auth0 4.4.0 → 4.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 50bf71ae1695273ad9f86de42239cff42c681c8c0841fde4f2002c1e045940b0
-  data.tar.gz: 4956b4307c7c2d93fd1d8e955c2f77fc1c6fdd57232674c1dc50a1d95507097b
+  metadata.gz: 8e2d0aa18336dc8b5427ef196eebe49f8232e2776c90307d1c38e2129d8704e8
+  data.tar.gz: acfe0224309b9b2de3faa249f65e40654586f446494b53044d27cea4ad60b5da
 SHA512:
-  metadata.gz: 7cdbe3de507568e75af632efdd47c005c71425f0c884fb66863d63325ac5f4d162e0d129d648c306ad5747bb6d6634819431cd566420e06b87611b384f91b632
-  data.tar.gz: cc4d1e11073b11d8412615bf57586e3f173d649ae48f47b212104de5aaca6b294d86f06eeb3bbb7f13c3016a3ef4a2f57d5e6b87b08db776e730e36e9eb1a566
+  metadata.gz: 194975ab5dce4b26bae48fdf25b143a7ae7ff47898e500dc0a49913bcecb54276919e79a70a8a5b2d1d064d176f15cd394bd58d26241f2388c35535ebf5614a5
+  data.tar.gz: 29bde6a3792287ecae9d8559e0b52ed8fc57407a183665944e1883cb3ee64dede9169a8525b191042c86b6c05a2833b34b592d60ff58ec97161d427fa4b84f49

data/CHANGELOG.md

@@ -1,42 +1,78 @@
 # Change Log
 
-## [v4.4.0](https://github.com/auth0/ruby-auth0/tree/v4.4.0) (2018-02-19)
-[Full Changelog](https://github.com/auth0/ruby-auth0/compare/v4.2.0...v4.4.0)
-
-Note: If you are using the `login` endpoint, you will need to enable the [Resource Owner Password Grant](https://auth0.com/docs/clients/client-grant-types).
+## [v4.5.0](https://github.com/auth0/ruby-auth0/tree/v4.5.0) (2018-07-26)
+[Full Changelog](https://github.com/auth0/ruby-auth0/compare/v4.4.0...v4.5.0)
 
 **Closed issues:**
 
-- Vulnerable dependency: yard. [\#99]
-https://github.com/auth0/ruby-auth0/issues/99
+- New version with updated rest-client dependency [\#93](https://github.com/auth0/ruby-auth0/issues/93)
+- Bug?: `result` from auth0/mixins/httpproxy.rb returns 'nil' [\#88](https://github.com/auth0/ruby-auth0/issues/88)
+- import\_users fails with EOFError [\#56](https://github.com/auth0/ruby-auth0/issues/56)
+- Using inside of a Rails API [\#55](https://github.com/auth0/ruby-auth0/issues/55)
+- Add documentation? [\#102](https://github.com/auth0/ruby-auth0/issues/102)
+- logout\_url does not include client\_id parameter [\#81](https://github.com/auth0/ruby-auth0/issues/81)
+
+**Merged pull requests:**
+
+- Correctly default grant\_type to 'password' in login method [\#107](https://github.com/auth0/ruby-auth0/pull/107) ([psparrow](https://github.com/psparrow))
+- Add additional parameters for WS-Fed URL [\#123](https://github.com/auth0/ruby-auth0/pull/123) ([joshcanhelp](https://github.com/joshcanhelp))
+- Deprecate Authentication API endpoints [\#121](https://github.com/auth0/ruby-auth0/pull/121) ([joshcanhelp](https://github.com/joshcanhelp))
+- Clean up auth endpoint tests [\#120](https://github.com/auth0/ruby-auth0/pull/120) ([joshcanhelp](https://github.com/joshcanhelp))
+- Fix docblocks for Authentication API endpoints [\#119](https://github.com/auth0/ruby-auth0/pull/119) ([joshcanhelp](https://github.com/joshcanhelp))
+- Add Client ID to logout\_url [\#118](https://github.com/auth0/ruby-auth0/pull/118) ([joshcanhelp](https://github.com/joshcanhelp))
+- Add pagination and tests for Rules endpoint [\#117](https://github.com/auth0/ruby-auth0/pull/117) ([joshcanhelp](https://github.com/joshcanhelp))
+- Add pagination and tests for Client Grants [\#116](https://github.com/auth0/ruby-auth0/pull/116) ([joshcanhelp](https://github.com/joshcanhelp))
+- Add search\_engine parameter to Users endpoint + tests [\#115](https://github.com/auth0/ruby-auth0/pull/115) ([joshcanhelp](https://github.com/joshcanhelp))
+- Improve README [\#114](https://github.com/auth0/ruby-auth0/pull/114) ([joshcanhelp](https://github.com/joshcanhelp))
+- Add pagination and tests to Clients and Connections endpoints [\#113](https://github.com/auth0/ruby-auth0/pull/113) ([joshcanhelp](https://github.com/joshcanhelp))
+- Use Secure RubyGems Source [\#112](https://github.com/auth0/ruby-auth0/pull/112) ([markprovan](https://github.com/markprovan))
 
-- Unsupported on latest ruby version. [\#83]
-https://github.com/auth0/ruby-auth0/issues/83
+## [v4.4.0](https://github.com/auth0/ruby-auth0/tree/v4.4.0) (2018-02-19)
+[Full Changelog](https://github.com/auth0/ruby-auth0/compare/v4.3.0...v4.4.0)
+
+**Closed issues:**
 
-- Outdated dependencies in ror-api example. [\#75]
-https://github.com/auth0/ruby-auth0/issues/75
+- Authentication Login is using `/oauth/ro`.  [\#89](https://github.com/auth0/ruby-auth0/issues/89)
 
-- Authentication Login is using `/oauth/ro` [\#89]
-https://github.com/auth0/ruby-auth0/issues/89
+## [v4.3.0](https://github.com/auth0/ruby-auth0/tree/v4.3.0) (2018-02-19)
+[Full Changelog](https://github.com/auth0/ruby-auth0/compare/v4.2.0...v4.3.0)
 
 **Merged pull requests:**
 
+- Fix script publish gem [\#106](https://github.com/auth0/ruby-auth0/pull/106) ([alexisluque](https://github.com/alexisluque))
 - Add support to /api/v2/users-by-email [\#105](https://github.com/auth0/ruby-auth0/pull/105) ([edgurgel](https://github.com/edgurgel))
+- Update /login to use /oauth/token [\#94](https://github.com/auth0/ruby-auth0/pull/94) ([Zensaburou](https://github.com/Zensaburou))
+- Fix error in the readme regarding timeouts [\#90](https://github.com/auth0/ruby-auth0/pull/90) ([ksamc](https://github.com/ksamc))
 
 ## [v4.2.0](https://github.com/auth0/ruby-auth0/tree/v4.2.0) (2018-02-15)
 [Full Changelog](https://github.com/auth0/ruby-auth0/compare/v4.1.0...v4.2.0)
 
 **Closed issues:**
 
-- Vulnerable dependency: yard. [\#99]
-https://github.com/auth0/ruby-auth0/issues/99
+- Vulnerable dependency: yard [\#99](https://github.com/auth0/ruby-auth0/issues/99)
+- post\_password\_change results in payload validation error [\#84](https://github.com/auth0/ruby-auth0/issues/84)
+- Unsupported on latest ruby version \(2.4.0\) [\#83](https://github.com/auth0/ruby-auth0/issues/83)
+- Adding a resource server breaks authentication. [\#76](https://github.com/auth0/ruby-auth0/issues/76)
+- outdated dependencies in ror-api example [\#75](https://github.com/auth0/ruby-auth0/issues/75)
 
-- Unsupported on latest ruby version. [\#83]
-https://github.com/auth0/ruby-auth0/issues/83
-
-- Outdated dependencies in ror-api example. [\#75]
-https://github.com/auth0/ruby-auth0/issues/75
+**Merged pull requests:**
 
+- Add scripts and Dockerfile to publish SDK on rubygems [\#104](https://github.com/auth0/ruby-auth0/pull/104) ([alexisluque](https://github.com/alexisluque))
+- Fix typo [\#103](https://github.com/auth0/ruby-auth0/pull/103) ([coisnepe](https://github.com/coisnepe))
+- Fix tests [\#101](https://github.com/auth0/ruby-auth0/pull/101) ([alexisluque](https://github.com/alexisluque))
+- Update outdated dependency [\#100](https://github.com/auth0/ruby-auth0/pull/100) ([alexisluque](https://github.com/alexisluque))
+- Fix build [\#98](https://github.com/auth0/ruby-auth0/pull/98) ([alexisluque](https://github.com/alexisluque))
+- Add delay to integration test [\#97](https://github.com/auth0/ruby-auth0/pull/97) ([alexisluque](https://github.com/alexisluque))
+- Fix build [\#96](https://github.com/auth0/ruby-auth0/pull/96) ([alexisluque](https://github.com/alexisluque))
+- Removed reference to API v1 [\#91](https://github.com/auth0/ruby-auth0/pull/91) ([aaguiarz](https://github.com/aaguiarz))
+- Update rest-client version to v2 [\#87](https://github.com/auth0/ruby-auth0/pull/87) ([hzalaz](https://github.com/hzalaz))
+- Introduce and raise exception for timeout [\#85](https://github.com/auth0/ruby-auth0/pull/85) ([anderslemke](https://github.com/anderslemke))
+- corrected missing comma in example code of readme.md [\#79](https://github.com/auth0/ruby-auth0/pull/79) ([drewnichols](https://github.com/drewnichols))
+- Resolve v1 API example error [\#78](https://github.com/auth0/ruby-auth0/pull/78) ([jesseproudman](https://github.com/jesseproudman))
+- updated dependencies in ror api example. Fix \#75 [\#77](https://github.com/auth0/ruby-auth0/pull/77) ([Amialc](https://github.com/Amialc))
+- Add a badge to documentation [\#74](https://github.com/auth0/ruby-auth0/pull/74) ([amingilani](https://github.com/amingilani))
+- Typo [\#73](https://github.com/auth0/ruby-auth0/pull/73) ([amingilani](https://github.com/amingilani))
+- Add how to generate documentation to the README.md + patch\_user [\#72](https://github.com/auth0/ruby-auth0/pull/72) ([ignaciojonas](https://github.com/ignaciojonas))
 
 ## [v4.1.0](https://github.com/auth0/ruby-auth0/tree/v4.1.0) (2016-07-25)
 [Full Changelog](https://github.com/auth0/ruby-auth0/compare/v4.0.0...v4.1.0)

data/Gemfile

@@ -1,4 +1,4 @@
-source 'http://rubygems.org'
+source 'https://rubygems.org'
 
 # Specify your gem's dependencies in auth0.gemspec
 gemspec

data/README.md

@@ -1,76 +1,130 @@
-Ruby api client for [Auth0](https://auth0.com) platform
-
 [![Build Status](https://travis-ci.org/auth0/ruby-auth0.svg?branch=master)](https://travis-ci.org/auth0/ruby-auth0)
 [![Gem Version](https://badge.fury.io/rb/auth0.svg)](http://badge.fury.io/rb/auth0)
 [![Coverage Status](https://coveralls.io/repos/auth0/ruby-auth0/badge.svg?branch=master)](https://coveralls.io/r/auth0/ruby-auth0?branch=master)
-[![Dependency Status](https://gemnasium.com/auth0/ruby-auth0.svg)](https://gemnasium.com/auth0/ruby-auth0)
 [![Yard Docs](http://img.shields.io/badge/yard-docs-blue.svg)](http://www.rubydoc.info/github/auth0/ruby-auth0/master/frames)
 
+Ruby API client for the [Auth0](https://auth0.com) platform.
+
 ## Installation
 
+This gem can be installed directly:
+
 ``` bash
 $ gem install auth0
 ```
 
-or with [Bundler](http://bundler.io)
+... or with [Bundler](https://bundler.io/man/bundle-add.1.html):
 
-```ruby
-gem 'auth0'
+```bash
+bundle add auth0
 ```
 
-## Basic usage
+## API Documentation
 
-Using [APIv2](https://auth0.com/docs/api/v2)
+You can build the API documentation with the following:
 
-```ruby
-require "auth0"
+``` bash
+bundle exec rake documentation
+```
 
-auth0 = Auth0Client.new(
-  :client_id => "YOUR CLIENT ID",
-  :token => "YOUR JWT HERE",
-  :domain => "<YOUR ACCOUNT>.auth0.com",
-  :api_version => 2
-)
+To view the generated documentation, open `doc/Auth0/Api.html`
 
-puts auth0.get_users
-```
+## Management API v2
 
-### Timeout
-You can setup a custom timeout in the Auth0Client. By default it is set to 10 seconds.
+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
-require "auth0"
+# config/routes.rb
+Rails.application.routes.draw do
+  # ...
+  get 'admin/users', to: 'all_users#index'
+  # ...
+end
+```
 
-auth0 = Auth0Client.new(
-  :client_id => "YOUR CLIENT ID",
-  :token => "YOUR JWT HERE",
-  :domain => "<YOUR ACCOUNT>.auth0.com",
-  :timeout => 15
-)
+... and a Controller to handle that route:
 
-puts auth0.get_users
+```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'],
+      token: ENV['AUTH0_RUBY_API_TOKEN'],
+      domain: ENV['AUTH0_RUBY_DOMAIN'],
+      api_version: 2,
+      timeout: 15 # optional, defaults to 10
+    )
+  end
+end
 ```
 
-## API Documentation
+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.
 
-Build API docs locally
+Finally, we'll add a view to display the results:
 
-``` bash
-bundle exec rake documentation
+```ruby
+# app/views/all_users/index.html.erb
+<h1>Users</h1>
+<%= debug @params %>
+<%= debug @users %>
 ```
 
-To view API docs, go to `doc` folder and open `index.html`
+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
+
+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:
+
+* 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.
+* Log a user in to a highly trusted app with the [Resource Owner Password grant](https://auth0.com/docs/api-auth/tutorials/password-grant) using the `login` method.
+* Exchange an authorization code for an access token on callback using the `obtain_user_tokens` method (see the note on state validation below).
+* Send a change password email to a database connection user using the `change_password` method.
+* Log a user out of Auth0 with the `logout_url` method.
+
+**Important note on state validation**: If you choose to implement a login flow callback youself, it is important to generate and store a `state` value, pass that value to Auth0 in the `authorization_url` method, and validate it in your callback URL before calling `obtain_user_tokens`. For more information on state validation, [please see our documentation](https://auth0.com/docs/protocols/oauth2/oauth-state). 
+
+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).
+
+
+## More Information
+
+* [Login using OmniAuth](https://auth0.com/docs/quickstart/webapp/rails/01-login)
+* [API authentication in Ruby](https://auth0.com/docs/quickstart/backend/ruby)
+* [API authentication in Rails](https://auth0.com/docs/quickstart/backend/rails)
+* [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:
 
-* Add authentication with [multiple authentication sources](https://docs.auth0.com/identityproviders), either social like **Google, Facebook, Microsoft Account, LinkedIn, GitHub, Twitter, Box, Salesforce, amont others**, or enterprise identity systems like **Windows Azure AD, Google Apps, Active Directory, ADFS or any SAML Identity Provider**.
+* 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, through [JavaScript rules](https://docs.auth0.com/rules).
+* 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).
 
 ## Create a free Auth0 Account
 
@@ -79,7 +133,7 @@ Auth0 helps you to:
 
 ## Issue Reporting
 
-If you have found a bug or if you have a feature request, please report them at this repository issues section. 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.
+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.
 
 ## Author
 

data/lib/auth0/api/authentication_endpoints.rb

@@ -1,14 +1,14 @@
 # rubocop:disable Metrics/ModuleLength
 module Auth0
   module Api
-    # {https://auth0.com/docs/auth-api}
-    # Methods to use the authentication endpoints
+    # {https://auth0.com/docs/api/authentication}
+    # Methods to use the Authentication API
     module AuthenticationEndpoints
       UP_AUTH = 'Username-Password-Authentication'.freeze
       JWT_BEARER = 'urn:ietf:params:oauth:grant-type:jwt-bearer'.freeze
 
-      # Retrives an access token
-      # @see https://auth0.com/docs/auth-api#!#post--oauth-access_token
+      # Retrieve an access token.
+      # @see https://auth0.com/docs/api/authentication#client-credentials
       # @param access_token [string] Social provider's access_token
       # @param connection [string] Currently, this endpoint only works for Facebook, Google, Twitter and Weibo
       # @return [json] Returns the access token
@@ -22,12 +22,12 @@ module Auth0
         end
       end
 
-      # Gets the user tokens using the code obtained through passive authentication in the specified connection
-      # @see https://auth0.com/docs/auth-api#!#post--oauth-access_token
+      # Get access and ID tokens using an Authorization Code.
+      # @see https://auth0.com/docs/api/authentication#authorization-code
+      # @param code [string] The access code obtained through passive authentication
+      # @param redirect_uri [string] Url to redirect after authorization
       # @param connection [string] Currently, this endpoint only works for Facebook, Google, Twitter and Weibo
       # @param scope [string] Defaults to openid. Can be 'openid name email', 'openid offline_access'
-      # @param redirect_uri [string] Url to redirect after authorization
-      # @param redirect_uri [string] The access code obtained through passive authentication
       # @return [json] Returns the access_token and id_token
       def obtain_user_tokens(code, redirect_uri, connection = 'facebook', scope = 'openid')
         raise Auth0::InvalidParameter, 'Must supply a valid code' if code.to_s.empty?
@@ -44,15 +44,15 @@ module Auth0
         post('/oauth/token', request_params)
       end
 
-      # Logins using username/password
-      # @see https://auth0.com/docs/auth-api#!#post--oauth-ro
-      # @param username [string] Username
-      # @param password [string] User's password
-      # @param scope [string] Defaults to openid. Can be 'openid name email', 'openid offline_access'
+      # Get access and ID tokens using Resource Owner Password.
+      # @see https://auth0.com/docs/api/authentication#resource-owner-password
+      # @param username [string] Username or email
+      # @param password [string] Password
       # @param id_token [string] Token's id
-      # @param connection_name [string] Connection name. Works for database connections, passwordless connections,
-      # Active Directory/LDAP, Windows Azure AD and ADF
-      # @return [json] Returns the access token and id token
+      # @param connection_name [string] Connection name; use a database or
+      #    passwordless connection, Active Directory/LDAP, Windows Azure or ADF
+      # @param options [hash] Additional options - :scope, :grant_type, :device
+      # @return [json] Returns the access_token and id_token
       def login(username, password, id_token = nil, connection_name = UP_AUTH, options = {})
         raise Auth0::InvalidParameter, 'Must supply a valid username' if username.to_s.empty?
         raise Auth0::InvalidParameter, 'Must supply a valid password' if password.to_s.empty?
@@ -63,80 +63,180 @@ module Auth0
           password:      password,
           scope:         options.fetch(:scope, 'openid'),
           connection:    connection_name,
-          grant_type:    options.fetch(:grant_type, password),
+          grant_type:    options.fetch(:grant_type, 'password'),
           id_token:      id_token,
           device:        options.fetch(:device, nil)
         }
         post('/oauth/token', request_params)
       end
 
-      # Signup using username/password
-      # @see https://auth0.com/docs/auth-api#!#post--dbconnections-signup
-      # @param email [string] User email
-      # @param password [string] User's password
-      # @param connection_name [string] Connection name. Works for database connections.
+      # Sign up with a database connection using a username and password.
+      # @see https://auth0.com/docs/api/authentication#signup
+      # @param email [string] New user's email
+      # @param password [string] New user's password
+      # @param connection_name [string] Database connection name
       # @return [json] Returns the created user
       def signup(email, password, connection_name = UP_AUTH)
         raise Auth0::InvalidParameter, 'Must supply a valid email' if email.to_s.empty?
         raise Auth0::InvalidParameter, 'Must supply a valid password' if password.to_s.empty?
         request_params = {
-          client_id:  @client_id,
           email:      email,
+          password:   password,
           connection: connection_name,
-          password:   password
+          client_id:  @client_id
         }
         post('/dbconnections/signup', request_params)
       end
 
-      # Asks to change a password for a given user.
-      # Send an email to the user.
-      # @see https://auth0.com/docs/auth-api#!#post--dbconnections-change_password
-      # @param email [string] User email
-      # @param password [string] User's new password
-      # @param connection_name [string] Connection name. Works for database connections.
+      # Change a user's password or trigger a password reset email.
+      # @see https://auth0.com/docs/api/authentication#change-password
+      # @see https://auth0.com/docs/connections/database/password-change
+      # @param email [string] User's current email
+      # @param password [string] User's new password; empty to trigger a
+      #   password reset email
+      # @param connection_name [string] Database connection name
       def change_password(email, password, connection_name = UP_AUTH)
         raise Auth0::InvalidParameter, 'Must supply a valid email' if email.to_s.empty?
         request_params = {
-          client_id:  @client_id,
           email:      email,
+          password:   password,
           connection: connection_name,
-          password:   password
+          client_id:  @client_id
         }
         post('/dbconnections/change_password', request_params)
       end
 
-      # Start passwordless workflow sending an email
-      # @see https://auth0.com/docs/auth-api#!#post--with_email
-      # @param email [string] User email
-      # @param send [string] Defaults to 'link'. Can be 'code'. You can then authenticate with this user opening the link
-      # @param auth_params [hash] Append/override parameters to the link (like scope, redirect_uri, protocol, etc.)
+      # Start Passwordless email login flow.
+      # @see https://auth0.com/docs/api/authentication#get-code-or-link
+      # @see https://auth0.com/docs/connections/passwordless#passwordless-on-regular-web-apps
+      # @param email [string] Email to send a link or code
+      # @param send [string] Pass 'link' to send a magic link, 'code' to send a code
+      # @param auth_params [hash] Append or override the magic link parameters
       def start_passwordless_email_flow(email, send = 'link', auth_params = {})
         raise Auth0::InvalidParameter, 'Must supply a valid email' if email.to_s.empty?
         request_params = {
-          client_id:   @client_id,
-          connection:  'email',
           email:       email,
           send:        send,
-          authParams:  auth_params
+          authParams:  auth_params,
+          connection:  'email',
+          client_id:   @client_id
         }
         post('/passwordless/start', request_params)
       end
 
-      # Start passwordless workflow sending a SMS message
-      # @see https://auth0.com/docs/auth-api#!#post--with_sms
+      # Start Passwordless SMS login flow.
+      # @see https://auth0.com/docs/api/authentication#get-code-or-link
+      # @see https://auth0.com/docs/connections/passwordless#passwordless-on-regular-web-apps
       # @param phone_number [string] User's phone number.
       def start_passwordless_sms_flow(phone_number)
         raise Auth0::InvalidParameter, 'Must supply a valid phone number' if phone_number.to_s.empty?
         request_params = {
-          client_id:    @client_id,
+          phone_number: phone_number,
           connection:   'sms',
-          phone_number: phone_number
+          client_id:    @client_id
         }
         post('/passwordless/start', request_params)
       end
 
-      # Logins using phone number/verification code.
-      # @see https://auth0.com/docs/auth-api#!#post--ro_with_sms
+      # Retrive SAML 2.0 metadata XML for an Application.
+      # @see https://auth0.com/docs/api/authentication#get-metadata
+      # @return [xml] SAML 2.0 metadata
+      def saml_metadata
+        get("/samlp/metadata/#{@client_id}")
+      end
+
+      # Retrieve WS-Federation metadata XML for a tenant.
+      # @see https://auth0.com/docs/api/authentication#get-metadata36
+      # @return [xml] WS-Federation metadata
+      def wsfed_metadata
+        get('/wsfed/FederationMetadata/2007-06/FederationMetadata.xml')
+      end
+
+      # Return the user information based on the Auth0 access token.
+      # @see https://auth0.com/docs/api/authentication#get-user-info
+      # @return [json] User information based on the Auth0 access token
+      def user_info
+        get('/userinfo')
+      end
+
+      # Return an authorization URL.
+      # @see https://auth0.com/docs/api/authentication#authorization-code-grant
+      # @param redirect_uri [string] URL to redirect after authorization
+      # @param options [hash] Can contain response_type, connection, state and additional_parameters.
+      # @return [url] Authorization URL.
+      def authorization_url(redirect_uri, options = {})
+        raise Auth0::InvalidParameter, 'Must supply a valid redirect_uri' if redirect_uri.to_s.empty?
+        request_params = {
+          client_id: @client_id,
+          response_type: options.fetch(:response_type, 'code'),
+          connection: options.fetch(:connection, nil),
+          redirect_uri: redirect_uri,
+          state: options.fetch(:state, nil),
+          scope: options.fetch(:scope, nil)
+        }.merge(options.fetch(:additional_parameters, {}))
+
+        URI::HTTPS.build(host: @domain, path: '/authorize', query: to_query(request_params))
+      end
+
+      # Returns an Auth0 logout URL with a return URL.
+      # @see https://auth0.com/docs/api/authentication#logout
+      # @see https://auth0.com/docs/logout
+      # @param return_to [string] URL to redirect after logout.
+      # @param include_client [bool] Include the client_id in the logout URL.
+      # @param federated [boolean] Perform a federated logout.
+      # @return [url] Logout URI
+      def logout_url(return_to, include_client: false, federated: false)
+        request_params = {
+          returnTo: return_to,
+          client_id: include_client ? @client_id : nil,
+          federated: federated ? '1' : nil
+        }
+
+        URI::HTTPS.build(
+          host: @domain,
+          path: '/v2/logout',
+          query: to_query(request_params)
+        )
+      end
+
+      # Return a SAMLP URL.
+      # The SAML Request AssertionConsumerServiceURL will be used to POST back
+      # the assertion and it must match with the application callback URL.
+      # @see https://auth0.com/docs/api/authentication#accept-request
+      # @param connection [string] Connection to use; empty to show all
+      # @return [url] SAMLP URL
+      def samlp_url(connection = UP_AUTH)
+        request_params = {
+          connection: connection
+        }
+        URI::HTTPS.build(host: @domain, path: "/samlp/#{@client_id}", query: to_query(request_params))
+      end
+
+      # Return a WS-Federation URL.
+      # @see https://auth0.com/docs/api/authentication#accept-request35
+      # @param connection [string] Connection to use; empty to show all
+      # @param options [hash] Extra options; supports wtrealm, wctx, wreply
+      # @return [url] WS-Federation URL
+      def wsfed_url(connection = UP_AUTH, options = {})
+        request_params = {
+          whr: connection,
+          wtrealm: options[:wtrealm],
+          wctx: options[:wctx],
+          wreply: options[:wreply]
+        }
+
+        url_client_id = @client_id if !request_params[:wtrealm]
+        URI::HTTPS.build(
+          host: @domain,
+          path: "/wsfed/#{url_client_id}",
+          query: to_query(request_params)
+        )
+      end
+
+      # Login using phone number + verification code.
+      # @deprecated 4.5.0 - Legacy authentication pipeline; use a Password Grant
+      #   instead - https://auth0.com/docs/api-auth/tutorials/password-grant
+      # @see https://auth0.com/docs/api/authentication#resource-owner
       # @param phone_number [string] User's phone number.
       # @param code [string] Verification code.
       # @return [json] Returns the access token and id token
@@ -154,23 +254,10 @@ module Auth0
         post('/oauth/ro', request_params)
       end
 
-      # Retrives the SAML 2.0 metadata
-      # @see https://auth0.com/docs/auth-api#!#get--samlp--client_id-
-      # @return [xml] SAML 2.0 metadata
-      def saml_metadata
-        get("/samlp/metadata/#{@client_id}")
-      end
-
-      # Retrives the WS-Federation metadata
-      # @see https://auth0.com/docs/auth-api#!#get--wsfed--client_id-
-      # @return [xml] Federation Metadata
-      def wsfed_metadata
-        get('/wsfed/FederationMetadata/2007-06/FederationMetadata.xml')
-      end
-
-      # Validates a JSON Web Token (signature and expiration)
-      # @see https://auth0.com/docs/auth-api#!#post--tokeninfo
-      # @param id_token [string] Token's id.
+      # Validate a JSON Web Token (signature and expiration).
+      # @deprecated 4.5.0 - Legacy endpoint, use /userinfo instead.
+      # @see https://auth0.com/docs/api/authentication#get-token-info
+      # @param id_token [string] ID Token to use
       # @return User information associated with the user id (sub property) of the token.
       def token_info(id_token)
         raise Auth0::InvalidParameter, 'Must supply a valid id_token' if id_token.to_s.empty?
@@ -178,8 +265,10 @@ module Auth0
         post('/tokeninfo', request_params)
       end
 
-      # Refreshes a delegation token
-      # @see https://auth0.com/docs/auth-api#!#post--delegation
+      # Refresh a delegation token.
+      # @deprecated 4.5.0 - Feature is disabled, no replacement currently; see
+      #   https://auth0.com/docs/api-auth/tutorials/adoption/delegation
+      # @see https://auth0.com/docs/api/authentication#delegation
       # @param refresh_token [string] Token to refresh
       # @param target [string] Target to sign the new token.
       # @param scope [string] Defaults to openid. Can be 'openid name email'.
@@ -200,8 +289,10 @@ module Auth0
         post('/delegation', request_params)
       end
 
-      # Retrives a delegation token
-      # @see https://auth0.com/docs/auth-api#!#post--delegation
+      # Retrieve a delegation token.
+      # @deprecated 4.5.0 - Feature is disabled, no replacement currently; see
+      #   https://auth0.com/docs/api-auth/tutorials/adoption/delegation
+      # @see https://auth0.com/docs/api/authentication#delegation
       # @param id_token [string] Token's id.
       # @param target [string] Target to sign the new token.
       # @param scope [string] Defaults to openid. Can be 'openid name email'.
@@ -222,8 +313,9 @@ module Auth0
         post('/delegation', request_params)
       end
 
-      # Retrives an impersonation URL to login as another user
-      # @see https://auth0.com/docs/auth-api#!#post--users--user_id--impersonate
+      # Retrieve an impersonation URL to login as another user.
+      # @deprecated 4.5.0 - Feature is disabled.
+      # @see https://auth0.com/docs/api/authentication#impersonation
       # @param user_id [string] Impersonate user id
       # @param app_client_id [string] Application client id
       # @param impersonator_id [string] Impersonator user id id.
@@ -251,9 +343,12 @@ module Auth0
         authorization_header @token
         result
       end
+      # rubocop:enable Metrics/MethodLength, Metrics/AbcSize
 
-      # Unlinks a User
-      # @see https://auth0.com/docs/auth-api#!#post--unlink
+      # Unlink a user's account from the identity provider.
+      # @deprecated 4.5.0 - Endpoint is disabled in favor of the Management API;
+      #   see https://auth0.com/docs/migrations/guides/account-linking
+      # @see https://auth0.com/docs/api/authentication#unlink
       # @param access_token [string] Logged-in user access token
       # @param user_id [string] User Id
       def unlink_user(access_token, user_id)
@@ -266,72 +361,13 @@ module Auth0
         post('/unlink', request_params)
       end
 
-      # Returns the user information based on the Auth0 access token.
-      # @see https://auth0.com/docs/auth-api#!#get--userinfo
-      # @return [json] User information based on the Auth0 access token
-      def user_info
-        get('/userinfo')
-      end
-
-      # Returns an authorization URL, triggers a redirect.
-      # @see https://auth0.com/docs/auth-api#!#get--authorize_social
-      # @param redirect_uri [string] Url to redirect after authorization
-      # @param options [hash] Can contain response_type, connection, state and additional_parameters.
-      # @return [url] Authorization URL.
-      def authorization_url(redirect_uri, options = {})
-        raise Auth0::InvalidParameter, 'Must supply a valid redirect_uri' if redirect_uri.to_s.empty?
-        request_params = {
-          client_id: @client_id,
-          response_type: options.fetch(:response_type, 'code'),
-          connection: options.fetch(:connection, nil),
-          redirect_uri: redirect_uri,
-          state: options.fetch(:state, nil),
-          scope: options.fetch(:scope, nil)
-        }.merge(options.fetch(:additional_parameters, {}))
-
-        URI::HTTPS.build(host: @domain, path: '/authorize', query: to_query(request_params))
-      end
-
-      # Returns an logout  URL, triggers the logout flow.
-      # @see https://auth0.com/docs/auth-api#!#get--logout
-      # @param return_to [string] Url to redirect after authorization
-      # @return [url] Logout URL.
-      def logout_url(return_to)
-        request_params = {
-          returnTo: return_to
-        }
-
-        URI::HTTPS.build(host: @domain, path: '/logout', query: to_query(request_params))
-      end
-
-      # Returns a samlp URL. The SAML Request AssertionConsumerServiceURL will be used to POST back the assertion
-      # and it has to match with the application callback URL.
-      # @see https://auth0.com/docs/auth-api#get--samlp--client_id-
-      # @param connection [string] to login with a specific provider.
-      # @return [url] samlp URL.
-      def samlp_url(connection = UP_AUTH)
-        request_params = {
-          connection: connection
-        }
-        URI::HTTPS.build(host: @domain, path: "/samlp/#{@client_id}", query: to_query(request_params))
-      end
-
-      # Returns a wsfed URL.
-      # @see https://auth0.com/docs/auth-api#get--wsfed--client_id-
-      # @param connection [string] to login with a specific provider.
-      # @return [url] wsfed URL.
-      def wsfed_url(connection = UP_AUTH)
-        request_params = {
-          whr: connection
-        }
-        URI::HTTPS.build(host: @domain, path: "/wsfed/#{@client_id}", query: to_query(request_params))
-      end
-
       private
 
+      # Build a URL query string from a hash.
       def to_query(hash)
-        hash.map { |k, v| "#{k}=#{URI.escape(v)}" unless v.nil? }.reject(&:nil?).join('&')
+        hash.map { |k, v| "#{k}=#{CGI.escape(v)}" unless v.nil? }.reject(&:nil?).join('&')
       end
     end
   end
 end
+# rubocop:enable Metrics/ModuleLength