auth0 4.11.0 → 5.20.0

data/README.md

@@ -1,14 +1,38 @@
-# Auth0 - Ruby
+![ruby-auth0](https://cdn.auth0.com/website/sdks/banners/ruby-auth0-banner.png)
+
+Ruby API client for the [Auth0](https://auth0.com) platform.
 
 [![CircleCI](https://img.shields.io/circleci/project/github/auth0/ruby-auth0/master.svg)](https://circleci.com/gh/auth0/ruby-auth0)
 [![Gem Version](https://badge.fury.io/rb/auth0.svg)](http://badge.fury.io/rb/auth0)
 [![codecov](https://codecov.io/gh/auth0/ruby-auth0/branch/master/graph/badge.svg)](https://codecov.io/gh/auth0/ruby-auth0)
 [![Yard Docs](http://img.shields.io/badge/yard-docs-blue.svg)](http://www.rubydoc.info/github/auth0/ruby-auth0/master/frames)
 [![MIT licensed](https://img.shields.io/dub/l/vibe-d.svg?style=flat)](https://github.com/auth0/ruby-auth0/blob/master/LICENSE)
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/auth0/ruby-auth0)
 
-Ruby API client for the [Auth0](https://auth0.com) platform.
+<div>
+📚 <a href="#documentation">Documentation</a> - 🚀 <a href="#getting-started">Getting started</a> - 💻 <a href="#api-reference">API reference</a> - 💬 <a href="#feedback">Feedback</a>
+</div>
+
+> [!NOTE]
+> **[v6.0.0.beta.1](https://github.com/auth0/ruby-auth0/releases/tag/v6.0.0.beta.1) is now available!** This release features a completely rewritten Management API client, auto-generated from the Auth0 OpenAPI spec using [Fern](https://buildwithfern.com/), with strongly-typed responses, built-in pagination, and automatic token management.
+>
+> ```bash
+> gem install auth0 --pre
+> ```
+>
+> We'd love your feedback - please [open an issue](https://github.com/auth0/ruby-auth0/issues/new) if you encounter any problems.
+>
+> 📖 [Migration Guide](https://github.com/auth0/ruby-auth0/blob/v6/v6_MIGRATION_GUIDE.md) ・ [Changelog](https://github.com/auth0/ruby-auth0/blob/v6/CHANGELOG.md) ・ [API Reference](https://github.com/auth0/ruby-auth0/blob/v6/reference.md)
+
+## Documentation
+
+- [API documentation](https://www.rubydoc.info/gems/auth0) - documentation auto-generated from the code comments that explains all the available features
+- [Examples](https://github.com/auth0/ruby-auth0/blob/master/EXAMPLES.md) - examples that demonstrate the different ways in which this SDK can be used
+- [Docs Site](https://auth0.com/docs) - explore our Docs site and learn more about Auth0
 
-## Installation
+## Getting Started
+
+### Installation
 
 This gem can be installed directly:
 
@@ -16,96 +40,48 @@ This gem can be installed directly:
 $ gem install auth0
 ```
 
-... or with [Bundler](https://bundler.io/man/bundle-add.1.html):
+or with [Bundler](https://bundler.io/man/bundle-add.1.html):
 
 ```bash
 bundle add auth0
 ```
 
-## API Documentation
-
-You can build the API documentation with the following:
-
-```bash
-bundle exec rake documentation
-```
+### Usage
 
-To view the generated documentation, open `doc/Auth0/Api.html` .
-
-## Management API v2
-
-This SDK provides access to the [Management API v2](https://auth0.com/docs/api/management/v2) via modules that help create clear and accurate calls. Most of the interaction is done through the `Auth0Client` class, instantiated with the required credentials.
-
-As a simple example of how to get started, we'll create an admin route to point to a list of all users from Auth0:
-
-```ruby
-# config/routes.rb
-Rails.application.routes.draw do
-  # ...
-  get 'admin/users', to: 'all_users#index'
-  # ...
-end
-```
-
-... and a Controller to handle that route:
+Create an instance of `Auth0Client` to access properties and methods of the authentication and management APIs:
 
 ```ruby
-# app/controllers/all_users_controllers.rb
 require 'auth0'
 
-class AllUsersController < ApplicationController
-  # Get all users from Auth0 with "auth0" in their email.
-  def index
-    @params = {
-      q: "email:*auth0*",
-      fields: 'email,user_id,name',
-      include_fields: true,
-      page: 0,
-      per_page: 50
-    }
-    @users = auth0_client.users @params
-  end
-
-  private
-
-  # Setup the Auth0 API connection.
-  def auth0_client
-    @auth0_client ||= Auth0Client.new(
-      client_id: ENV['AUTH0_RUBY_CLIENT_ID'],
-      client_secret: ENV['AUTH0_RUBY_CLIENT_SECRET'],
-      # If you pass in a client_secret value, the SDK will automatically try to get a
-      # Management API token for this application. Make sure your Application can make a
-      # Client Credentials grant (Application settings in Auth0 > Advanced > Grant Types
-      # tab) and that the Application is authorized for the Management API:
-      # https://auth0.com/docs/api-auth/config/using-the-auth0-dashboard
-      #
-      # Otherwise, you can pass in a Management API token directly for testing or temporary
-      # access using the key below.
-      # token: ENV['AUTH0_RUBY_API_TOKEN'],
-      domain: ENV['AUTH0_RUBY_DOMAIN'],
-      api_version: 2,
-      timeout: 15 # optional, defaults to 10
-    )
-  end
-end
+client = Auth0Client.new(
+  client_id: ENV['AUTH0_RUBY_CLIENT_ID'],
+  client_secret: ENV['AUTH0_RUBY_CLIENT_SECRET'],
+  domain: ENV['AUTH0_RUBY_DOMAIN'],
+  # If you pass in a client_secret value, the SDK will automatically try to get a
+  # Management API token for this application. Make sure your Application can make a
+  # Client Credentials grant (Application settings in Auth0 > Advanced > Grant Types
+  # tab) and that the Application is authorized for the Management API:
+  # https://auth0.com/docs/api-auth/config/using-the-auth0-dashboard
+  #
+  # Otherwise, you can pass in a Management API token directly for testing or temporary
+  # access using the key below.
+  # token: ENV['AUTH0_RUBY_API_TOKEN'],
+  #
+  # When passing a token, you can also specify when the token expires in seconds from epoch. Otherwise, expiry is set
+  # by default to an hour from now.
+  # token_expires_at: Time.now.to_i + 86400
+)
 ```
 
-In this example, we're using environment variables to store the values needed to connect to Auth0 and authorize. The `token` used above is an API token for the Management API with the scopes required to perform a specific action (in this case `read:users`). These tokens can be [generated manually](https://auth0.com/docs/api/management/v2/tokens#get-a-token-manually) using a test Application or with the [Application](https://manage.auth0.com/#/applications) being used for your project.
-
-Finally, we'll add a view to display the results:
+If `token` is omitted, the SDK will attempt to fetch a new token using the `client_credentials` grant, provided that `client_id` and `client_secret` are provided in the configuration. Once the token is about to expire (or has already expired), a new token will be fetched and cached for future calls.
 
-```ruby
-# app/views/all_users/index.html.erb
-<h1>Users</h1>
-<%= debug @params %>
-<%= debug @users %>
-```
+For this to work, ensure your application can make a Client Credentials grant (Application settings in Auth0 > Advanced > Grant Types tab) and that the application is authorized for the Management API: https://auth0.com/docs/api-auth/config/using-the-auth0-dashboard
 
-This should show the parameters passed to the `users` method and a list of users that matched the query (or an empty array if none).
+## Authentication API Client
 
-## Authentication
+This SDK provides access to [Authentication API](https://auth0.com/docs/api/authentication) endpoints with the `Auth0::API::AuthenticationEndpoints` module.
 
-In addition to the Management API, this SDK also provides access to [Authentication API](https://auth0.com/docs/api/authentication) endpoints with the `Auth0::API::AuthenticationEndpoints` module. For basic login capability, we suggest using our OmniAuth stategy [detailed here](https://auth0.com/docs/quickstart/webapp/rails/01-login). Other authentication tasks currently supported are:
+For basic login capability, we suggest using our OmniAuth stategy [detailed here](https://auth0.com/docs/quickstart/webapp/rails/01-login). Other authentication tasks currently supported are:
 
 - Register a new user with a database connection using the `signup` method.
 - Redirect a user to the universal login page for authentication using the `authorization_url` method.
@@ -118,43 +94,13 @@ In addition to the Management API, this SDK also provides access to [Authenticat
 
 Please note that this module implements endpoints that might be deprecated for newer tenants. If you have any questions about how and when the endpoints should be used, consult the [documentation](https://auth0.com/docs/api/authentication) or ask in our [Community forums](https://community.auth0.com/tags/wordpress).
 
-## Development
+## Management API Client
 
-In order to set up the local environment you'd have to have Ruby installed and a few global gems used to run and record the unit tests. A working Ruby version can be taken from the [CI script](/.circleci/config.yml). At the moment of this writting we're using Ruby `2.5.7`.
+This SDK provides access to the [Management API](https://auth0.com/docs/api/management/v2) via modules that help create clear and accurate calls. Most of the interaction is done through the `Auth0Client` class, instantiated with the required credentials.
 
-> It is expected that every Pull Request introducing a fix, change or feature contains enough test coverage to assert the new behavior.
+For an example of using the management API client to read of users, see the [examples document](https://github.com/auth0/ruby-auth0/blob/master/EXAMPLES.md).
 
-### Running the tests
-
-Install the gems required for this project.
-
-```bash
-bundle install
-```
-
-Finally, run the tests.
-
-```bash
-bundle exec rake test
-```
-
-#### Running only unit tests
-
-You can run only the unit tests and ignore the integration tests by running the following:
-
-```bash
-bundle exec rake spec
-```
-
-#### Running only integration tests
-
-You can run only the unit tests and ignore the integration tests by running the following:
-
-```bash
-bundle exec rake integration
-```
-
-## More Information
+## Further reading
 
 - [Login using OmniAuth](https://auth0.com/docs/quickstart/webapp/rails/01-login)
 - [API authentication in Ruby](https://auth0.com/docs/quickstart/backend/ruby)
@@ -162,30 +108,35 @@ bundle exec rake integration
 - [Managing authentication with Auth0 (blog)](https://auth0.com/blog/rails-5-with-auth0/)
 - [Ruby on Rails workflow with Docker (blog)](https://auth0.com/blog/ruby-on-rails-killer-workflow-with-docker-part-1/)
 
-## What is Auth0?
-
-Auth0 helps you to:
+## Feedback
 
-- Add authentication with [multiple authentication sources](https://docs.auth0.com/identityproviders), either social like **Google, Facebook, Microsoft Account, LinkedIn, GitHub, Twitter, Box, Salesforce** among others, or enterprise identity systems like **Windows Azure AD, Google Apps, Active Directory, ADFS or any SAML Identity Provider**.
-- Add authentication through more traditional **[username/password databases](https://docs.auth0.com/mysql-connection-tutorial)**.
-- Add support for **[linking different user accounts](https://docs.auth0.com/link-accounts)** with the same user.
-- Support for generating signed [JSON Web Tokens](https://docs.auth0.com/jwt) to call your APIs and **flow the user identity** securely.
-- Analytics of how, when, and where users are logging in.
-- Pull data from other sources and add it to the user profile with [JavaScript rules](https://docs.auth0.com/rules).
+### Contributing
 
-## Create a free Auth0 Account
+We appreciate feedback and contribution to this repo! Before you get started, please see the following:
 
-1. Go to [Auth0](https://auth0.com) and click Sign Up.
-2. Use Google, GitHub or Microsoft Account to login.
+- [Auth0's general contribution guidelines](https://github.com/auth0/open-source-template/blob/master/GENERAL-CONTRIBUTING.md)
+- [Auth0's code of conduct guidelines](https://github.com/auth0/open-source-template/blob/master/CODE-OF-CONDUCT.md)
 
-## Issue Reporting
+### Raise an issue
 
-If you find a bug or have a feature request, please report them in this repository's [Issues tab](https://github.com/auth0/ruby-auth0/issues). Please do not report security vulnerabilities on the public GitHub issue tracker. The [Responsible Disclosure Program](https://auth0.com/whitehat) details the procedure for disclosing security issues.
+To provide feedback or report a bug, please [raise an issue on our issue tracker](https://github.com/auth0/ruby-auth0/issues).
 
-## Author
+### Vulnerability Reporting
 
-[Auth0](https://auth0.com)
+Please do not report security vulnerabilities on the public GitHub issue tracker. The [Responsible Disclosure Program](https://auth0.com/whitehat) details the procedure for disclosing security issues.
 
-## License
+---
 
-This project is licensed under the MIT license. See the [LICENSE](LICENSE) file for more info.
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://cdn.auth0.com/website/sdks/logos/auth0_dark_mode.png" width="150">
+    <source media="(prefers-color-scheme: light)" srcset="https://cdn.auth0.com/website/sdks/logos/auth0_light_mode.png" width="150">
+    <img alt="Auth0 Logo" src="https://cdn.auth0.com/website/sdks/logos/auth0_light_mode.png" width="150">
+  </picture>
+</p>
+<p align="center">
+  Auth0 is an easy to implement, adaptable authentication and authorization platform. To learn more checkout <a href="https://auth0.com/why-auth0">Why Auth0?</a>
+</p>
+<p align="center">
+  This project is licensed under the MIT license. See the <a href="https://github.com/auth0/ruby-auth0/blob/master/LICENSE"> LICENSE</a> file for more info.
+</p>

data/auth0.gemspec

@@ -11,25 +11,22 @@ Gem::Specification.new do |s|
   s.summary     = 'Auth0 API Client'
   s.description = 'Ruby toolkit for Auth0 API https://auth0.com.'
 
-  s.files         = `git ls-files`.split("\n")
-  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
-  s.executables   = `git ls-files -- bin/*`.split("\n").map { |f| File.basename(f) }
+  s.files         = Dir['lib/**/*.rb'] + %w[LICENSE README.md CHANGELOG.md auth0.gemspec .version]
   s.require_paths = ['lib']
 
-  s.add_runtime_dependency 'rest-client', '~> 2.0.0'
+  s.add_runtime_dependency 'rest-client', '~> 2.1'
+  s.add_runtime_dependency 'jwt', '>= 2.7', '< 4.0'
+  s.add_runtime_dependency 'zache', '~> 0.12'
+  s.add_runtime_dependency 'addressable', '~> 2.8'
+  s.add_runtime_dependency 'retryable', '~> 3.0'
 
+  s.add_development_dependency 'bundler'
   s.add_development_dependency 'rake', '~> 13.0'
   s.add_development_dependency 'fuubar', '~> 2.0'
   s.add_development_dependency 'guard-rspec', '~> 4.5' unless ENV['CIRCLECI']
-  s.add_development_dependency 'dotenv-rails', '~> 2.0'
-  s.add_development_dependency 'pry', '~> 0.10'
-  s.add_development_dependency 'pry-nav', '~> 0.2.4'
-  s.add_development_dependency 'rspec', '~> 3.1', '>= 3.1.0'
-  s.add_development_dependency 'rack-test', '~> 0.6'
-  s.add_development_dependency 'rack', '~> 2.1.2'
+  s.add_development_dependency 'dotenv', '~> 3.0'
+  s.add_development_dependency 'rspec', '~> 3.11'
   s.add_development_dependency 'simplecov', '~> 0.9'
-  s.add_development_dependency 'faker', '~> 1.4'
-  s.add_development_dependency 'yard', '~> 0.9.12'
-  s.add_development_dependency 'gem-release', '~> 0.7'
+  s.add_development_dependency 'faker', '~> 2.0'
   s.license = 'MIT'
 end

data/lib/auth0/algorithm.rb

@@ -0,0 +1,5 @@
+module Auth0
+  module Algorithm
+    include Auth0::Mixins::Validation::Algorithm
+  end
+end