From 248e42383953ba1c88f243bdcf08b78ced6863ca Mon Sep 17 00:00:00 2001 From: Amanda VS Date: Mon, 29 Apr 2024 17:17:46 -0400 Subject: [PATCH] Docs 3689 auth explorer update (#10394) * Authentication API updates HRI addition * Updates for Auth API Exp HRI update Break out client grants #Learn More standardization Error pages into Markdown tables * Commits Clean-up Final markdown tables addition of fapi to glossary for HRI entry * Update _device-code.md Duplicate Learn More * Updates after local run review * Last commits for final fixes Fixes for the nav, flow files, updated error codes * Update articles/api/authentication/index.md Co-authored-by: Patrick Dillon * Revoke has been added the the Refresh Token page * Update _introduction.md * First batch of commits * Small edits for older content * Last commits from HRI * Last edits for the smaller project * Remove pending redirect --------- Co-authored-by: Patrick Dillon Co-authored-by: Nick Gagliardi <133918568+nick-gagliardi@users.noreply.github.com> --- .markdownlint.json | 8 +- articles/_includes/_http-method.html | 4 +- articles/_includes/_test-this-endpoint.md | 3 +- .../api/authentication/_change-password.md | 6 +- articles/api/authentication/_introduction.md | 40 +- articles/api/authentication/_login.md | 103 +-- articles/api/authentication/_logout.md | 72 +- .../_multifactor-authentication.md | 37 +- articles/api/authentication/_passwordless.md | 28 +- articles/api/authentication/_saml-sso.md | 20 +- articles/api/authentication/_sign-up.md | 4 +- articles/api/authentication/_userinfo.md | 2 +- articles/api/authentication/_wsfed-req.md | 19 +- .../api-authz/_auth-code-flow.md | 121 ++++ .../api-authz/_auth-code-pkce.md | 126 ++++ .../authentication/api-authz/_authz-client.md | 231 +----- .../api-authz/_client-credential.md | 74 ++ .../authentication/api-authz/_device-code.md | 111 ++- .../authentication/api-authz/_get-token.md | 675 ------------------ .../api-authz/_highly-regulated.md | 232 ++++++ .../api/authentication/api-authz/_implicit.md | 61 ++ .../api-authz/_refresh-token.md | 247 +++++++ .../api-authz/_resource-owner.md | 96 +++ .../api-authz/_revoke-refersh-token.md | 80 --- articles/api/authentication/errors/_errors.md | 110 +-- .../errors/_oauth-access_token.md | 42 +- .../authentication/errors/_oauth-revoke.md | 27 +- .../api/authentication/errors/_oauth-ro.md | 126 +--- .../errors/_passwordless-start.md | 77 +- .../errors/_passwordless-verify.md | 90 +-- articles/api/authentication/index.md | 25 +- .../api/authentication/legacy/_delegation.md | 21 +- .../api/authentication/legacy/_linking.md | 4 +- articles/api/authentication/legacy/_login.md | 23 +- .../authentication/legacy/_resource-owner.md | 12 +- .../api/authentication/legacy/_userinfo.md | 4 +- config/glossary.json | 5 + config/redirects.js | 4 - 38 files changed, 1331 insertions(+), 1639 deletions(-) create mode 100644 articles/api/authentication/api-authz/_auth-code-flow.md create mode 100644 articles/api/authentication/api-authz/_auth-code-pkce.md create mode 100644 articles/api/authentication/api-authz/_client-credential.md delete mode 100644 articles/api/authentication/api-authz/_get-token.md create mode 100644 articles/api/authentication/api-authz/_highly-regulated.md create mode 100644 articles/api/authentication/api-authz/_implicit.md create mode 100644 articles/api/authentication/api-authz/_refresh-token.md create mode 100644 articles/api/authentication/api-authz/_resource-owner.md delete mode 100644 articles/api/authentication/api-authz/_revoke-refersh-token.md diff --git a/.markdownlint.json b/.markdownlint.json index 66e4c0d02a..761c315758 100644 --- a/.markdownlint.json +++ b/.markdownlint.json @@ -1,20 +1,20 @@ { "default": false, "resultVersion": 1, - "MD001": true, + "MD001": false, "MD002": true, "MD003": true, "MD005": true, "MD006": true, "MD011": true, - "MD012": true, + "MD012": false, "MD018": true, "MD019": true, "MD023": true, - "MD024": true, + "MD024": false, "MD025": true, "MD027": true, - "MD031": true, + "MD031": false, "MD034": true, "MD035": true, "MD037": true, diff --git a/articles/_includes/_http-method.html b/articles/_includes/_http-method.html index 42cf02bee8..cacd38d8f0 100644 --- a/articles/_includes/_http-method.html +++ b/articles/_includes/_http-method.html @@ -1,4 +1,4 @@ -
+

${http_method} ${path} -

\ No newline at end of file + \ No newline at end of file diff --git a/articles/_includes/_test-this-endpoint.md b/articles/_includes/_test-this-endpoint.md index 318f993067..e2d873ea5d 100644 --- a/articles/_includes/_test-this-endpoint.md +++ b/articles/_includes/_test-this-endpoint.md @@ -1,5 +1,4 @@ -You can use our **Authentication API Debugger** extension to test this endpoint. To do so, you need to be logged in and have installed the [Authentication API Debugger extension](/extensions/authentication-api-debugger). - + Click on **Install Debugger** to go to the article that explains how (you only have to do this once). <% diff --git a/articles/api/authentication/_change-password.md b/articles/api/authentication/_change-password.md index 4f99e81283..c543017fc1 100644 --- a/articles/api/authentication/_change-password.md +++ b/articles/api/authentication/_change-password.md @@ -56,7 +56,7 @@ curl --request POST \ Send a change password email to the user's provided email address and `connection`. -Optionally, you may provide an Organization ID to support Organization-specific variables in [customized email templates](https://auth0.com/docs/customize/email/email-templates#common-variables) and to include the `organization_id` and `organization_name` parameters in the **Redirect To** URL. +Optionally, you may provide an Organization ID to support Organization-specific variables in [customized email templates](/customize/email/email-templates#common-variables) and to include the `organization_id` and `organization_name` parameters in the **Redirect To** URL. Note: This endpoint only works for database connections. @@ -79,9 +79,9 @@ Note: This endpoint only works for database connections. * `X-RateLimit-Reset`: Remaining time until the rate limit (`X-RateLimit-Limit`) resets. The value is in [UTC epoch seconds](https://en.wikipedia.org/wiki/Unix_time). -### More Information +### Learn More - [Changing a User's Password](/connections/database/password-change) - [Password Strength in Auth0 Database Connections](/connections/database/password-strength) - [Password Options in Auth0 Database Connections](/connections/database/password-options) -- [Auth0 API Rate Limit Policy](/policies/rate-limits) +- [Auth0 API Rate Limit Policy](/troubleshoot/customer-support/operational-policies/rate-limit-policy/rate-limit-configurations) diff --git a/articles/api/authentication/_introduction.md b/articles/api/authentication/_introduction.md index 965d1370b6..0e9b16db4c 100644 --- a/articles/api/authentication/_introduction.md +++ b/articles/api/authentication/_introduction.md @@ -2,7 +2,7 @@ The Authentication API enables you to manage all aspects of user identity when you use Auth0. It offers endpoints so your users can log in, sign up, log out, access APIs, and more. -The API supports various identity protocols, like [OpenID Connect](/protocols/oidc), [OAuth 2.0](/protocols/oauth2), and [SAML](/protocols/saml). +The API supports various identity protocols, like [OpenID Connect](/protocols/oidc), [OAuth 2.0](/protocols/oauth2), [FAPI](/secure/highly-regulated-identity#advanced-security-with-openid-connect-fapi-) and [SAML](/protocols/saml). :::note This API is designed for people who feel comfortable integrating with RESTful APIs. If you prefer a more guided approach check out our [Quickstarts](/quickstarts) or our [Libraries](/libraries). @@ -32,7 +32,7 @@ Generate a [client assertion](https://auth0.com/docs/get-started/authentication- ### Client ID and Client Secret -Send the Client ID and Client Secret. The method you can use to send this data is determined by the [Token Endpoint Authentication Method](https://auth0.com/docs/get-started/applications/confidential-and-public-applications/view-application-type) configured for your application. +Send the Client ID and Client Secret. The method you can use to send this data is determined by the [Token Endpoint Authentication Method](/get-started/applications/confidential-and-public-applications/view-application-type) configured for your application. If you are using **Post**, you must send this data in the JSON body of your request. @@ -44,7 +44,7 @@ An example is the [Revoke Refresh Token endpoint](#revoke-refresh-token). This o Send the Client ID. For public applications (applications that cannot hold credentials securely, such as SPAs or mobile apps), we offer some endpoints that can be accessed using only the Client ID. -An example is the [Implicit Grant](#implicit-grant). +An example is the [Implicit Grant](#implicit-flow). ### mTLS Authentication @@ -85,16 +85,38 @@ Each request should be sent with a Content-Type of `application/json`. You can test the endpoints using the [Authentication API Debugger](/extensions/authentication-api-debugger). -### Test with the Authentication API Debugger +### Authentication API Debugger The [Authentication API Debugger](/extensions/authentication-api-debugger) is an Auth0 extension you can use to test several endpoints of the Authentication API. -If it's the first time you use it, you have to install it using the [dashboard](${manage_url}/#/extensions). Once you do, you are ready to configure your app's settings and run your tests. +<%= include('../../_includes/_test-this-endpoint') %> + +### Configure Connections + +1. On the *Configuration* tab, set the fields **Application** (select the application you want to use for the test) and **Connection** (the name of the social connection to use). + +1. Copy the **Callback URL** and set it as part of the **Allowed Callback URLs** of your [Application Settings](${manage_url}/#/applications). + +1. At the *OAuth2 / OIDC* tab, select **OAuth2 / OIDC Login**. + +### Use Authentication API Debugger +Configure other endpoints with the following options: + +- Passwordless: On the *OAuth2 / OIDC* tab, set **Username** to the user's phone number if `connection=sms`, or the user's email if `connection=email`, and **Password** to the user's verification code. Click **Resource Owner Endpoint**. +- SAML SSO: On the *Other Flows* tab, select **SAML**. +- WS-Federation: On the *Other Flows* tab, select **WS-Federation**. +- Logout: On the *Other Flows* tab, select **Logout**, or **Logout (Federated)** to log the user out of the identity provider as well. +- Legacy Login: On the *OAuth2 / OIDC* tab, set the fields **ID Token**, **Refresh Token** and **Target Client ID**. Click **Delegation**. +- Legacy Delegation: On the *OAuth2 / OIDC* tab, set **Username** and **Password**. Click **Resource Owner Endpoint**. +- Legacy Resource Owner: On the *OAuth2 / OIDC* tab, set the **Username** and **Password**, then select **Resource Owner Endpoint**. + +### Use Authentication API Debugger with authentications flows + +Configure authentication flows with the following options: +- Authorization Code Flow: On the *OAuth2 / OIDC* tab, set the field **Authorization Code** to the code you retrieved from [Authorization Code Grant](/get-started/authentication-and-authorization-flow/authorization-code-flow), and the **Code Verifier** to the key. Click **OAuth2 Code Exchange**. +- Authorization Code Flow + PKCE: On the *OAuth2 / OIDC* tab, set the field **Authorization Code** to the code you retrieved from [Authorization Code Grant](/get-started/authentication-and-authorization-flow/authorization-code-flow-with-pkce), and the **Code Verifier** to the key. Click **OAuth2 Code Exchange**. +- Client Credential Flow: On the *OAuth2 / OIDC* tab, select **OAuth2 Client Credentials**. -Note that its URL varies according to your tenant's region: -- US West -- Europe Central -- Australia ## Errors diff --git a/articles/api/authentication/_login.md b/articles/api/authentication/_login.md index f170793af1..8dd70dbe3a 100644 --- a/articles/api/authentication/_login.md +++ b/articles/api/authentication/_login.md @@ -1,5 +1,14 @@ + + # Login +<%= include('../../_includes/_http-method', { + "http_badge": "badge-primary", + "http_method": "GET", + "path": "/authorize", + "link": "#social" +}) %> + ## Social ```http @@ -39,14 +48,9 @@ GET https://${account.namespace}/authorize? ``` -<%= include('../../_includes/_http-method', { - "http_badge": "badge-primary", - "http_method": "GET", - "path": "/authorize", - "link": "#social" -}) %> +You can connect your Auth0 service to a social identity provider and allow your users to log in to your application via Facebook, Google, Apple, or other supported providers. To learn more about supported providers, visit [Marketplace](https://marketplace.auth0.com/features/social-connections). -Use this endpoint to authenticate a user with a social provider. It will return a `302` redirect to the social provider specified in `connection`. +To authenticate users with a social provider, make a `GET` call to the `/authorize` endpoint. It will return a `302` redirect to the social provider specified in the `connection` parameter. ::: note Social connections only support browser-based (passive) authentication because most social providers don't allow a username and password to be entered into applications that they don't own. Therefore, the user will be redirected to the provider's sign in page. @@ -56,40 +60,26 @@ Social connections only support browser-based (passive) authentication because m | Parameter | Description | |:-----------------|:------------| -| `response_type`
Required | Use `code` for server side flows and `token` for application side flows | +| `response_type`
Required | Specifies the token type. Use `code` for server side flows and `token` for application side flows | | `client_id`
Required | The `client_id` of your application | | `connection` | The name of a social identity provider configured to your application, for example `google-oauth2` or `facebook`. If null, it will redirect to the [Auth0 Login Page](https://${account.namespace}/login) and show the Login Widget. | -| `redirect_uri`
Required | The URL to which Auth0 will redirect the browser after authorization has been granted by the user. | +| `redirect_uri`
Required | The URL to which Auth0 will redirect the browser after authorization has been granted by the user. Specify the `redirect_uri` under your [Application's Settings](${manage_url}/#/applications).| | `state`
Recommended | An opaque value the applications adds to the initial request that the authorization server includes when redirecting the back to the application. This value must be used by the application to prevent CSRF attacks. | | `ADDITIONAL_PARAMETERS` | Append any additional parameter to the end of your request, and it will be sent to the provider. For example, `access_type=offline` (for Google Refresh Tokens) , `display=popup` (for Windows Live popup mode). | -### Test with Authentication API Debugger - -<%= include('../../_includes/_test-this-endpoint') %> - -1. At the *Configuration* tab, set the fields **Application** (select the application you want to use for the test) and **Connection** (the name of the social connection to use). - -1. Copy the **Callback URL** and set it as part of the **Allowed Callback URLs** of your [Application Settings](${manage_url}/#/applications). - -1. At the *OAuth2 / OIDC* tab, click **OAuth2 / OIDC Login**. - ### Remarks -- The `redirect_uri` value must be specified as a valid callback URL under your [Application's Settings](${manage_url}/#/applications). - - If `response_type=token`, after the user authenticates on the provider, it will redirect to your application `callback URL` passing the Access Token and ID Token in the address `location.hash`. This is used for Single-Page Apps and also on Native Mobile SDKs. - The sample auth0.js script uses the library version 8. If you are using auth0.js version 7, please see this [reference guide](/libraries/auth0js/v7). +### Learn More -### More Information - -- [Supported Social Identity Providers](/connections/identity-providers-social) +- [Supported Social Identity Providers](https://marketplace.auth0.com/features/social-connections) - [Custom Social Connections](/connections/social/oauth2) -- [State Parameter](/protocols/oauth2/oauth-state) +- [State Parameter](/secure/attack-protection/state-parameters) - [Auth0.js /authorize Method Reference](/libraries/auth0js#webauth-authorize-) - ## Database/AD/LDAP (Passive) ```http @@ -126,46 +116,26 @@ GET https://${account.namespace}/authorize? ``` -<%= include('../../_includes/_http-method', { - "http_badge": "badge-primary", - "http_method": "GET", - "path": "/authorize", - "link": "#database-ad-ldap-passive-" -}) %> - -Use this endpoint for browser based (passive) authentication. It returns a `302` redirect to the [Auth0 Login Page](https://${account.namespace}/login) that will show the Login Widget where the user can log in with email and password. +Use the Auth0 user store or your own database to store and manage username and password credentials. If you have your own user database, you can use it as an identity provider in Auth0 to authenticate users. When you make a `GET` call to the `/authorize` endpoint for browser based (passive) authentication. It returns a `302` redirect to the [Auth0 Login Page](https://${account.namespace}/login) that will show the Login Widget where the user can log in with email and password. ### Request Parameters | Parameter | Description | |:-----------------|:------------| -| `response_type`
Required | Use `code` for server side flows and `token` for application side flows. | +| `response_type`
Required | Specifies the token type. Use `code` for server side flows and `token` for application side flows. | | `client_id`
Required | The `client_id` of your application. | | `connection` | The name of the connection configured to your application. If null, it will redirect to the [Auth0 Login Page](https://${account.namespace}/login) and show the Login Widget using the first database connection. | -| `redirect_uri`
Required | The URL to which Auth0 will redirect the browser after authorization has been granted by the user. | -| `scope` | OIDC scopes and custom API scopes. For example: `openid read:timesheets`. | +| `redirect_uri`
Required | The URL to which Auth0 will redirect the browser after authorization has been granted by the user. Specify the `redirect_uri` under your [Application's Settings](${manage_url}/#/applications).| +| `scope`
Recommended | OIDC scopes and custom API scopes. For example: `openid read:timesheets`. Include `offline_access` to get a Refresh Token.| | `state`
Recommended | An opaque value the applications adds to the initial request that the authorization server includes when redirecting the back to the application. This value must be used by the application to prevent CSRF attacks. | - -### Test with Authentication API Debugger - -<%= include('../../_includes/_test-this-endpoint') %> - -1. At the *Configuration* tab, set the fields **Application** (select the application you want to use for the test) and **Connection** (the name of the social connection to use). - -1. Copy the **Callback URL** and set it as part of the **Allowed Callback URLs** of your [Application Settings](${manage_url}/#/applications). - -1. At the *OAuth2 / OIDC* tab, click **OAuth2 / OIDC Login**. - - ### Remarks -- The `redirect_uri` value must be specified as a valid callback URL under your [Application's Settings](${manage_url}/#/applications). - If `response_type=token`, after the user authenticates, it will redirect to your application `callback URL` passing the Access Token and ID Token in the address `location.hash`. This is used for Single-Page Apps and also on Native Mobile SDKs. - The main difference between passive and active authentication is that the former happens in the browser through the [Auth0 Login Page](https://${account.namespace}/login) and the latter can be invoked from anywhere (a script, server to server, and so forth). - The sample auth0.js script uses the library version 8. If you are using auth0.js version 7, please see this [reference guide](/libraries/auth0js/v7). -### More Information +### Learn More - [Database Identity Providers](/connections/database) - [Rate Limits on User/Password Authentication](/policies/rate-limit-policy/database-connections-rate-limits) @@ -208,49 +178,30 @@ GET https://${account.namespace}/authorize? ``` -<%= include('../../_includes/_http-method', { - "http_badge": "badge-primary", - "http_method": "GET", - "path": "/authorize", - "link": "#enterprise-saml-and-others-" -}) %> - -Use this endpoint for passive authentication. It returns a `302` redirect to the SAML Provider (or Windows Azure AD and the rest, as specified in the `connection`) to enter their credentials. +You can connect your Auth0 service to an enterprise identity provider and allow your users to log in to your application via Microsoft Azure Active Directory, Google Workspace, Okta Workforce, or other supported providers. To learn more about supported providers, visit [Auth0 Marketplace](https://marketplace.auth0.com/features/enterprise-connections). +Make a `GET` call to the `/authorize` endpoint for passive authentication. It returns a `302` redirect to the SAML Provider (or Windows Azure AD and the rest, as specified in the `connection`) to enter their credentials. ### Request Parameters | Parameter | Description | |:-----------------|:------------| -| `response_type`
Required | Use `code` for server side flows, `token` for application side flows. | +| `response_type`
Required | Specifies the token type. Use `code` for server side flows, `token` for application side flows. | | `client_id`
Required | The `client_id` of your application. | | `connection` | The name of the connection configured to your application. If null, it will redirect to the [Auth0 Login Page](https://${account.namespace}/login) and show the Login Widget using the first database connection. | -| `redirect_uri`
Required | The URL to which Auth0 will redirect the browser after authorization has been granted by the user. | +| `redirect_uri`
Required | The URL to which Auth0 will redirect the browser after authorization has been granted by the user. Specify the `redirect_uri` under your [Application's Settings](${manage_url}/#/applications).| | `state`
Recommended | An opaque value the applications adds to the initial request that the authorization server includes when redirecting the back to the application. This value must be used by the application to prevent CSRF attacks. | - -### Test with Authentication API Debugger - -<%= include('../../_includes/_test-this-endpoint') %> - -1. At the *Configuration* tab, set the fields **Application** (select the application you want to use for the test) and **Connection** (the name of the social connection to use). - -1. Copy the **Callback URL** and set it as part of the **Allowed Callback URLs** of your [Application Settings](${manage_url}/#/applications). - -1. At the *OAuth2 / OIDC* tab, click **OAuth2 / OIDC Login**. - - ### Remarks - If no `connection` is specified, it will redirect to the [Login Page](https://${account.namespace}/login) and show the Login Widget. -- The `redirect_uri` value must be specified as a valid callback URL under your [Application's Settings](${manage_url}/#/applications). - If `response_type=token`, after the user authenticates, it will redirect to your application `callback URL` passing the Access Token and ID Token in the address `location.hash`. This is used for Single-Page Apps and also on Native Mobile SDKs. - Additional parameters can be sent that will be passed to the provider. - The sample auth0.js script uses the library version 8. If you are using auth0.js version 7, please see this [reference guide](/libraries/auth0js/v7). -### More Information +### Learn More - [SAML](/protocols/saml) - [Obtain a Client Id and Client Secret for Microsoft Azure Active Directory](/connections/enterprise/azure-active-directory) - [State Parameter](/protocols/oauth2/oauth-state) -- [Auth0.js /authorize Method Reference](/libraries/auth0js#webauth-authorize-) +- [Auth0.js /authorize Method Reference](/libraries/auth0js#webauth-authorize-) \ No newline at end of file diff --git a/articles/api/authentication/_logout.md b/articles/api/authentication/_logout.md index 5443ea80f9..f14e9184e5 100644 --- a/articles/api/authentication/_logout.md +++ b/articles/api/authentication/_logout.md @@ -1,6 +1,12 @@ # Logout ## Auth0 Logout +<%= include('../../_includes/_http-method', { + "http_badge": "badge-primary", + "http_method": "GET", + "path": "/v2/logout", + "link": "#logout" +}) %> ```http GET https://${account.namespace}/v2/logout? @@ -32,49 +38,36 @@ curl --request GET \ ``` -<%= include('../../_includes/_http-method', { - "http_badge": "badge-primary", - "http_method": "GET", - "path": "/v2/logout", - "link": "#logout" -}) %> - Use this endpoint to logout a user. If you want to navigate the user to a specific URL after the logout, set that URL at the `returnTo` parameter. The URL should be included in any the appropriate `Allowed Logout URLs` list: -- If the `client_id` parameter is included, the `returnTo` URL must be listed in the `Allowed Logout URLs` set at the application level (see [Setting Allowed Logout URLs at the App Level](/logout#set-the-allowed-logout-urls-at-the-application-level)). -- If the `client_id` parameter is NOT included, the `returnTo` URL must be listed in the `Allowed Logout URLs` set at the tenant level (see [Setting Allowed Logout URLs at the Tenant Level](/logout#set-the-allowed-logout-urls-at-the-tenant-level)). -- If the `client_id` parameter is included and the `returnTo` URL is NOT set, the server returns the user to the first Allowed Logout URLs set in the Dashboard (see [Setting Allowed Logout URLs at the Tenant Level](/logout#set-the-allowed-logout-urls-at-the-tenant-level)). +- If the `client_id` parameter is included, the `returnTo` URL must be listed in the `Allowed Logout URLs` set at the application level. To learn more, read [Log Users Out of Applications](/authenticate/login/logout/log-users-out-of-applications). +- If the `client_id` parameter is NOT included, the `returnTo` URL must be listed in the `Allowed Logout URLs` set at the tenant level. To learn more, read [Log Users Out of Auth0](/authenticate/login/logout/log-users-out-of-auth0). +- If the `client_id` parameter is included and the `returnTo` URL is NOT set, the server returns the user to the first Allowed Logout URLs set in the Dashboard. To learn more, read [Log Users Out of Applications](/authenticate/login/logout/log-users-out-of-applications). ### Request Parameters | Parameter | Description | |:-----------------|:------------| -| `returnTo ` | URL to redirect the user after the logout. | +| `returnTo` | URL to redirect the user after the logout. | | `client_id` | The `client_id` of your application. | | `federated` | Add this query string parameter to the logout URL, to log the user out of their identity provider, as well: `https://${account.namespace}/v2/logout?federated`. | - -### Test with Authentication API Debugger - -<%= include('../../_includes/_test-this-endpoint') %> - -1. At the *Configuration* tab, set the fields **Application** (select the application you want to use for the test) and **Connection** (the name of the social connection to use). - -1. Copy the **Callback URL** and set it as part of the **Allowed Logout URLs** of your [Application Settings](${manage_url}/#/applications). - -1. At the *Other Flows* tab, click **Logout**, or **Logout (Federated)** to log the user out of the identity provider as well. - - ### Remarks - Logging the user out of their identity provider is not common practice, so think about the user experience before you use the `federated` query string parameter. - The sample auth0.js script uses the library version 8. If you are using auth0.js version 7, please see this [reference guide](/libraries/auth0js/v7). -### More Information +### Learn More - [Logout](/logout) ## OIDC Logout +<%= include('../../_includes/_http-method', { + "http_badge": "badge-primary", + "http_method": "GET", + "path": "/oidc/logout", + "link": "#logout" +}) %> ```http GET https://${account.namespace}/oidc/logout? @@ -111,22 +104,17 @@ curl --request GET \ ``` -<%= include('../../_includes/_http-method', { - "http_badge": "badge-primary", - "http_method": "GET", - "path": "/oidc/logout", - "link": "#logout" -}) %> - Use this endpoint to logout a user. If you want to navigate the user to a specific URL after the logout, set that URL at the `post_logout_redirect_uri` parameter. The URL should be included in the appropriate `Allowed Logout URLs` list: - If the `id_token_hint` parameter is included: - When the `client_id` parameter is included, the server uses the URL from the `aud` claim in the `id_token_hint` to select which of the `Allowed Logout URLs` to use from the application specified by the `client_id`. - When the `client_id` parameter is NOT included, the server uses the URL from the `aud` claim in the `id_token_hint` to select which of the `Allowed Logout URLs` at the tenant level to use. - If the `id_token_hint` parameter is not included: - - If the `client_id` parameter is included, the `post_logout_redirect_uri` URL must be listed in the `Allowed Logout URLs` set at the application level (see [Setting Allowed Logout URLs at the App Level](/docs/logout#set-the-allowed-logout-urls-at-the-application-level)). - - If the `client_id` parameter is NOT included, the `post_logout_redirect_uri` URL must be listed in the `Allowed Logout URLs` set at the tenant level (see [Setting Allowed Logout URLs at the Tenant Level](/docs/logout#set-the-allowed-logout-urls-at-the-tenant-level)). - - If the `client_id` parameter is included and the `post_logout_redirect_uri` URL is NOT set, the server returns the user to the first `Allowed Logout URLs` set in the Dashboard (see [Setting Allowed Logout URLs at the Tenant Level](/docs/logout#set-the-allowed-logout-urls-at-the-tenant-level)). + - If the `client_id` parameter is included, the `post_logout_redirect_uri` URL must be listed in the `Allowed Logout URLs` set at the application level. + - If the `client_id` parameter is NOT included, the `post_logout_redirect_uri` URL must be listed in the `Allowed Logout URLs` set at the tenant level. + - If the `client_id` parameter is included and the `post_logout_redirect_uri` URL is NOT set, the server returns the user to the first `Allowed Logout URLs` set in Auth0 Dashboard. + + To learn more, read [Log Users Out of Auth0 with OIDC Endpoint](/authenticate/login/logout/log-users-out-of-auth0). ### Request Parameters @@ -141,18 +129,6 @@ Use this endpoint to logout a user. If you want to navigate the user to a specif | `state` (Optional) | An opaque value the applications adds to the initial request that the authorization server includes when redirecting the back to the`post_logout_redirect_uri`. | | `ui_locales` (Optional) | Space-delimited list of locales used to constrain the language list for the request. The first locale on the list must match the enabled locale in your tenant | - -### Test with Authentication API Debugger - -<%= include('../../_includes/_test-this-endpoint') %> - -1. At the *Configuration* tab, set the fields **Application** (select the application you want to use for the test) and **Connection** (the name of the social connection to use). - -1. Copy the **_Callback URL_** and set it as part of the **Allowed Logout URLs** of your Application Settings. - -1. At the _Other Flows_ tab, click **Logout**, or **Logout (Federated)** to log the user out of the identity provider as well. - - ### Remarks - Logging the user out of their social identity provider is not common practice, so think about the user experience before you use the `federated` query string parameter with social identity providers. @@ -162,7 +138,7 @@ Use this endpoint to logout a user. If you want to navigate the user to a specif - The `POST` HTTP method is also supported for this request. When using `POST`, the request parameters should be provided in the request body as form parameters instead of the query string. The federated parameter requires a value of `true` or `false`. - This conforms to the [OIDC RP-initiated Logout Specification](https://openid.net/specs/openid-connect-rpinitiated-1_0.html). -### More Information +### Learn More - [Logout](/logout) - [Use the OIDC Endpoint to Log Users Out of Auth0](/logout/log-users-out-of-auth0) @@ -195,6 +171,6 @@ Logout behavior is determined by the configuration of the SAML2 Web App addon fo ### Remarks - The POST body must contain a valid SAML `` message. To learn more, read [Assertions and Protocols for the OASIS Security Assertion Markup Language (SAML) V2.0 on Oasis](https://docs.oasis-open.org/security/saml/v2.0/saml-core-2.0-os.pdf). -### More information +### Learn More - [Logout](/logout) - [Log Users Out of SAML Identity Providers](https://auth0.com/docs/authenticate/login/logout/log-users-out-of-saml-idps) diff --git a/articles/api/authentication/_multifactor-authentication.md b/articles/api/authentication/_multifactor-authentication.md index 7a3c70e26a..32c6a59802 100644 --- a/articles/api/authentication/_multifactor-authentication.md +++ b/articles/api/authentication/_multifactor-authentication.md @@ -6,7 +6,7 @@ First, request a challenge based on the challenge types supported by the applica Next, verify the multi-factor authentication using the `/oauth/token` endpoint and the specified challenge type: a one-time password (OTP), a recovery code, or an out-of-band (OOB) challenge. -For more information, check out: +To learn more, read: - [Multi-factor Authentication and Resource Owner Password](/mfa/guides/mfa-api/multifactor-resource-owner-password) - [Multi-factor Authentication API](/mfa/concepts/mfa-api) @@ -62,6 +62,7 @@ Content-Type: application/json ``` > RESPONSE SAMPLE FOR OOB WITHOUT BINDING METHOD: + ```JSON HTTP/1.1 200 OK Content-Type: application/json @@ -72,6 +73,7 @@ Content-Type: application/json ``` > RESPONSE SAMPLE FOR OOB WITH BINDING METHOD: + ```JSON HTTP/1.1 200 OK Content-Type: application/json @@ -82,13 +84,6 @@ Content-Type: application/json } ``` -<%= include('../../_includes/_http-method', { - "http_badge": "badge-success", - "http_method": "POST", - "path": "/mfa/challenge", - "link": "#multifactor-authentication" -}) %> - Request a challenge for multi-factor authentication (MFA) based on the challenge types supported by the application and user. The `challenge_type` is how the user will get the challenge and prove possession. Supported challenge types include: @@ -116,9 +111,9 @@ If OTP is supported by the user and you don't want to request a different factor - Auth0 chooses the challenge type based on the application's supported types and types the user is enrolled with. - An `unsupported_challenge_type` error is returned if your application does not support any of the challenge types the user has enrolled with. - An `unsupported_challenge_type` error is returned if the user is not enrolled. -- If the user is not enrolled, you will get a `association_required` error, indicating the user needs to enroll to use MFA. Check [Add an authenticator](#add-an-authenticator) below on how to proceed. +- If the user is not enrolled, you will get a `association_required` error, indicating the user needs to enroll to use MFA. Read [Add an authenticator](#add-an-authenticator) below on how to proceed. -### More information +### Learn More * [Authenticate With Resource Owner Password Grant and MFA](/mfa/guides/mfa-api/authenticate) * [Manage Authenticator Factors using the MFA API](/mfa/guides/mfa-api/manage) @@ -161,6 +156,7 @@ request(options, function (error, response, body) { ``` > RESPONSE SAMPLE FOR OTP: + ```JSON HTTP/1.1 200 OK Content-Type: application/json @@ -196,7 +192,7 @@ The response is the same as responses for `password` or `http://auth0.com/oauth/ | `mfa_token`
Required | The `mfa_token` you received from `mfa_required` error. | | `otp`
Required | OTP Code provided by the user. | -### More information +### Learn More - [Associate OTP Authenticators](/mfa/guides/mfa-api/otp) @@ -239,6 +235,7 @@ request(options, function (error, response, body) { ``` > RESPONSE SAMPLE FOR PENDING CHALLENGE: + ```JSON HTTP/1.1 200 OK Content-Type: application/json @@ -249,6 +246,7 @@ Content-Type: application/json ``` > RESPONSE SAMPLE FOR VERIFIED CHALLENGE: + ```JSON HTTP/1.1 200 OK Content-Type: application/json @@ -260,6 +258,7 @@ Content-Type: application/json ``` > RESPONSE SAMPLE FOR REJECTED CHALLENGE: + ```JSON HTTP/1.1 200 OK Content-Type: application/json @@ -300,7 +299,7 @@ When the challenge response includes a `binding_method: prompt`, your app needs | `oob_code`
Required | The oob code received from the challenge request. | | `binding_code`| A code used to bind the side channel (used to deliver the challenge) with the main channel you are using to authenticate. This is usually an OTP-like code delivered as part of the challenge message. | -### More information +### Learn More - [Associate Out-of-Band Authenticators](/mfa/guides/mfa-api/oob) @@ -342,6 +341,7 @@ request(options, function (error, response, body) { ``` > RESPONSE SAMPLE FOR OTP: + ```JSON HTTP/1.1 200 OK Content-Type: application/json @@ -426,6 +426,7 @@ request(options, function (error, response, body) { ``` > RESPONSE SAMPLE FOR OOB (SMS channel): + ```JSON HTTP/1.1 200 OK Content-Type: application/json @@ -439,6 +440,7 @@ Content-Type: application/json ``` > RESPONSE SAMPLE FOR OOB (Auth0 channel): + ```JSON HTTP/1.1 200 OK Content-Type: application/json @@ -452,6 +454,7 @@ Content-Type: application/json ``` > RESPONSE SAMPLE FOR OTP: + ```JSON HTTP/1.1 200 OK Content-Type: application/json @@ -495,7 +498,7 @@ To access this endpoint, you must set an Access Token at the Authorization heade | `oob_channels` | The type of OOB channels supported by the client. An array with values `"auth0"`, `"sms"`, `"voice"`. Required if `authenticator_types` include `oob`. | | `phone_number` | The phone number to use for SMS or Voice. Required if `oob_channels` includes `sms` or `voice`. | -### More information +### Learn More - [Multi-factor Authentication API](/mfa/concepts/mfa-api) @@ -533,6 +536,7 @@ request(options, function (error, response, body) { ``` > RESPONSE SAMPLE: + ```JSON HTTP/1.1 200 OK Content-Type: application/json @@ -570,6 +574,7 @@ Content-Type: application/json } ] ``` + <%= include('../../_includes/_http-method', { "http_badge": "badge-primary", "http_method": "GET", @@ -590,7 +595,7 @@ To access this endpoint you must set an Access Toke | `ACCESS_TOKEN`
Required | The Access Token obtained during login. | -#### More information +#### Learn More - [Manage Authenticators](/mfa/guides/mfa-api/manage) @@ -626,6 +631,7 @@ request(options, function (error, response, body) { ``` > RESPONSE SAMPLE: + ```JSON HTTP/1.1 204 OK ``` @@ -644,7 +650,6 @@ To access this endpoint, you must set an Access Tok - `scope`: `remove:authenticators` - `audience`: `https://${account.namespace}/mfa/` - ### Request Parameters | Parameter | Description | @@ -652,6 +657,6 @@ To access this endpoint, you must set an Access Tok | `ACCESS_TOKEN`
Required | The Access Token obtained during login. | | `AUTHENTICATOR_ID`
Required | The ID of the authenticator to delete. -### More information +### Learn More - [Manage Authenticators](/mfa/guides/mfa-api/manage) diff --git a/articles/api/authentication/_passwordless.md b/articles/api/authentication/_passwordless.md index bab9b13a97..4cb6994684 100644 --- a/articles/api/authentication/_passwordless.md +++ b/articles/api/authentication/_passwordless.md @@ -110,7 +110,7 @@ You have three options for [passwordless authentication](/connections/passwordle For the complete error code reference for this endpoint refer to [Errors > POST /passwordless/start](#post-passwordless-start). -### More Information +### Learn More - [Passwordless Authentication](/connections/passwordless) - [Passwordless Best Practices](/connections/passwordless/best-practices) @@ -208,22 +208,11 @@ Once you have a verification code, use this endpoint to login the user with thei | `scope` | Use `openid` to get an ID Token, or `openid profile email` to also include user profile information in the ID Token. | | `redirect_uri`
Required | A callback URL that has been registered with your application's **Allowed Callback URLs**. | - -### Test with Authentication API Debugger - -<%= include('../../_includes/_test-this-endpoint') %> - -1. At the *Configuration* tab, set the fields **Application** (select the application you want to use for the test) and **Connection** (use `sms` or `email`). - -1. Copy the **Callback URL** and set it as part of the **Allowed Callback URLs** of your [Application Settings](${manage_url}/#/applications). - -1. At the *OAuth2 / OIDC* tab, set **Username** to the user's phone number if `connection=sms`, or the user's email if `connection=email`, and **Password** to the user's verification code. Click **Resource Owner Endpoint**. - ### Error Codes For the complete error code reference for this endpoint refer to [Standard Error Responses](#standard-error-responses). -### More Information +### Learn More - [Passwordless Authentication](/connections/passwordless) @@ -251,17 +240,6 @@ Once you have a verification code, use this endpoint to login the user with thei | `password`
Required | The user's verification code. | | `scope` | Use `openid` to get an ID Token, or `openid profile email` to include also user profile information in the ID Token. | - -### Test with Authentication API Debugger - -<%= include('../../_includes/_test-this-endpoint') %> - -1. At the *Configuration* tab, set the fields **Application** (select the application you want to use for the test) and **Connection** (use `sms` or `email`). - -1. Copy the **Callback URL** and set it as part of the **Allowed Callback URLs** of your [Application Settings](${manage_url}/#/applications). - -1. At the *OAuth2 / OIDC* tab, set **Username** to the user's phone number if `connection=sms`, or the user's email if `connection=email`, and **Password** to the user's verification code. Click **Resource Owner Endpoint**. - ### Remarks - The `profile` scope value requests access to the End-User's default profile Claims, which are: `name`, `family_name`, `given_name`, `middle_name`, `nickname`, `preferred_username`, `profile`, `picture`, `website`, `gender`, `birthdate`, `zoneinfo`, `locale`, and `updated_at`. @@ -272,7 +250,7 @@ Once you have a verification code, use this endpoint to login the user with thei For the complete error code reference for this endpoint refer to [Errors > POST /passwordless/verify](#post-passwordless-verify). -### More Information +### Learn More - [Passwordless Best Practices](/connections/passwordless/best-practices) diff --git a/articles/api/authentication/_saml-sso.md b/articles/api/authentication/_saml-sso.md index 0bc97799dc..0769a51318 100644 --- a/articles/api/authentication/_saml-sso.md +++ b/articles/api/authentication/_saml-sso.md @@ -27,7 +27,7 @@ include('../../_includes/_http-method', { Use this endpoint to accept a SAML request to initiate a login. -Optionally, you can include a `connection` parameter to log in with a specific provider. If no connection is specified, the [Auth0 Login Page](/login_page) will be shown. +Optionally, you can include a `connection` parameter to log in with a specific provider. If no connection is specified, the [Auth0 Login Page](/authenticate/login/auth0-universal-login) will be shown. Optionally, SP-initiated login requests can include an `organization` parameter to authenticate users in the context of an organization. To learn more, see [Organizations](/organizations). @@ -46,7 +46,7 @@ Optionally, SP-initiated login requests can include an `organization` parameter - All the parameters of the SAML response can be modified with [Rules](/rules). - The SAML request `AssertionConsumerServiceURL` will be used to `POST` back the assertion. It must match one of the application's `callback_URLs`. -### More Information +### Learn More - [SAML](/protocols/saml) ## Get Metadata @@ -78,7 +78,7 @@ This endpoint returns the SAM | `client_id`
Required | The `client_id` of your application. | -### More Information +### Learn More - [SAML](/protocols/saml) @@ -116,17 +116,5 @@ This endpoint accepts an IdP-Initiated Sign On SAMLResponse from a Required | The name of an identity provider configured to your application. | | `SAMLResponse`
Required | An IdP-Initiated Sign On SAML Response. | - -### Test with Authentication API Debugger - -<%= include('../../_includes/_test-this-endpoint') %> - -1. At the *Configuration* tab, set the field **Application** (select the application you want to use for the test) and **Connection** (the name of the configured identity provider). - -1. Copy the **Callback URL** and set it as part of the **Allowed Callback URLs** of your [Application Settings](${manage_url}/#/applications). - -1. At the *Other Flows* tab, click **SAML**. - - -### More Information +### Learn More - [SAML](/protocols/saml) diff --git a/articles/api/authentication/_sign-up.md b/articles/api/authentication/_sign-up.md index 9a47df00c4..be5894e0e4 100644 --- a/articles/api/authentication/_sign-up.md +++ b/articles/api/authentication/_sign-up.md @@ -102,9 +102,9 @@ This endpoint only works for database connections. - The sample auth0.js script uses the library version 8. If you are using auth0.js version 7, please see this [reference guide](/libraries/auth0js/v7). -### More Information +### Learn More - [Password Strength in Auth0 Database Connections](/connections/database/password-strength) - [Password Options in Auth0 Database Connections](/connections/database/password-options) - [Adding Username for Database Connections](/connections/database/require-username) -- [Metadata Overview](/users/concepts/overview-user-metadata) +- [Metadata Overview](/users/concepts/overview-user-metadata) \ No newline at end of file diff --git a/articles/api/authentication/_userinfo.md b/articles/api/authentication/_userinfo.md index dc972f1bab..d636bbb3d5 100644 --- a/articles/api/authentication/_userinfo.md +++ b/articles/api/authentication/_userinfo.md @@ -100,7 +100,7 @@ This endpoint will work only if `openid` was granted as a - To access the most up-to-date values for the `email` or custom claims, you must get new tokens. You can log in using silent authentication (where the `prompt` parameter for your call to the [`authorize` endpoint](/api/authentication#authorization-code-grant) equals `none`) - To access the most up-to-date values for standard claims that were changed using an external IdP (for example, the user changed their email address in Facebook)., you must get new tokens. Log in again using the external IdP, but *not* with silent authentication. -### More Information +### Learn More - [Auth0.js v8 Reference: Extract the authResult and get user info](/libraries/auth0js#extract-the-authresult-and-get-user-info) diff --git a/articles/api/authentication/_wsfed-req.md b/articles/api/authentication/_wsfed-req.md index 699c9990dd..e2e4005875 100644 --- a/articles/api/authentication/_wsfed-req.md +++ b/articles/api/authentication/_wsfed-req.md @@ -32,18 +32,6 @@ This endpoint accepts a WS-Federation request to initiate a login. | `wctx` | Your application's state. | | `wreply` | The callback URL. | - -### Test with Authentication API Debugger - -<%= include('../../_includes/_test-this-endpoint') %> - -1. At the *Configuration* tab, set the field **Application** (select the application you want to use for the test) and **Connection** (the name of the configured identity provider). - -1. Copy the **Callback URL** and set it as part of the **Allowed Callback URLs** of your [Application Settings](${manage_url}/#/applications). - -1. At the *Other Flows* tab, click **WS-Federation**. - - ### Remarks - The `wtrealm` parameter must be in one of these formats: @@ -51,11 +39,9 @@ This endpoint accepts a WS-Federation request to initiate a login. - If this parameter does not begin with a urn, the `client.clientAliases` array is used for look-up. This can only be set with the [/api/v2/clients](/api/management/v2#!/Clients/get_clients) Management API. - The `whr` parameter is mapped to the connection like this: `urn:CONNECTION_NAME`. For example, `urn:google-oauth2` indicates login with Google. If there is no `whr` parameter included, the user will be directed to the [Auth0 Login Page](/login_page). - -### More Information +### Learn More - [WS-Federation](/protocols/ws-fed) - ## Get Metadata ```http @@ -78,7 +64,6 @@ include('../../_includes/_http-method', { This endpoint returns the WS-Federation metadata. - -### More Information +### Learn More - [WS-Federation](/protocols/ws-fed) diff --git a/articles/api/authentication/api-authz/_auth-code-flow.md b/articles/api/authentication/api-authz/_auth-code-flow.md new file mode 100644 index 0000000000..01732638b9 --- /dev/null +++ b/articles/api/authentication/api-authz/_auth-code-flow.md @@ -0,0 +1,121 @@ +# Authorization Code Flow + +## Authorize + +```http +GET https://${account.namespace}/authorize? + audience=API_IDENTIFIER& + scope=SCOPE& + response_type=code& + client_id=${account.clientId}& + redirect_uri=${account.callback}& + state=STATE +``` + +> RESPONSE SAMPLE + +```text +HTTP/1.1 302 Found +Location: ${account.callback}?code=AUTHORIZATION_CODE&state=STATE +``` + +<%= include('../../../_includes/_http-method', { + "http_badge": "badge-primary", + "http_method": "GET", + "path": "/authorize", + "link": "#authorization-code-grant" +}) %> + +This is the OAuth 2.0 grant that regular web apps utilize in order to access an API. + +### Request Parameters + +| Parameter | Description | +|:-----------------|:------------| +| `audience`
| The unique identifier of the target API you want to access. | +| `scope` | The scopes which you want to request authorization for. These must be separated by a space. You can request any of the [standard OpenID Connect (OIDC) scopes](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims) about users, such as `profile` and `email`, custom claims that must [conform to a namespaced format](/tokens/guides/create-namespaced-custom-claims), or any scopes supported by the target API (for example, `read:contacts`). Include `offline_access` to get a Refresh Token. | +| `response_type`
Required | Indicates to Auth0 which OAuth 2.0 flow you want to use. Use `code` for Authorization Code Grant Flow. | +| `client_id`
Required | Your application's ID. | +| `state`
Recommended | An opaque value the application adds to the initial request that Auth0 includes when redirecting the back to the application. This value must be used by the application to prevent CSRF attacks. | +| `redirect_uri` | The URL to which Auth0 will redirect the browser after authorization has been granted by the user. | +| `connection` | The name of the connection configured to your application. | +| `prompt` | To initiate a [silent authentication](/api-auth/tutorials/silent-authentication) request, use `prompt=none` (To learn more, read the Remarks). | +| `organization` | ID of the [organization](/organizations) to use when authenticating a user. When not provided, if your application is configured to **Display Organization Prompt**, the user will be able to enter the organization name when authenticating. | +| `invitation` | Ticket ID of the organization invitation. When [inviting a member to an Organization](/organizations/invite-members), your application should handle invitation acceptance by forwarding the invitation and organization key-value pairs when the user accepts the invitation. | + +## Get Token + +```http +POST https://${account.namespace}/oauth/token +Content-Type: application/x-www-form-urlencoded + +grant_type=authorization_code&client_id=${account.clientId}&client_secret=YOUR_CLIENT_SECRET&code=AUTHORIZATION_CODE&redirect_uri=${account.callback} +``` + +```shell +curl --request POST \ + --url 'https://${account.namespace}/oauth/token' \ + --header 'content-type: application/x-www-form-urlencoded' \ + --data 'grant_type=authorization_code&client_id=${account.clientId}&client_secret=YOUR_CLIENT_SECRET&code=AUTHORIZATION_CODE&redirect_uri=${account.callback}' +``` + +```javascript +var request = require("request"); + +var options = { method: 'POST', + url: 'https://${account.namespace}/oauth/token', + headers: { 'content-type': 'application/x-www-form-urlencoded' }, + form: + { grant_type: 'authorization_code', + client_id: '${account.clientId}', + client_secret: 'YOUR_CLIENT_SECRET', + code: 'AUTHORIZATION_CODE', + redirect_uri: '${account.callback}' } + }; + +request(options, function (error, response, body) { + if (error) throw new Error(error); + + console.log(body); +}); +``` + +> RESPONSE SAMPLE: + +```JSON +HTTP/1.1 200 OK +Content-Type: application/json +{ + "access_token":"eyJz93a...k4laUWw", + "refresh_token":"GEbRxBN...edjnXbL", + "id_token":"eyJ0XAi...4faeEoQ", + "token_type":"Bearer", + "expires_in":86400 +} +``` + +<%= include('../../../_includes/_http-method', { + "http_badge": "badge-success", + "http_method": "POST", + "path": "/oauth/token", + "link": "#authorization-code" +}) %> + +This is the flow that regular web apps use to access an API. Use this endpoint to exchange an Authorization Code for a token. + +### Request Parameters + +| Parameter | Description | +|:-----------------|:------------| +| `grant_type`
Required | Denotes the flow you are using. For Authorization Code, use `authorization_code`. | +| `client_id`
Required | Your application's Client ID. | +| `client_secret`
Required | Your application's Client Secret. | +| `code`
Required | The Authorization Code received from the initial `/authorize` call. | +| `redirect_uri`| This is required only if it was set at the [GET /authorize](#authorization-code-grant) endpoint. The values from `/authorize` must match the value you set at `/oauth/token`. | + +### Learn More + +- [Authorization Code Flow](/flows/concepts/auth-code) +- [Call API Using the Authorization Code Flow](/flows/guides/auth-code/call-api-auth-code) +- [State Parameter](/protocols/oauth2/oauth-state) +- [Silent Authentication](/api-auth/tutorials/silent-authentication) \ No newline at end of file diff --git a/articles/api/authentication/api-authz/_auth-code-pkce.md b/articles/api/authentication/api-authz/_auth-code-pkce.md new file mode 100644 index 0000000000..8c3d58f5cf --- /dev/null +++ b/articles/api/authentication/api-authz/_auth-code-pkce.md @@ -0,0 +1,126 @@ +# Authorization Code Flow with PKCE + +## Authorize +```http +GET https://${account.namespace}/authorize? + audience=API_IDENTIFIER& + scope=SCOPE& + response_type=code& + client_id=${account.clientId}& + redirect_uri=${account.callback}& + code_challenge=CODE_CHALLENGE& + code_challenge_method=S256 +``` + +> RESPONSE SAMPLE + +```text +HTTP/1.1 302 Found +Location: ${account.callback}?code=AUTHORIZATION_CODE +``` + +<%= include('../../../_includes/_http-method', { + "http_badge": "badge-primary", + "http_method": "GET", + "path": "/authorize", + "link": "#authorization-code-grant-pkce-" +}) %> + +This is the OAuth 2.0 grant that mobile apps utilize in order to access an API. Before starting with this flow, you need to generate and store a `code_verifier`, and using that, generate a `code_challenge` that will be sent in the authorization request. + +### Request Parameters + +| Parameter | Description | +|:-----------------|:------------| +| `audience`
| The unique identifier of the target API you want to access. | +| `scope` | The scopes which you want to request authorization for. These must be separated by a space. You can request any of the [standard OpenID Connect (OIDC) scopes](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims) about users, such as `profile` and `email`, custom claims that must [conform to a namespaced format](/tokens/guides/create-namespaced-custom-claims), or any scopes supported by the target API (for example, `read:contacts`). Include `offline_access` to get a Refresh Token. | +| `response_type`
Required | Indicates to Auth0 which OAuth 2.0 Flow you want to perform. Use `code` for Authorization Code Grant (PKCE) Flow. | +| `client_id`
Required | Your application's Client ID. | +| `state`
Recommended | An opaque value the client adds to the initial request that Auth0 includes when redirecting back to the client. This value must be used by the client to prevent CSRF attacks. | +| `redirect_uri` | The URL to which Auth0 will redirect the browser after authorization has been granted by the user. | +| `code_challenge_method`
Required | Method used to generate the challenge. The PKCE spec defines two methods, `S256` and `plain`, however, Auth0 supports only `S256` since the latter is discouraged. | +| `code_challenge`
Required | Generated challenge from the `code_verifier`. | +| `connection` | The name of the connection configured to your application. | +| `prompt` | To initiate a [silent authentication](/api-auth/tutorials/silent-authentication) request, use `prompt=none` (To learn more, read the Remarks). | +| `organization` | ID of the [organization](/organizations) to use when authenticating a user. When not provided, if your application is configured to **Display Organization Prompt**, the user will be able to enter the organization name when authenticating. | +| `invitation` | Ticket ID of the organization invitation. When [inviting a member to an Organization](/organizations/invite-members), your application should handle invitation acceptance by forwarding the invitation and organization key-value pairs when the user accepts the invitation. | + +## Get Token +```http +POST https://${account.namespace}/oauth/token +Content-Type: application/x-www-form-urlencoded + +grant_type=authorization_code&client_id=${account.clientId}&code_verifier=CODE_VERIFIER&code=AUTHORIZATION_CODE&redirect_uri=${account.callback} +``` + +```shell +curl --request POST \ + --url 'https://${account.namespace}/oauth/token' \ + --header 'content-type: application/x-www-form-urlencoded' \ + --data 'grant_type=authorization_code&client_id=${account.clientId}&code_verifier=CODE_VERIFIER&code=AUTHORIZATION_CODE&redirect_uri=${account.callback}' +``` + +```javascript +var request = require("request"); + +var options = { method: 'POST', + url: 'https://${account.namespace}/oauth/token', + headers: { 'content-type': 'application/x-www-form-urlencoded' }, + form: { + grant_type:"authorization_code", + client_id: "${account.clientId}", + code_verifier: "CODE_VERIFIER", + code: "AUTHORIZATION_CODE", + redirect_uri: "${account.callback}", } }; + +request(options, function (error, response, body) { + if (error) throw new Error(error); + + console.log(body); +}); +``` + +> RESPONSE SAMPLE: + +```JSON +HTTP/1.1 200 OK +Content-Type: application/json +{ + "access_token":"eyJz93a...k4laUWw", + "refresh_token":"GEbRxBN...edjnXbL", + "id_token":"eyJ0XAi...4faeEoQ", + "token_type":"Bearer", + "expires_in":86400 +} +``` + +<%= include('../../../_includes/_http-method', { + "http_badge": "badge-success", + "http_method": "POST", + "path": "/oauth/token", + "link": "#authorization-code-pkce-" +}) %> + +This is the flow that mobile apps use to access an API. Use this endpoint to exchange an Authorization Code for a token. + +### Request Parameters + +| Parameter | Description | +|:-----------------|:------------| +| `grant_type`
Required | Denotes the flow you are using. For Authorization Code (PKCE) use `authorization_code`. | +| `client_id`
Required | Your application's Client ID. | +| `code`
Required | The Authorization Code received from the initial `/authorize` call. | +| `code_verifier`
Required | Cryptographically random key that was used to generate the `code_challenge` passed to `/authorize`. | +| `redirect_uri` | This is required only if it was set at the [GET /authorize](#authorization-code-grant-pkce-) endpoint. The values from `/authorize` must match the value you set at `/oauth/token`. | + +### Remarks + +- In order to improve compatibility for applications, Auth0 will now return profile information in a [structured claim format as defined by the OIDC specification](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims). This means that in order to add custom claims to ID tokens or access tokens, they must [conform to a namespaced format](/tokens/guides/create-namespaced-custom-claims) to avoid possible collisions with standard OIDC claims. +- Include `offline_access` to the `scope` request parameter to get a refresh token from [POST /oauth/token](#authorization-code-pkce-). Make sure that the **Allow Offline Access** field is enabled in the [API Settings](${manage_url}/#/apis). +- The `redirect_uri` value must be specified as a valid callback URL under your [Application's Settings](${manage_url}/#/applications). +- Silent authentication lets you perform an authentication flow where Auth0 will only reply with redirects, and never with a login page. When an Access Token has expired, silent authentication can be used to retrieve a new one without user interaction, assuming the user's Single Sign-on (SSO) session has not expired. + +### Learn More +- [Authorization Code Flow with Proof Key for Code Exchange (PKCE)](/flows/concepts/auth-code-pkce) +- [Call API Using the Authorization Code Flow with PKCE](/flows/guides/auth-code-pkce/call-api-auth-code-pkce) +- [Silent Authentication](/api-auth/tutorials/silent-authentication) \ No newline at end of file diff --git a/articles/api/authentication/api-authz/_authz-client.md b/articles/api/authentication/api-authz/_authz-client.md index cd711d31f2..4979eff892 100644 --- a/articles/api/authentication/api-authz/_authz-client.md +++ b/articles/api/authentication/api-authz/_authz-client.md @@ -2,6 +2,7 @@ To begin an OAuth 2.0 Authorization flow, your application should first send the user to the authorization URL. +## Authorize endpoint The purpose of this call is to obtain consent from the user to invoke the API (specified in `audience`) and do certain things (specified in `scope`) on behalf of the user. Auth0 will authenticate the user and obtain consent, unless consent has been previously given. If you alter the value in `scope`, Auth0 will require consent to be given again. The OAuth 2.0 flows that require user authorization are: @@ -9,228 +10,16 @@ The OAuth 2.0 flows that require user authorization are: - [Authorization Code Flow with Proof Key for Code Exchange (PKCE)](/flows/concepts/auth-code-pkce) - [Implicit Flow](/flows/concepts/implicit) -On the other hand, the [Resource Owner Password Grant](/api-auth/grant/password) and [Client Credentials Flow](/flows/concepts/client-credentials) do not use this endpoint since there is no user authorization involved. Instead, they directly invoke the `POST /oauth/token` endpoint to retrieve an Access Token. +The [Resource Owner Password Grant](/api-auth/grant/password) and [Client Credentials Flow](/flows/concepts/client-credentials) do not use this endpoint since there is no user authorization involved. Instead, they directly invoke the `POST /oauth/token` endpoint to retrieve an Access Token. Based on the OAuth 2.0 flow you are implementing, the parameters slightly change. To determine which flow is best suited for your case, refer to: [Which OAuth 2.0 flow should I use?](/api-auth/which-oauth-flow-to-use). -## Authorization Code Flow +## Get Token +For token-based authentication, use the `oauth/token` endpoint to get an access token for your application to make authenticated calls to a secure API. Optionally, you can also retrieve an ID Token and a Refresh Token. ID Tokens contains user information in the form of scopes you application can extract to provide a better user experience. Refresh Tokens allow your application to request a new access token once the current token expires without interruping the user experience. To learn more, read [ID Tokens](https://auth0.com/docs/secure/tokens/id-tokens) and [Refresh Tokens](https://auth0.com/docs/secure/tokens/refresh-tokens). -```http -GET https://${account.namespace}/authorize? - audience=API_IDENTIFIER& - scope=SCOPE& - response_type=code& - client_id=${account.clientId}& - redirect_uri=${account.callback}& - state=STATE -``` - -> RESPONSE SAMPLE - -```text -HTTP/1.1 302 Found -Location: ${account.callback}?code=AUTHORIZATION_CODE&state=STATE -``` - -<%= include('../../../_includes/_http-method', { - "http_badge": "badge-primary", - "http_method": "GET", - "path": "/authorize", - "link": "#authorization-code-grant" -}) %> - -This is the OAuth 2.0 grant that regular web apps utilize in order to access an API. - -### Request Parameters - -| Parameter | Description | -|:-----------------|:------------| -| `audience`
| The unique identifier of the target API you want to access. | -| `scope` | The scopes which you want to request authorization for. These must be separated by a space. You can request any of the [standard OpenID Connect (OIDC) scopes](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims) about users, such as `profile` and `email`, custom claims that must [conform to a namespaced format](/tokens/guides/create-namespaced-custom-claims), or any scopes supported by the target API (for example, `read:contacts`). Include `offline_access` to get a Refresh Token. | -| `response_type`
Required | Indicates to Auth0 which OAuth 2.0 flow you want to perform. Use `code` for Authorization Code Grant Flow. | -| `client_id`
Required | Your application's ID. | -| `state`
Recommended | An opaque value the application adds to the initial request that Auth0 includes when redirecting the back to the application. This value must be used by the application to prevent CSRF attacks. | -| `redirect_uri` | The URL to which Auth0 will redirect the browser after authorization has been granted by the user. | -| `connection` | The name of the connection configured to your application. | -| `prompt` | To initiate a [silent authentication](/api-auth/tutorials/silent-authentication) request, use `prompt=none` (see Remarks for more info). | -| `organization` | ID of the [organization](/organizations) to use when authenticating a user. When not provided, if your application is configured to **Display Organization Prompt**, the user will be able to enter the organization name when authenticating. | -| `invitation` | Ticket ID of the organization invitation. When [inviting a member to an Organization](/organizations/invite-members), your application should handle invitation acceptance by forwarding the invitation and organization key-value pairs when the user accepts the invitation. | - - -### Test with Authentication API Debugger - -<%= include('../../../_includes/_test-this-endpoint') %> - -1. At the *Configuration* tab, set the **Client** field to the application you want to use for the test. - -1. Copy the **Callback URL** and set it as part of the **Allowed Callback URLs** of your [Application Settings](${manage_url}/#/applications). - -1. At the *OAuth2 / OIDC* tab, set the fields **Audience** (to the unique identifier of the API you want to access), **Response Type** (set to `code`) and enable the **Audience** switch. - -1. Click **OAuth / OIDC Login**. Following the redirect, the URL will contain the authorization code. Note, that the code will be set at the **Authorization Code** field so you can proceed with exchanging it for an Access Token. - -### Remarks - -- In order to improve compatibility for applications, Auth0 will now return profile information in a [structured claim format as defined by the OIDC specification](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims). This means that in order to add custom claims to ID Tokens or Access Tokens, they must [conform to a namespaced format](/tokens/guides/create-namespaced-custom-claims) to avoid possible collisions with standard OIDC claims. -- Include `offline_access` to the `scope` request parameter to get a Refresh Token from [POST /oauth/token](#authorization-code). Make sure that the **Allow Offline Access** field is enabled in the [API Settings](${manage_url}/#/apis). -- The `redirect_uri` value must be specified as a valid callback URL under your [Application's Settings](${manage_url}/#/applications). -- Silent authentication lets you perform an authentication flow where Auth0 will only reply with redirects, and never with a login page. When an Access Token has expired, silent authentication can be used to retrieve a new one without user interaction, assuming the user's Single Sign-on session has not expired. - -### More Information - -- [Authorization Code Flow](/flows/concepts/auth-code) -- [Call API Using the Authorization Code Flow](/flows/guides/auth-code/call-api-auth-code) -- [State Parameter](/protocols/oauth2/oauth-state) -- [Silent Authentication](/api-auth/tutorials/silent-authentication) - - -## Authorization Code Flow with PKCE - -```http -GET https://${account.namespace}/authorize? - audience=API_IDENTIFIER& - scope=SCOPE& - response_type=code& - client_id=${account.clientId}& - redirect_uri=${account.callback}& - code_challenge=CODE_CHALLENGE& - code_challenge_method=S256 -``` - -> RESPONSE SAMPLE - -```text -HTTP/1.1 302 Found -Location: ${account.callback}?code=AUTHORIZATION_CODE -``` - -<%= include('../../../_includes/_http-method', { - "http_badge": "badge-primary", - "http_method": "GET", - "path": "/authorize", - "link": "#authorization-code-grant-pkce-" -}) %> - -This is the OAuth 2.0 grant that mobile apps utilize in order to access an API. Before starting with this flow, you need to generate and store a `code_verifier`, and using that, generate a `code_challenge` that will be sent in the authorization request. - - -### Request Parameters - -| Parameter | Description | -|:-----------------|:------------| -| `audience`
| The unique identifier of the target API you want to access. | -| `scope` | The scopes which you want to request authorization for. These must be separated by a space. You can request any of the [standard OpenID Connect (OIDC) scopes](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims) about users, such as `profile` and `email`, custom claims that must [conform to a namespaced format](/tokens/guides/create-namespaced-custom-claims), or any scopes supported by the target API (for example, `read:contacts`). Include `offline_access` to get a Refresh Token. | -| `response_type`
Required | Indicates to Auth0 which OAuth 2.0 Flow you want to perform. Use `code` for Authorization Code Grant (PKCE) Flow. | -| `client_id`
Required | Your application's Client ID. | -| `state`
Recommended | An opaque value the clients adds to the initial request that Auth0 includes when redirecting the back to the client. This value must be used by the client to prevent CSRF attacks. | -| `redirect_uri` | The URL to which Auth0 will redirect the browser after authorization has been granted by the user. | -| `code_challenge_method`
Required | Method used to generate the challenge. The PKCE spec defines two methods, `S256` and `plain`, however, Auth0 supports only `S256` since the latter is discouraged. | -| `code_challenge`
Required | Generated challenge from the `code_verifier`. | -| `connection` | The name of the connection configured to your application. | -| `prompt` | To initiate a [silent authentication](/api-auth/tutorials/silent-authentication) request, use `prompt=none` (see Remarks for more info). | -| `organization` | ID of the [organization](/organizations) to use when authenticating a user. When not provided, if your application is configured to **Display Organization Prompt**, the user will be able to enter the organization name when authenticating. | -| `invitation` | Ticket ID of the organization invitation. When [inviting a member to an Organization](/organizations/invite-members), your application should handle invitation acceptance by forwarding the invitation and organization key-value pairs when the user accepts the invitation. | - - -### Test with Authentication API Debugger - -<%= include('../../../_includes/_test-this-endpoint') %> - -1. At the *Configuration* tab, set the **Application** field to the app you want to use for the test. - -1. Copy the **Callback URL** and set it as part of the **Allowed Callback URLs** of your [Application Settings](${manage_url}/#/applications). - -1. At the *OAuth2 / OIDC* tab, set the fields **Audience** (to the unique identifier of the API you want to access), **Response Type** (set to `code`) and enable the **Audience** and **PKCE** switches. - -1. Click **OAuth / OIDC Login**. Following the redirect, the URL will contain the authorization code. Note, that the code will be set at the **Authorization Code** field, and the **Code Verifier** will be automatically set as well, so you can proceed with exchanging the code for an Access Token. - - -### Remarks - -- In order to improve compatibility for applications, Auth0 will now return profile information in a [structured claim format as defined by the OIDC specification](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims). This means that in order to add custom claims to ID Tokens or Access Tokens, they must [conform to a namespaced format](/tokens/guides/create-namespaced-custom-claims) to avoid possible collisions with standard OIDC claims. -- Include `offline_access` to the `scope` request parameter to get a Refresh Token from [POST /oauth/token](#authorization-code-pkce-). Make sure that the **Allow Offline Access** field is enabled in the [API Settings](${manage_url}/#/apis). -- The `redirect_uri` value must be specified as a valid callback URL under your [Application's Settings](${manage_url}/#/applications). -- Silent authentication lets you perform an authentication flow where Auth0 will only reply with redirects, and never with a login page. When an Access Token has expired, silent authentication can be used to retrieve a new one without user interaction, assuming the user's Single Sign-on (SSO) session has not expired. - - -### More Information - -- [Authorization Code Flow with Proof Key for Code Exchange (PKCE)](/flows/concepts/auth-code-pkce) -- [Call API Using the Authorization Code Flow with PKCE](/flows/guides/auth-code-pkce/call-api-auth-code-pkce) -- [Silent Authentication](/api-auth/tutorials/silent-authentication) - - -## Implicit Flow - -```http -GET https://${account.namespace}/authorize? - audience=API_IDENTIFIER& - scope=SCOPE& - response_type=token|id_token|id_token token& - client_id=${account.clientId}& - redirect_uri=${account.callback}& - state=STATE& - nonce=NONCE -``` - -> RESPONSE SAMPLE - -```text -HTTP/1.1 302 Found -Location: ${account.callback}#access_token=TOKEN&state=STATE&token_type=TYPE&expires_in=SECONDS -``` - -<%= include('../../../_includes/_http-method', { - "http_badge": "badge-primary", - "http_method": "GET", - "path": "/authorize", - "link": "#implicit-grant" -}) %> - -This is the OAuth 2.0 grant that web apps utilize in order to access an API. - - -### Request Parameters - -| Parameter | Description | -|:-----------------|:------------| -| `audience`
| The unique identifier of the target API you want to access. | -| `scope` | The scopes which you want to request authorization for. These must be separated by a space. You can request any of the [standard OpenID Connect (OIDC) scopes](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims) about users, such as `profile` and `email`, custom claims that must [conform to a namespaced format](/tokens/guides/create-namespaced-custom-claims), or any scopes supported by the target API (for example, `read:contacts`). | -| `response_type`
Required | This will specify the type of token you will receive at the end of the flow. Use `token` to get only an Access Token, `id_token` to get only an ID Token (if you don't plan on accessing an API), or `id_token token` to get both an ID Token and an Access Token. | -| `client_id`
Required | Your application's ID. | -| `state`
Recommended | An opaque value the application adds to the initial request that Auth0 includes when redirecting the back to the application. This value must be used by the application to prevent CSRF attacks. | -| `redirect_uri` | The URL to which Auth0 will redirect the browser after authorization has been granted by the user. | -| `nonce`
Recommended | A string value which will be included in the ID Token response from Auth0, [used to prevent token replay attacks](/api-auth/tutorials/nonce). It is required for `response_type=id_token token`. | -| `connection` | The name of the connection configured to your application. | -| `prompt` | To initiate a [silent authentication](/api-auth/tutorials/silent-authentication) request, use `prompt=none` (see Remarks for more info). | -| `organization` | ID of the [organization](/organizations) to use when authenticating a user. When not provided, if your application is configured to **Display Organization Prompt**, the user will be able to enter the organization name when authenticating. | -| `invitation` | Ticket ID of the organization invitation. When [inviting a member to an Organization](/organizations/invite-members), your application should handle invitation acceptance by forwarding the invitation and organization key-value pairs when the user accepts the invitation. | - - -### Test with Authentication API Debugger - -<%= include('../../../_includes/_test-this-endpoint') %> - -1. At the *Configuration* tab, set the **Application** field to the app you want to use for the test. - -1. Copy the **Callback URL** and set it as part of the **Allowed Callback URLs** of your [application Settings](${manage_url}/#/applications). - -1. At the *OAuth2 / OIDC* tab, set the fields **Audience** (to the unique identifier of the API you want to access), **Response Type** (set to `token`) and enable the **Audience** switch. - -1. Click **OAuth / OIDC Login**. - - -### Remarks - -- The `redirect_uri` value must be specified as a valid callback URL under your [Application's Settings](${manage_url}/#/applications). -- If `response_type=token`, after the user authenticates with the provider, this will redirect them to your application callback URL while passing the `access_token` in the address `location.hash`. This is used for Single-Page Apps and on Native Mobile SDKs. -- The Implicit Grant does not support the issuance of Refresh Tokens. You can use [Silent Authentication](/api-auth/tutorials/silent-authentication) instead. -- In order to improve compatibility for applications, Auth0 will now return profile information in a [structured claim format as defined by the OIDC specification](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims). This means that in order to add custom claims to ID Tokens or Access Tokens, they must [conform to a namespaced format](/tokens/guides/create-namespaced-custom-claims) to avoid possible collisions with standard OIDC claims. -- Silent authentication lets you perform an authentication flow where Auth0 will only reply with redirects, and never with a login page. When an Access Token has expired, silent authentication can be used to retrieve a new one without user interaction, assuming the user's Single Sign-on (SSO) session has not expired. - -### More Information - -- [Implicit Flow](/flows/concepts/implicit) -- [State Parameter](/protocols/oauth2/oauth-state) -- [Mitigate replay attacks when using the Implicit Grant](/api-auth/tutorials/nonce) -- [Silent Authentication](/api-auth/tutorials/silent-authentication) +Note that the only OAuth 2.0 flows that can retrieve a Refresh Token are: +- [Authorization Code Flow (Authorization Code)](/flows/concepts/auth-code) +- [Authorization Code Flow with PKCE (Authorization Code with PKCE)](/flows/concepts/auth-code-pkce) +- [Resource Owner Password](/api-auth/grant/password) +- [Device Authorization Flow](/flows/concepts/device-auth) +- Token Exchange\* \ No newline at end of file diff --git a/articles/api/authentication/api-authz/_client-credential.md b/articles/api/authentication/api-authz/_client-credential.md new file mode 100644 index 0000000000..d80df51e58 --- /dev/null +++ b/articles/api/authentication/api-authz/_client-credential.md @@ -0,0 +1,74 @@ +# Client Credential Flow + +## Get Token + +```http +POST https://${account.namespace}/oauth/token +Content-Type: application/x-www-form-urlencoded + +audience=API_IDENTIFIER&grant_type=client_credentials&client_id=${account.clientId}&client_secret=YOUR_CLIENT_SECRET +``` + +```shell +curl --request POST \ + --url 'https://${account.namespace}/oauth/token' \ + --header 'content-type: application/x-www-form-urlencoded' \ + --data 'audience=API_IDENTIFIER&grant_type=client_credentials&client_id=${account.clientId}&client_secret=YOUR_CLIENT_SECRET' +``` + +```javascript +var request = require("request"); + +var options = { method: 'POST', + url: 'https://${account.namespace}/oauth/token', + headers: { 'content-type': 'application/x-www-form-urlencoded' }, + form: + { client_id: '${account.clientId}', + client_secret: 'YOUR_CLIENT_SECRET', + audience: 'API_IDENTIFIER', + grant_type: 'client_credentials' } + }; + +request(options, function (error, response, body) { + if (error) throw new Error(error); + + console.log(body); +}); +``` + +> RESPONSE SAMPLE: + +```JSON +HTTP/1.1 200 OK +Content-Type: application/json +{ + "access_token":"eyJz93a...k4laUWw", + "token_type":"Bearer", + "expires_in":86400 +} +``` + +<%= include('../../../_includes/_http-method', { + "http_badge": "badge-success", + "http_method": "POST", + "path": "/oauth/token", + "link": "#client-credentials" +}) %> + +This is the OAuth 2.0 grant that server processes use to access an API. Use this endpoint to directly request an access token by using the application's credentials (a Client ID and a Client Secret). + +### Request Parameters + +| Parameter | Description | +|:-----------------|:------------| +| `grant_type`
Required | Denotes the flow you are using. For Client Credentials use `client_credentials`. | +| `client_id`
Required | Your application's Client ID. | +| `client_secret`
Required | Your application's Client Secret. | +| `audience`
Required | The unique identifier of the target API you want to access. | + +### Learn More + +- [Client Credentials Flow](/flows/concepts/client-credentials) +- [Call API using the Client Credentials Flow](/flows/guides/client-credentials/call-api-client-credentials) +- [Setting up a Client Grant using the Management Dashboard](/api-auth/config/using-the-auth0-dashboard) +- [Asking for Access Tokens for a Client Credentials Grant](/api-auth/config/asking-for-access-tokens) \ No newline at end of file diff --git a/articles/api/authentication/api-authz/_device-code.md b/articles/api/authentication/api-authz/_device-code.md index 76bb7dacec..1fc4a27933 100644 --- a/articles/api/authentication/api-authz/_device-code.md +++ b/articles/api/authentication/api-authz/_device-code.md @@ -1,8 +1,6 @@ -# Get Device Code +# Device Authorization Flow -To begin the [Device Authorization Flow](/flows/concepts/device-auth), your application should first request a device code. - -## Device Authorization Flow +## Authorize ```http POST https://${account.namespace}/oauth/device/code @@ -59,7 +57,7 @@ Content-Type: application/json "link": "#device-code" }) %> -This is the flow that input-constrained devices use to access an API. Use this endpoint to get a device code. +This is the flow that input-constrained devices use to access an API. Use this endpoint to get a device code. To begin the [Device Authorization Flow](/flows/concepts/device-auth), your application should first request a device code. ### Request Parameters @@ -84,7 +82,106 @@ This is the flow that input-constrained devices use to access an API. Use this e - Include `offline_access` to the `scope` request parameter to get a Refresh Token from [POST /oauth/token](#device-auth). Make sure that the **Allow Offline Access** field is enabled in the [API Settings](${manage_url}/#/apis). -### More Information +```http +POST https://${account.namespace}/oauth/token +Content-Type: application/x-www-form-urlencoded + +client_id=${account.clientId}&device_code=YOUR_DEVICE_CODE&grant_type=urn:ietf:params:oauth:grant-type:device_code +``` + +```shell +curl --request POST \ + --url 'https://${account.namespace}/oauth/token' \ + --header 'content-type: application/x-www-form-urlencoded' \ + --data 'client_id=${account.clientId}&device_code=YOUR_DEVICE_CODE&grant_type=urn:ietf:params:oauth:grant-type:device_code' +``` + +```javascript +var request = require("request"); + +var options = { method: 'POST', + url: 'https://${account.namespace}/oauth/token', + headers: { 'content-type': 'application/x-www-form-urlencoded' }, + form: + { client_id: '${account.clientId}', + device_code: 'YOUR_DEVICE_CODE', + grant_type: 'urn:ietf:params:oauth:grant-type:device_code' } + }; + +request(options, function (error, response, body) { + if (error) throw new Error(error); + + console.log(body); +}); +``` + +> RESPONSE SAMPLE: + +```JSON +HTTP/1.1 200 OK +Content-Type: application/json +{ + "access_token": "eyJz93a...k4laUWw", + "id_token": "eyJ...0NE", + "refresh_token": "eyJ...MoQ", + "scope": "...", + "expires_in": 86400, + "token_type": "Bearer" +} +``` + +```JSON +HTTP/1.1 403 Forbidden +Content-Type: application/json + { + // Can be retried + "error": "authorization_pending", + "error_description": "User has yet to authorize device code." + } +``` + +```JSON +HTTP/1.1 429 Too Many Requests +Content-Type: application/json + { + // Can be retried + "error": "slow_down", + "error_description": "You are polling faster than the specified interval of 5 seconds." + } +``` + +```JSON +HTTP/1.1 403 Forbidden +Content-Type: application/json + { + // Cannot be retried; transaction failed + "error": "access_denied|invalid_grant|...", + "error_description": "Failure: User cancelled the confirmation prompt or consent page; the code expired; there was an error." + } +``` + +<%= include('../../../_includes/_http-method', { + "http_badge": "badge-success", + "http_method": "POST", + "path": "/oauth/token", + "link": "#device-auth" +}) %> + +This is the OAuth 2.0 grant that input-constrained devices use to access an API. Poll this endpoint using the interval returned with your [device code](/api/authentication#get-device-code) to directly request an access token using the application's credentials (a Client ID) and a device code. + +### Request Parameters + +| Parameter | Description | +|:-----------------|:------------| +| `grant_type`
Required | Denotes the flow you are using. For Device Authorization, use `urn:ietf:params:oauth:grant-type:device_code`. | +| `client_id`
Required | Your application's Client ID. | +| `device_code`
Required | The device code previously returned from the [/oauth/device/code endpoint](/api/authentication#device-authorization-flow). | + +### Remarks +- Because you will be polling this endpoint (using the `interval` from the initial response to determine frequency) while waiting for the user to go to the verification URL and enter their user code, you will likely receive at least one failure before receiving a successful response. See sample responses for possible responses. + +### Learn More - [Device Authorization Flow](/flows/concepts/device-auth) -- [Call API Using the Device Authorization Flow](/flows/guides/device-auth/call-api-device-auth) +- [Call API using the Device Authorization Flow](/flows/guides/device-auth/call-api-device-auth) +- [Setting up a Device Code Grant using the Management Dashboard](/api-auth/config/using-the-auth0-dashboard) \ No newline at end of file diff --git a/articles/api/authentication/api-authz/_get-token.md b/articles/api/authentication/api-authz/_get-token.md deleted file mode 100644 index 9738635486..0000000000 --- a/articles/api/authentication/api-authz/_get-token.md +++ /dev/null @@ -1,675 +0,0 @@ -# Get Token - -Use this endpoint to: -- Get an Access Token in order to call an API. Optionally, you can also retrieve an ID Token and a Refresh Token. -- Refresh your Access Token using a Refresh Token you got during authorization. - -Note that the only OAuth 2.0 flows that can retrieve a Refresh Token are: -- [Authorization Code Flow (Authorization Code)](/flows/concepts/auth-code) -- [Authorization Code Flow with PKCE (Authorization Code with PKCE)](/flows/concepts/auth-code-pkce) -- [Resource Owner Password](/api-auth/grant/password) -- [Device Authorization Flow](/flows/concepts/device-auth) -- Token Exchange\* - -\* Only for certain native social profiles - -## Authorization Code Flow - -```http -POST https://${account.namespace}/oauth/token -Content-Type: application/x-www-form-urlencoded - -grant_type=authorization_code&client_id=${account.clientId}&client_secret=YOUR_CLIENT_SECRET&code=AUTHORIZATION_CODE&redirect_uri=${account.callback} -``` - -```shell -curl --request POST \ - --url 'https://${account.namespace}/oauth/token' \ - --header 'content-type: application/x-www-form-urlencoded' \ - --data 'grant_type=authorization_code&client_id=${account.clientId}&client_secret=YOUR_CLIENT_SECRET&code=AUTHORIZATION_CODE&redirect_uri=${account.callback}' -``` - -```javascript -var request = require("request"); - -var options = { method: 'POST', - url: 'https://${account.namespace}/oauth/token', - headers: { 'content-type': 'application/x-www-form-urlencoded' }, - form: - { grant_type: 'authorization_code', - client_id: '${account.clientId}', - client_secret: 'YOUR_CLIENT_SECRET', - code: 'AUTHORIZATION_CODE', - redirect_uri: '${account.callback}' } - }; - -request(options, function (error, response, body) { - if (error) throw new Error(error); - - console.log(body); -}); -``` - -> RESPONSE SAMPLE: - -```JSON -HTTP/1.1 200 OK -Content-Type: application/json -{ - "access_token":"eyJz93a...k4laUWw", - "refresh_token":"GEbRxBN...edjnXbL", - "id_token":"eyJ0XAi...4faeEoQ", - "token_type":"Bearer", - "expires_in":86400 -} -``` - -<%= include('../../../_includes/_http-method', { - "http_badge": "badge-success", - "http_method": "POST", - "path": "/oauth/token", - "link": "#authorization-code" -}) %> - -This is the flow that regular web apps use to access an API. Use this endpoint to exchange an Authorization Code for a Token. - - -### Request Parameters - -| Parameter | Description | -|:-----------------|:------------| -| `grant_type`
Required | Denotes the flow you are using. For Authorization Code, use `authorization_code`. | -| `client_id`
Required | Your application's Client ID. | -| `client_secret`
Required | Your application's Client Secret. | -| `code`
Required | The Authorization Code received from the initial `/authorize` call. | -| `redirect_uri`| This is required only if it was set at the [GET /authorize](#authorization-code-grant) endpoint. The values must match. | - - -### Test with Authentication API Debugger - -<%= include('../../../_includes/_test-this-endpoint') %> - -If you have just executed the [Authorization Code Grant](#authorization-code-grant), you should already have a code set at the **Authorization Code** field of the *OAuth2 / OIDC* tab. If so, click **OAuth2 Code Exchange**; otherwise, follow the instructions. - -1. At the *Configuration* tab, set the **Application** field to the application you want to use for the test. - -1. Copy the **Callback URL** and set it as part of the **Allowed Callback URLs** of your [Application Settings](${manage_url}/#/applications). - -1. At the *OAuth2 / OIDC* tab, set the field **Authorization Code** to the code you retrieved from the [Authorization Code Grant](#authorization-code-grant). Click **OAuth2 Code Exchange**. - - -### More Information - -- [Authorization Code Flow](/flows/concepts/auth-code) -- [Call API using Authorization Code Flow](/flows/guides/auth-code/call-api-auth-code) - - -## Authorization Code Flow with PKCE - -```http -POST https://${account.namespace}/oauth/token -Content-Type: application/x-www-form-urlencoded - -grant_type=authorization_code&client_id=${account.clientId}&code_verifier=CODE_VERIFIER&code=AUTHORIZATION_CODE&redirect_uri=${account.callback} -``` - -```shell -curl --request POST \ - --url 'https://${account.namespace}/oauth/token' \ - --header 'content-type: application/x-www-form-urlencoded' \ - --data 'grant_type=authorization_code&client_id=${account.clientId}&code_verifier=CODE_VERIFIER&code=AUTHORIZATION_CODE&redirect_uri=${account.callback}' -``` - -```javascript -var request = require("request"); - -var options = { method: 'POST', - url: 'https://${account.namespace}/oauth/token', - headers: { 'content-type': 'application/x-www-form-urlencoded' }, - form: { - grant_type:"authorization_code", - client_id: "${account.clientId}", - code_verifier: "CODE_VERIFIER", - code: "AUTHORIZATION_CODE", - redirect_uri: "${account.callback}", } }; - -request(options, function (error, response, body) { - if (error) throw new Error(error); - - console.log(body); -}); -``` - -> RESPONSE SAMPLE: - -```JSON -HTTP/1.1 200 OK -Content-Type: application/json -{ - "access_token":"eyJz93a...k4laUWw", - "refresh_token":"GEbRxBN...edjnXbL", - "id_token":"eyJ0XAi...4faeEoQ", - "token_type":"Bearer", - "expires_in":86400 -} -``` - -<%= include('../../../_includes/_http-method', { - "http_badge": "badge-success", - "http_method": "POST", - "path": "/oauth/token", - "link": "#authorization-code-pkce-" -}) %> - -This is the flow that mobile apps use to access an API. Use this endpoint to exchange an Authorization Code for a Token. - - -### Request Parameters - -| Parameter | Description | -|:-----------------|:------------| -| `grant_type`
Required | Denotes the flow you are using. For Authorization Code (PKCE) use `authorization_code`. | -| `client_id`
Required | Your application's Client ID. | -| `code`
Required | The Authorization Code received from the initial `/authorize` call. | -| `code_verifier`
Required | Cryptographically random key that was used to generate the `code_challenge` passed to `/authorize`. | -| `redirect_uri` | This is required only if it was set at the [GET /authorize](#authorization-code-grant-pkce-) endpoint. The values must match. | - - -### Test with Authentication API Debugger - -<%= include('../../../_includes/_test-this-endpoint') %> - -If you have just executed the [Authorization Code Grant (PKCE)](#authorization-code-grant-pkce-) you should already have the **Authorization Code** and **Code Verifier** fields, of the *OAuth2 / OIDC* tab, set. If so, click **OAuth2 Code Exchange**, otherwise follow the instructions. - -1. At the *Configuration* tab, set the **Client** field to the application you want to use for the test. - -1. Copy the **Callback URL** and set it as part of the **Allowed Callback URLs** of your [Application Settings](${manage_url}/#/applications). - -1. At the *OAuth2 / OIDC* tab, set the field **Authorization Code** to the code you retrieved from [Authorization Code Grant](#authorization-code-grant-pkce-), and the **Code Verifier** to the key. Click **OAuth2 Code Exchange**. - - -### More Information - -- [Authorization Code Flow with Proof Key for Code Exchange (PKCE)](/flows/concepts/auth-code-pkce) -- [Call API Using the Authorization Code Flow with PKCE](/flows/guides/auth-code-pkce/call-api-auth-code-pkce) - - -## Client Credentials Flow - -```http -POST https://${account.namespace}/oauth/token -Content-Type: application/x-www-form-urlencoded - -audience=API_IDENTIFIER&grant_type=client_credentials&client_id=${account.clientId}&client_secret=YOUR_CLIENT_SECRET -``` - -```shell -curl --request POST \ - --url 'https://${account.namespace}/oauth/token' \ - --header 'content-type: application/x-www-form-urlencoded' \ - --data 'audience=API_IDENTIFIER&grant_type=client_credentials&client_id=${account.clientId}&client_secret=YOUR_CLIENT_SECRET' -``` - -```javascript -var request = require("request"); - -var options = { method: 'POST', - url: 'https://${account.namespace}/oauth/token', - headers: { 'content-type': 'application/x-www-form-urlencoded' }, - form: - { client_id: '${account.clientId}', - client_secret: 'YOUR_CLIENT_SECRET', - audience: 'API_IDENTIFIER', - grant_type: 'client_credentials' } - }; - -request(options, function (error, response, body) { - if (error) throw new Error(error); - - console.log(body); -}); -``` - -> RESPONSE SAMPLE: - -```JSON -HTTP/1.1 200 OK -Content-Type: application/json -{ - "access_token":"eyJz93a...k4laUWw", - "token_type":"Bearer", - "expires_in":86400 -} -``` - -<%= include('../../../_includes/_http-method', { - "http_badge": "badge-success", - "http_method": "POST", - "path": "/oauth/token", - "link": "#client-credentials" -}) %> - -This is the OAuth 2.0 grant that server processes use to access an API. Use this endpoint to directly request an Access Token by using the Client's credentials (a Client ID and a Client Secret). - -### Request Parameters - -| Parameter | Description | -|:-----------------|:------------| -| `grant_type`
Required | Denotes the flow you are using. For Client Credentials use `client_credentials`. | -| `client_id`
Required | Your application's Client ID. | -| `client_secret`
Required | Your application's Client Secret. | -| `audience`
Required | The unique identifier of the target API you want to access. | - - -### Test with Authentication API Debugger - -<%= include('../../../_includes/_test-this-endpoint') %> - -1. At the *Configuration* tab, set the **Client** field to the application you want to use for the test. - -1. Copy the **Callback URL** and set it as part of the **Allowed Callback URLs** of your [Application Settings](${manage_url}/#/applications). - -1. At the *OAuth2 / OIDC* tab, click **OAuth2 Client Credentials**. - - -### More Information - -- [Client Credentials Flow](/flows/concepts/client-credentials) -- [Call API using the Client Credentials Flow](/flows/guides/client-credentials/call-api-client-credentials) -- [Setting up a Client Grant using the Management Dashboard](/api-auth/config/using-the-auth0-dashboard) -- [Asking for Access Tokens for a Client Credentials Grant](/api-auth/config/asking-for-access-tokens) - - -## Resource Owner Password - -```http -POST https://${account.namespace}/oauth/token -Content-Type: application/x-www-form-urlencoded - -grant_type=password&username=USERNAME&password=PASSWORD&audience=API_IDENTIFIER&scope=SCOPE&client_id=${account.clientId}&client_secret=YOUR_CLIENT_SECRET -``` - -```shell -curl --request POST \ - --url 'https://${account.namespace}/oauth/token' \ - --header 'content-type: application/x-www-form-urlencoded' \ - --data 'grant_type=password&username=USERNAME&password=PASSWORD&audience=API_IDENTIFIER&scope=SCOPE&client_id=${account.clientId}&client_secret=YOUR_CLIENT_SECRET' -``` - -```javascript -var request = require("request"); - -var options = { method: 'POST', - url: 'https://${account.namespace}/oauth/token', - headers: { 'content-type': 'application/x-www-form-urlencoded' }, - form: - { grant_type: 'password', - username: 'USERNAME', - password: 'PASSWORD', - audience: 'API_IDENTIFIER', - scope: 'SCOPE', - client_id: '${account.clientId}', - client_secret: 'YOUR_CLIENT_SECRET' } - }; - -request(options, function (error, response, body) { - if (error) throw new Error(error); - - console.log(body); -}); -``` - -> RESPONSE SAMPLE: - -```JSON -HTTP/1.1 200 OK -Content-Type: application/json -{ - "access_token":"eyJz93a...k4laUWw", - "token_type":"Bearer", - "expires_in":86400 -} -``` - -<%= include('../../../_includes/_http-method', { - "http_badge": "badge-success", - "http_method": "POST", - "path": "/oauth/token", - "link": "#resource-owner-password" -}) %> - -:::warning -This flow should only be used from highly-trusted applications that **cannot do redirects**. If you can use redirect-based flows from your app, we recommend using the [Authorization Code Flow](#regular-web-app-login-flow) instead. -::: - -This is the OAuth 2.0 grant that highly-trusted apps use to access an API. In this flow, the end-user is asked to fill in credentials (username/password), typically using an interactive form in the user-agent (browser). This information is sent to the backend and from there to Auth0. It is therefore imperative that the application is absolutely trusted with this information. For [single-page applications and native/mobile apps](/flows/concepts/auth-code-pkce), we recommend using web flows instead. - - -### Request Parameters - -| Parameter | Description | -|:-----------------|:------------| -| `grant_type`
Required | Denotes the flow you are using. For Resource Owner Password use `password`. To add realm support use `http://auth0.com/oauth/grant-type/password-realm`. | -| `client_id`
Required | Your application's Client ID. | -| `client_secret` | Your application's Client Secret. Required when the Token Endpoint Authentication Method field at your [Application Settings](${manage_url}/#/applications) is `Post` or `Basic`. | -| `audience` | The unique identifier of the target API you want to access. | -| `username`
Required | Resource Owner's identifier, such as a username or email address. | -| `password`
Required | Resource Owner's secret. | -| `scope` | String value of the different scopes the application is asking for. Multiple scopes are separated with whitespace. | -| `realm` | String value of the realm the user belongs. Set this if you want to add realm support at this grant. For more information on what realms are refer to [Realm Support](/api-auth/grant/password#realm-support). | - -### Request headers - -| Parameter | Description | -|:-----------------|:------------| -| `auth0-forwarded-for` | End-user IP as a string value. Set this if you want brute-force protection to work in server-side scenarios. For more information on how and when to use this header, refer to [Using resource owner password from server-side](/api-auth/tutorials/using-resource-owner-password-from-server-side). | - -### Test with Authentication API Debugger - -<%= include('../../../_includes/_test-this-endpoint') %> - -1. At the *Configuration* tab, set the **Client** field to the application you want to use for the test. - -1. Copy the **Callback URL** and set it as part of the **Allowed Callback URLs** of your [Application Settings](${manage_url}/#/applications). - -1. At the *OAuth2 / OIDC* tab, set the **Username** and **Password**, and click **Password Grant**. - - -### Remarks - -- The scopes issued to the application may differ from the scopes requested. In this case, a `scope` parameter will be included in the response JSON. -- If you don't request specific scopes, all scopes defined for the audience will be returned due to the implied trust to the application in this grant. You can customize the scopes returned in a rule. For more information, refer to [Calling APIs from Highly Trusted Applications](/api-auth/grant/password). -- To add realm support set the `grant_type` to `http://auth0.com/oauth/grant-type/password-realm`, and the `realm` to the realm the user belongs. This maps to a connection in Auth0. For example, if you have configured a database connection for your internal employees and you have named the connection `employees`, then use this value. For more information on how to implement this refer to: [Realm Support](/api-auth/tutorials/password-grant#realm-support). -- In addition to username and password, Auth0 may also require the end-user to provide an additional factor as proof of identity before issuing the requested scopes. In this case, the request described above will return an `mfa_required` error along with an `mfa_token`. You can use these tokens to request a challenge for the possession factor and validate it accordingly. For details refer to [Resource Owner Password and MFA](#resource-owner-password-and-mfa). - -### More Information -- [Calling APIs from Highly-Trusted Applications](/api-auth/grant/password) -- [Executing the Resource Owner Password Grant](/api-auth/tutorials/password-grant) -- [Multi-factor Authentication and Resource Owner Password](/mfa/guides/mfa-api/multifactor-resource-owner-password) - -## Device Authorization Flow - -```http -POST https://${account.namespace}/oauth/token -Content-Type: application/x-www-form-urlencoded - -client_id=${account.clientId}&device_code=YOUR_DEVICE_CODE&grant_type=urn:ietf:params:oauth:grant-type:device_code -``` - -```shell -curl --request POST \ - --url 'https://${account.namespace}/oauth/token' \ - --header 'content-type: application/x-www-form-urlencoded' \ - --data 'client_id=${account.clientId}&device_code=YOUR_DEVICE_CODE&grant_type=urn:ietf:params:oauth:grant-type:device_code' -``` - -```javascript -var request = require("request"); - -var options = { method: 'POST', - url: 'https://${account.namespace}/oauth/token', - headers: { 'content-type': 'application/x-www-form-urlencoded' }, - form: - { client_id: '${account.clientId}', - device_code: 'YOUR_DEVICE_CODE', - grant_type: 'urn:ietf:params:oauth:grant-type:device_code' } - }; - -request(options, function (error, response, body) { - if (error) throw new Error(error); - - console.log(body); -}); -``` - -> RESPONSE SAMPLE: - -```JSON -HTTP/1.1 200 OK -Content-Type: application/json -{ - "access_token": "eyJz93a...k4laUWw", - "id_token": "eyJ...0NE", - "refresh_token": "eyJ...MoQ", - "scope": "...", - "expires_in": 86400, - "token_type": "Bearer" -} -``` - -```JSON -HTTP/1.1 403 Forbidden -Content-Type: application/json - { - // Can be retried - "error": "authorization_pending", - "error_description": "User has yet to authorize device code." - } -``` - -```JSON -HTTP/1.1 429 Too Many Requests -Content-Type: application/json - { - // Can be retried - "error": "slow_down", - "error_description": "You are polling faster than the specified interval of 5 seconds." - } -``` - -```JSON -HTTP/1.1 403 Forbidden -Content-Type: application/json - { - // Cannot be retried; transaction failed - "error": "access_denied|invalid_grant|...", - "error_description": "Failure: User cancelled the confirmation prompt or consent page; the code expired; there was an error." - } -``` - -<%= include('../../../_includes/_http-method', { - "http_badge": "badge-success", - "http_method": "POST", - "path": "/oauth/token", - "link": "#device-auth" -}) %> - -This is the OAuth 2.0 grant that input-constrained devices use to access an API. Poll this endpoint using the interval returned with your [device code](/api/authentication#get-device-code) to directly request an Access Token using the application's credentials (a Client ID) and a device code. - -### Request Parameters - -| Parameter | Description | -|:-----------------|:------------| -| `grant_type`
Required | Denotes the flow you are using. For Device Authorization, use `urn:ietf:params:oauth:grant-type:device_code`. | -| `client_id`
Required | Your application's Client ID. | -| `device_code`
Required | The device code previously returned from the [/oauth/device/code endpoint](/api/authentication#device-authorization-flow). | - -### Remarks -- Because you will be polling this endpoint (using the `interval` from the initial response to determine frequency) while waiting for the user to go to the verification URL and enter their user code, you will likely receive at least one failure before receiving a successful response. See sample responses for possible responses. - -### More Information - -- [Device Authorization Flow](/flows/concepts/device-auth) -- [Call API using the Device Authorization Flow](/flows/guides/device-auth/call-api-device-auth) -- [Setting up a Device Code Grant using the Management Dashboard](/api-auth/config/using-the-auth0-dashboard) - -## Refresh Token - -```http -POST https://${account.namespace}/oauth/token -Content-Type: application/x-www-form-urlencoded - -grant_type=refresh_token&client_id=${account.clientId}&client_secret=YOUR_CLIENT_SECRET&refresh_token=YOUR_REFRESH_TOKEN -``` - -```shell -curl --request POST \ - --url 'https://${account.namespace}/oauth/token' \ - --header 'content-type: application/x-www-form-urlencoded' \ - --data 'grant_type=refresh_token&client_id=${account.clientId}&client_secret=YOUR_CLIENT_SECRET&refresh_token=YOUR_REFRESH_TOKEN' -``` - -```javascript -var request = require("request"); - -var options = { method: 'POST', - url: 'https://${account.namespace}/oauth/token', - headers: { 'content-type': 'application/x-www-form-urlencoded' }, - form: - { grant_type: 'refresh_token', - client_id: '${account.clientId}', - client_secret: 'YOUR_CLIENT_SECRET', - refresh_token: 'YOUR_REFRESH_TOKEN'} - }; - -request(options, function (error, response, body) { - if (error) throw new Error(error); - - console.log(body); -}); -``` - -> RESPONSE SAMPLE: - -```JSON -HTTP/1.1 200 OK -Content-Type: application/json -{ - "access_token": "eyJ...MoQ", - "expires_in": 86400, - "scope": "openid offline_access", - "id_token": "eyJ...0NE", - "token_type": "Bearer" -} -``` - -<%= include('../../../_includes/_http-method', { - "http_badge": "badge-success", - "http_method": "POST", - "path": "/oauth/token", - "link": "#refresh-token" -}) %> - -Use this endpoint to refresh an Access Token using the Refresh Token you got during authorization. - - -### Request Parameters - -| Parameter | Description | -|:-----------------|:------------| -| `grant_type`
Required | Denotes the flow you are using. To refresh a token, use `refresh_token`. | -| `client_id`
Required | Your application's Client ID. | -| `client_secret` | Your application's Client Secret. Required when the Token Endpoint Authentication Method field at your [Application Settings](${manage_url}/#/applications) is `Post` or `Basic`. | -| `refresh_token`
Required | The Refresh Token to use. | -| `scope` | A space-delimited list of requested scope permissions. If not sent, the original scopes will be used; otherwise you can request a reduced set of scopes. Note that this must be URL encoded. | - - -### Test this endpoint - -<%= include('../../../_includes/_test-this-endpoint') %> - -1. At the *Configuration* tab, set the **Client** field to the client you want to use for the test. - -1. Copy the **Callback URL** and set it as part of the **Allowed Callback URLs** of your [Application Settings](${manage_url}/#/applications). - -1. At the *OAuth2 / OIDC* tab, set the field **Refresh Token** to the Refresh Token you have. Click **OAuth2 Refresh Token Exchange**. - -### More Information - -- [Refresh Tokens](/tokens/concepts/refresh-tokens) - -## Token Exchange for Native Social - -```http -POST https://${account.namespace}/oauth/token -Content-Type: application/x-www-form-urlencoded - -grant_type=urn:ietf:params:oauth:grant-type:token-exchange&subject_token=SUBJECT_TOKEN&subject_token_type=SUBJECT_TOKEN_TYPE&client_id=${account.clientId}&audience=API_IDENTIFIER&scope=SCOPE -``` - -```shell -curl --request POST \ - --url 'https://${account.namespace}/oauth/token' \ - --header 'content-type: application/x-www-form-urlencoded' \ - --data 'grant_type=urn:ietf:params:oauth:grant-type:token-exchange&subject_token=SUBJECT_TOKEN&subject_token_type=SUBJECT_TOKEN_TYPE&client_id=${account.clientId}&audience=API_IDENTIFIER&scope=SCOPE' - }' -``` - -```javascript -var request = require("request"); - -var options = { method: 'POST', - url: 'https://${account.namespace}/oauth/token', - headers: { 'content-type': 'application/x-www-form-urlencoded' }, - form: - { grant_type: 'urn:ietf:params:oauth:grant-type:token-exchange', - subject_token: 'SUBJECT_TOKEN', - subject_token_type: 'SUBJECT_TOKEN_TYPE', - client_id: '${account.clientId}', - audience: 'API_IDENTIFIER', - scope: 'SCOPE', - }; - -request(options, function (error, response, body) { - if (error) throw new Error(error); - - console.log(body); -}); -``` - -> RESPONSE SAMPLE: - -```JSON -HTTP/1.1 200 OK -Content-Type: application/json -{ - "access_token": "eyJz93a...k4laUWw", - "id_token": "eyJ...0NE", - "refresh_token": "eyJ...MoQ", - "expires_in":86400, - "token_type":"Bearer" -} -``` - -<%= include('../../../_includes/_http-method', { - "http_badge": "badge-success", - "http_method": "POST", - "path": "/oauth/token", - "link": "#token-exchange-native-social" -}) %> - -:::warning -This flow is intended for use with native social interactions **only**. Use of this flow outside of a native social setting is highly discouraged. -::: - -When a non-browser-based solution (such as a mobile platform's SDK) authenticates the user, the authentication will commonly result in artifacts being returned to application code. In such situations, this grant type allows for the Auth0 platform to accept artifacts from trusted sources and issue tokens in response. In this way, apps making use of non-browser-based authentication mechanisms (as are common in native apps) can still retrieve Auth0 tokens without asking for further user interaction. - -Artifacts returned by this flow (and the contents thereof) will be determined by the `subject_token_type` and configuration settings of the tenant. - -### Request Parameters - -| Parameter | Description | -|:-----------------|:------------| -| `grant_type`
Required | Denotes the flow you are using. For Token Exchange for Native Social, use `urn:ietf:params:oauth:grant-type:token-exchange`. | -| `subject_token`
Required | Externally-issued identity artifact, representing the user. | -| `subject_token_type`
Required | Identifier that indicates the type of `subject_token`. Currently supported native social values are: `http://auth0.com/oauth/token-type/apple-authz-code`. | -| `client_id`
Required | Your application's Client ID. | -| `audience` | The unique identifier of the target API you want to access. | -| `scope` | String value of the different scopes the application is requesting. Multiple scopes are separated with whitespace. | -| `user_profile`
Only For `apple-authz-code` | Optional element used for native iOS interactions for which profile updates can occur. Expected parameter value will be JSON in the form of: `{ name: { firstName: 'John', lastName: 'Smith }}` | - -### Request headers - -| Parameter | Description | -|:-----------------|:------------| -| `auth0-forwarded-for` | End-user IP as a string value. Set this if you want brute-force protection to work in server-side scenarios. For more information on how and when to use this header, refer to [Using resource owner password from server-side](/api-auth/tutorials/using-resource-owner-password-from-server-side). | - -### Remarks - -- The scopes issued to the application may differ from the scopes requested. In this case, a `scope` parameter will be included in the response JSON. -- If you don't request specific scopes, all scopes defined for the audience will be returned due to the implied trust to the application in this grant. You can customize the scopes returned in a rule. For more information, refer to [Calling APIs from Highly Trusted Applications](/api-auth/grant/password). - -### More Information -- [Add Sign In with Apple to Native iOS Apps](/connections/apple-siwa/add-siwa-to-native-app) -- [iOS Swift - Sign In with Apple Quickstart](/quickstart/native/ios-swift-siwa) - diff --git a/articles/api/authentication/api-authz/_highly-regulated.md b/articles/api/authentication/api-authz/_highly-regulated.md new file mode 100644 index 0000000000..b013129593 --- /dev/null +++ b/articles/api/authentication/api-authz/_highly-regulated.md @@ -0,0 +1,232 @@ +# Authorization Code Flow with Enhanced Privacy Protection +## Push Authorization Requests (PAR) + +<%= include('../../../_includes/_http-method', { + "http_badge": "badge-primary", + "http_method": "POST", + "path": "/oauth/par", + "link": "##push-authorization-requests-par-" +}) %> + +```http +POST ${account.namespace}/oauth/par +Content-Type: 'application/x-www-form-urlencoded' + audience={https://yourApi/}& + response_type=code|code id_token& + client_id={yourClientId}& + redirect_uri={https://yourApp/callback}& + state=STATE& + scope=openid|profile|email& + code_challenge=CODE_CHALLENGE& + code_challenge_method=S256& + nonce=NONCE& + connection=CONNECTION& + prompt=login|consent|none& + organisation=ORGANIZATION +``` + +```javascript +var request = require("request"); + +var options = { method: 'POST', + url: 'https://{yourDomain}/oauth/par, + headers: { 'content-type': 'application/x-www-form-urlencoded' }, + form: { + audience: '{https://yourApi/}', + response_type: 'code|code id_token', + client_id: '{yourClientId}', + redirect_uri: '{https://yourApp/callback}', + state: 'STATE', + scope: 'openid|profile|email', + authorization_details: JSON.stringify([{ type: 'my_type' }]), + code_challenge: 'CODE_CHALLENGE', + code_challenge_method: 'S256', + nonce: 'NONCE', + connection: 'CONNECTION', + prompt: 'login|consent|none' + organisation: 'ORGANIZATION' + } +}; + +request(options, function (error, response, body) { + if (error) throw new Error(error); + + console.log(body); +}); + +``` + +```shell +curl --request POST \ + --url 'https://{yourDomain}/oauth/par' \ + --header 'content-type: application/x-www-form-urlencoded' \ +--data 'audience={https://yourApi/}response_type=code|code id_token&client_id={yourClientId}&redirect_uri={https://yourApp/callback}&state=STATE&scope=openid|profile|email&authorization_details='[{"type":"my_type"}]' +&code_challenge=CODE_CHALLENGE&code_challenge_method=S256&nonce=NONCE&connection=CONNECTION&prompt=login|consent|none&organisation=ORGANIZATION' + +``` + +> RESPONSE SAMPLE: + +``` json +/** +If the request is successful, `/oauth/par` responds with a `JSON` object containing the `request_uri` property, which can be used at the authorization endpoint, and the `expires_in` value, which indicates the number of seconds the `request_uri` is valid. +*/ + +HTTP/1.1 201 Created +Content-Type: application/json + +{ + "request_uri": + "urn:ietf:params:oauth:request_uri:6esc_11ACC5bwc014ltc14eY22c", + "expires_in": 30 +} +``` + +::: note +Highly Regulated Identity is currently available for Enterprise customers under Limited Early Access. To learn more about this program, contact [Auth0 Support](http://support.auth0.com/). +::: +

+ +Authorization Code Flow with [Pushed Authorization Requests (PAR)](/get-started/authentication-and-authorization-flow/authorization-code-flow/authorization-code-flow-with-par) uses the `/oauth/par` endpoint to allow applications to send the authorization parameters usually sent in a `GET` request to `/authorize`. PAR uses a POST method from the backend to keep parameter values secure. The `/oauth/par` endpoint accepts all authorization parameters which can be proivided to `/authorize`. Assuming the call to the `/oauth/par` endpoint is valid, Auth0 will respond with a `redirect_uri` value that can be used as a parameter for the `/authorize` endpoint. + +Assuming the call to the `/oauth/par` endpoint is valid, Auth0 will respond with a `redirect_uri` value also used as a parameter for the `/authorize` endpoint. To learn more about configuring PAR, read [Configure Pushed Authorization Requests (PAR)](/get-started/applications/configure-par). + +## Request Parameters +| Parameter | Description | +|:-----------------|:------------| +|`authorization_details`| Requested permissions for each resource. Similar to scopes. To learn more, read [RAR reference documention](https://auth0.com/docs/get-started/authentication-and-authorization-flow/authorization-code-flow/authorization-code-flow-with-rar). | +|`audience`| The unique identifier of the target API you want to access. | +| `response_type`
Required | Specifies the token type. We recommend you use `code` to request an authorization code, or code `id_token` to receive an authorization code and a [detached signature](https://openid.net/specs/openid-financial-api-part-2-1_0.html#id-token-as-detached-signature). | +| `client_id`
Required | The `client_id` of your application. | +| `redirect_uri`
Required | The URL to which Auth0 will redirect the browser after authorization has been granted by the user. Specify the `redirect_uri` under your [Application's Settings](${manage_url}/#/applications).| +| `state`
Recommended | An opaque value the application adds to the initial request that the authorization server includes when redirecting the back to the application. This value must be used by the application to prevent CSRF attacks. | +| `scope`
Recommended| OIDC scopes and custom API scopes. For example: `openid read:timesheets`. Include `offline_access` to get a refresh token.| +| `code_challenge`
Recommended | OIDC scopes and custom API scopes. For example: `openid read:timesheets`. Include `offline_access` to get a refresh token. | +| `code_challenge_method`
Recommended | Method used to generate the challenge. The PKCE specification defines two methods, `S256` and plain, however, Auth0 supports only S256 since the latter is discouraged. [Authorization Code Flow with Proof Key for Code Exchange (PKCE)] (/get-started/authentication-and-authorization-flow/authorization-code-flow-with-pkce).| +| `nonce`
Recommended | A string value which will be included in the ID token response from Auth0, used to prevent token replay attacks. It is required for `response_type=id_token` token. | +| `connection` | The name of the connection configured to your application. If null, it will redirect to the [Auth0 Login Page](https://${account.namespace}/login) and show the Login Widget using the first database connection. | +| `prompt` | Can be used to force a particular prompt to display, e.g. `prompt=consent` will always display the consent prompt.| +| `organization` | ID of the organization to use when authenticating a user. When not provided, if your application is configured to **Display Organization Prompt**, the user will be able to enter the organization name when authenticating. | + +## Remarks +- To make a call to the PAR endpoint, you must: + - Set the request content type as `application/x-www-form-urlencoded` + - Use `strings` for all passed parameters + - Include an additional parameter for application authentication in the request (e.g. `client_secret`, or `client_assertion` and `client_assertion_type` for JSON Web Token Client Authentication, or pass a `client-certificate` and `client-certificate-ca-verified` header when using Mutual TLS). +- Use the `authorization_details` parameter to request permission for each resource. For example, you can specify an array of JSON objects to convey fine-grained information on the authorization. Each JSON object must contain a `type` attribute. The rest is up to you to define. + +## Authorize + +<%= include('../../../_includes/_http-method', { + "http_badge": "badge-primary", + "http_method": "GET", + "path": "/authorize", + "link": "#redirect-from-par-to-authorize" +}) %> + +```http +GET https://{yourDomain}/authorize + request_uri={yourRequestUri}& + client_id={yourClientId} +``` + +After calling the `/oauth/par` endpoint, redirect the end user to the `/authorize` endpoint using a `GET` call. + +:::note +The `/authorize` endpoint will respond based on the parameters passed to the `/oauth/par` endpoint. If you request a `response_type`, you should receive an authorization code to use at the `/oauth/token` endpoint. +::: + +### Request Parameters +| Parameter | Description | +|:-----------------|:------------| +| `client_id`
Required | The `client_id` of your application. | +| `request_uri`
Required | The `request_uri` value that was received from the `/oauth/par` endpoint. | + +### Exchange an Authorization Code for a Token + +<%= include('../../../_includes/_http-method', { + "http_badge": "badge-primary", + "http_method": "POST", + "path": "/oauth/token", + "link": "#exchange-an-authorization-code-for-a-token" +}) %> + +```http +POST https://{yourDomain}/oauth/par +Content-Type: 'application/x-www-form-urlencoded' + grant_type=code|code id_token& + client_id={yourClientId}& + code=CODE& + redirect_uri={https://yourApp/callback}& + code_verifier=CODE_VERIFIER +``` + +```javascript +curl --request POST \ + --url 'https://{yourDomain}/oauth/par' \ + --header 'content-type: application/x-www-form-urlencoded' \ +--data 'grant_type=authorization_code& client_id={yourClientId}& code=CODE&redirect_uri={https://yourApp/callback}&code_verifier=CODE_VERIFIER' +``` + +```shell +var request = require("request"); + +var options = { method: 'POST', + url: 'https://{yourDomain}/oauth/token, + headers: { 'content-type': 'application/x-www-form-urlencoded' }, + form: { + grant_type: 'authorization_code', + client_id: '{yourClientId}', + code: 'CODE', + redirect_uri: '{https://yourApp/callback}', + code_verifier: 'CODE_VERIFIER' + } +}; + +request(options, function (error, response, body) { + if (error) throw new Error(error); + + console.log(body); +}); +``` + +> RESPONSE SAMPLE: +``` json +/** +The `/oauth/token` endpoint will respond with a JSON object containing an `id_token` property, and potentially also a `refresh_token` if one was requested. +*/ +HTTP/1.1 200 OK +Content-Type: application/json +{ + "refresh_token":"GEbRxBN...edjnXbL", + "access_token":"eybRxBN...edjnXZQ", + "id_token":"eyJ0XAi...4faeEoQ", + "token_type":"Bearer", + "expires_in":86400, + "authrorization_details":[ + { + "type":"my_type", + "other_attributes_of_my_type":"value"} + ] +}, + + +``` + +When users are redirected back to your callback, you need to make a `POST` call to the `oauth/token` endpoint to exchange an authorization code for an access and/or an ID token. + +### Request Parameters +| Parameter | Description | +|:-----------------|:------------| +| `grant_type`
Required | Denotes the flow. Assuming you have an authorization code from the `/authorize` endpoint, use `authorization_code`. | +| `code` | The authorization code from the initial `/authorize` call. | +| `client_id`
Required | The `client_id` of your application. | +| `request_uri`
Required | This is required only if it was set at the `GET` `/oauth/par` endpoint. The values from `/authorize` must match the value you set at `/oauth/token`. | +| `code_verifier`
Recommended | Cryptographically random key used to generate the `code_challenge` passed to `/oauth/par`. If the `code_challenge` parameter is passed in the call to `/oauth/par`, this is required. | + +### Remarks + +To make a call to `/oauth/token` endpoint, you must: +- Set the request content type as `application/x-www-form-urlencoded` +- Use `strings` for all passed parameters +- Include an additional parameter for application authentication in the request (e.g. `client_secret`, or `client_assertion` and `client_assertion_type` for JSON Web Token Client Authentication, or pass a `client-certificate` and `client-certificate-ca-verified` header when using Mutual TLS). \ No newline at end of file diff --git a/articles/api/authentication/api-authz/_implicit.md b/articles/api/authentication/api-authz/_implicit.md new file mode 100644 index 0000000000..a938f156f3 --- /dev/null +++ b/articles/api/authentication/api-authz/_implicit.md @@ -0,0 +1,61 @@ +# Implicit Flow + +## Authorize + +```http +GET https://${account.namespace}/authorize? + audience=API_IDENTIFIER& + scope=SCOPE& + response_type=token|id_token|id_token token& + client_id=${account.clientId}& + redirect_uri=${account.callback}& + state=STATE& + nonce=NONCE +``` + +> RESPONSE SAMPLE + +```text +HTTP/1.1 302 Found +Location: ${account.callback}#access_token=TOKEN&state=STATE&token_type=TYPE&expires_in=SECONDS +``` + +<%= include('../../../_includes/_http-method', { + "http_badge": "badge-primary", + "http_method": "GET", + "path": "/authorize", + "link": "#implicit-grant" +}) %> + +This is the OAuth 2.0 grant that web apps utilize in order to access an API. + +### Request Parameters + +| Parameter | Description | +|:-----------------|:------------| +| `audience`
| The unique identifier of the target API you want to access. | +| `scope` | The scopes which you want to request authorization for. These must be separated by a space. You can request any of the [standard OpenID Connect (OIDC) scopes](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims) about users, such as `profile` and `email`. Custom claims that must [conform to a namespaced format](/tokens/guides/create-namespaced-custom-claims), or any scopes supported by the target API (for example, `read:contacts`). | +| `response_type`
Required | This will specify the type of token you will receive at the end of the flow. Use `token` to get only an Access Token, `id_token` to get only an ID token (if you don't plan on accessing an API), or `id_token token` to get both an ID token and an Access Token. | +| `client_id`
Required | Your application's ID. | +| `state`
Recommended | An opaque value the application adds to the initial request that Auth0 includes when redirecting back to the application. This value must be used by the application to prevent CSRF attacks. | +| `redirect_uri` | The URL to which Auth0 will redirect the browser after authorization has been granted by the user. | +| `nonce`
Recommended | A string value which will be included in the ID token response from Auth0, [used to prevent token replay attacks](/api-auth/tutorials/nonce). It is required for `response_type=id_token token`. | +| `connection` | The name of the connection configured for your application. | +| `prompt` | To initiate a [silent authentication](/api-auth/tutorials/silent-authentication) request, use `prompt=none` (To learn more, read the Remarks). | +| `organization` | ID of the [organization](/organizations) to use when authenticating a user. When not provided, if your application is configured to **Display Organization Prompt**, the user will be able to enter the organization name when authenticating. | +| `invitation` | Ticket ID of the organization invitation. When [inviting a member to an Organization](/organizations/invite-members), your application should handle invitation acceptance by forwarding the invitation and organization key-value pairs when the user accepts the invitation. | + +### Remarks + +- The `redirect_uri` value must be specified as a valid callback URL under your [Application's Settings](${manage_url}/#/applications). +- If `response_type=token`, after the user authenticates with the provider, this will redirect them to your application callback URL while passing the `access_token` in the address `location.hash`. This is used for Single-Page Apps and on Native Mobile SDKs. +- The Implicit Grant does not support the issuance of Refresh Tokens. Use [Silent Authentication](/api-auth/tutorials/silent-authentication) instead. +- In order to improve compatibility for applications, Auth0 will now return profile information in a [structured claim format as defined by the OIDC specification](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims). This means that in order to add custom claims to ID tokens or Access Tokens, they must [conform to a namespaced format](/tokens/guides/create-namespaced-custom-claims) to avoid possible collisions with standard OIDC claims. +- Silent Authentication lets you perform an authentication flow where Auth0 will only reply with redirects, and never with a login page. When an Access Token has expired, silent authentication can be used to retrieve a new one without user interaction, assuming the user's Single Sign-on (SSO) session has not expired. + +### Learn More + +- [Implicit Flow](/flows/concepts/implicit) +- [State Parameter](/protocols/oauth2/oauth-state) +- [Mitigate replay attacks when using the Implicit Grant](/api-auth/tutorials/nonce) +- [Silent Authentication](/api-auth/tutorials/silent-authentication) \ No newline at end of file diff --git a/articles/api/authentication/api-authz/_refresh-token.md b/articles/api/authentication/api-authz/_refresh-token.md new file mode 100644 index 0000000000..a51d17cecc --- /dev/null +++ b/articles/api/authentication/api-authz/_refresh-token.md @@ -0,0 +1,247 @@ +# Refresh Token + +```http +POST https://${account.namespace}/oauth/token +Content-Type: application/x-www-form-urlencoded + +grant_type=refresh_token&client_id=${account.clientId}&client_secret=YOUR_CLIENT_SECRET&refresh_token=YOUR_REFRESH_TOKEN +``` + +```shell +curl --request POST \ + --url 'https://${account.namespace}/oauth/token' \ + --header 'content-type: application/x-www-form-urlencoded' \ + --data 'grant_type=refresh_token&client_id=${account.clientId}&client_secret=YOUR_CLIENT_SECRET&refresh_token=YOUR_REFRESH_TOKEN' +``` + +```javascript +var request = require("request"); + +var options = { method: 'POST', + url: 'https://${account.namespace}/oauth/token', + headers: { 'content-type': 'application/x-www-form-urlencoded' }, + form: + { grant_type: 'refresh_token', + client_id: '${account.clientId}', + client_secret: 'YOUR_CLIENT_SECRET', + refresh_token: 'YOUR_REFRESH_TOKEN'} + }; + +request(options, function (error, response, body) { + if (error) throw new Error(error); + + console.log(body); +}); +``` + +> RESPONSE SAMPLE: + +```JSON +HTTP/1.1 200 OK +Content-Type: application/json +{ + "access_token": "eyJ...MoQ", + "expires_in": 86400, + "scope": "openid offline_access", + "id_token": "eyJ...0NE", + "token_type": "Bearer" +} +``` + +<%= include('../../../_includes/_http-method', { + "http_badge": "badge-success", + "http_method": "POST", + "path": "/oauth/token", + "link": "#refresh-token" +}) %> + +Use this endpoint to refresh an Access Token using the Refresh Token you got during authorization. + +### Request Parameters + +| Parameter | Description | +|:-----------------|:------------| +| `grant_type`
Required | Denotes the flow you are using. To refresh a token, use `refresh_token`. | +| `client_id`
Required | Your application's Client ID. | +| `client_secret` | Your application's Client Secret. Required when the **Token Endpoint Authentication Method** field at your [Application Settings](${manage_url}/#/applications) is `Post` or `Basic`. | +| `refresh_token`
Required | The refresh token to use. | +| `scope` | A space-delimited list of requested scope permissions. If not sent, the original scopes will be used; otherwise you can request a reduced set of scopes. Note that this must be URL encoded. | + +### Learn More + +- [Refresh Tokens](/tokens/concepts/refresh-tokens) + +## Token Exchange for Native Social + +```http +POST https://${account.namespace}/oauth/token +Content-Type: application/x-www-form-urlencoded + +grant_type=urn:ietf:params:oauth:grant-type:token-exchange&subject_token=SUBJECT_TOKEN&subject_token_type=SUBJECT_TOKEN_TYPE&client_id=${account.clientId}&audience=API_IDENTIFIER&scope=SCOPE +``` + +```shell +curl --request POST \ + --url 'https://${account.namespace}/oauth/token' \ + --header 'content-type: application/x-www-form-urlencoded' \ + --data 'grant_type=urn:ietf:params:oauth:grant-type:token-exchange&subject_token=SUBJECT_TOKEN&subject_token_type=SUBJECT_TOKEN_TYPE&client_id=${account.clientId}&audience=API_IDENTIFIER&scope=SCOPE' + }' +``` + +```javascript +var request = require("request"); + +var options = { method: 'POST', + url: 'https://${account.namespace}/oauth/token', + headers: { 'content-type': 'application/x-www-form-urlencoded' }, + form: + { grant_type: 'urn:ietf:params:oauth:grant-type:token-exchange', + subject_token: 'SUBJECT_TOKEN', + subject_token_type: 'SUBJECT_TOKEN_TYPE', + client_id: '${account.clientId}', + audience: 'API_IDENTIFIER', + scope: 'SCOPE', + }; + +request(options, function (error, response, body) { + if (error) throw new Error(error); + + console.log(body); +}); +``` + +> RESPONSE SAMPLE: + +```JSON +HTTP/1.1 200 OK +Content-Type: application/json +{ + "access_token": "eyJz93a...k4laUWw", + "id_token": "eyJ...0NE", + "refresh_token": "eyJ...MoQ", + "expires_in":86400, + "token_type":"Bearer" +} +``` + +<%= include('../../../_includes/_http-method', { + "http_badge": "badge-success", + "http_method": "POST", + "path": "/oauth/token", + "link": "#token-exchange-native-social" +}) %> + +:::warning +This flow is intended for use with native social interactions **only**. Use of this flow outside of a native social setting is highly discouraged. +::: + +When a non-browser-based solution (such as a mobile platform's SDK) authenticates the user, the authentication will commonly result in artifacts being returned to application code. In such situations, this grant type allows for the Auth0 platform to accept artifacts from trusted sources and issue tokens in response. In this way, apps making use of non-browser-based authentication mechanisms (as are common in native apps) can still retrieve Auth0 tokens without asking for further user interaction. + +Artifacts returned by this flow (and the contents thereof) will be determined by the `subject_token_type` and the tenant's configuration settings. + +### Request Parameters + +| Parameter | Description | +|:-----------------|:------------| +| `grant_type`
Required | Denotes the flow you are using. For Token Exchange for Native Social, use `urn:ietf:params:oauth:grant-type:token-exchange`. | +| `subject_token`
Required | Externally-issued identity artifact representing the user. | +| `subject_token_type`
Required | Identifier that indicates the type of `subject_token`. | +| `client_id`
Required | Your application's Client ID. | +| `audience` | The unique identifier of the target API you want to access. | +| `scope` | String value of the different scopes the application is requesting. Multiple scopes are separated with whitespace. | +| `user_profile`
Only For `apple-authz-code` | Optional element used for native iOS interactions for which profile updates can occur. Expected parameter value will be JSON in the form of: `{ name: { firstName: 'John', lastName: 'Smith }}` | + +### Request Parameters + +| Parameter | Description | +|:-----------------|:------------| +| `auth0-forwarded-for` | End user IP as a string value. Set this if you want brute-force protection to work in server-side scenarios. To learn more about how and when to use this header, read [Using resource owner password from server-side](/api-auth/tutorials/using-resource-owner-password-from-server-side). | + +### Remarks + +- The scopes issued to the application may differ from the requested scopes. In this case, a `scope` parameter will be included in the response JSON. +- If you don't request specific scopes, all scopes defined for the audience will be returned due to the implied trust to the application in this grant. You can customize the scopes returned in a rule. To learn more, read [Calling APIs from Highly Trusted Applications](/api-auth/grant/password). + +### Learn More +- [Add Sign In with Apple to Native iOS Apps](/connections/apple-siwa/add-siwa-to-native-app) +- [iOS Swift - Sign In with Apple Quickstart](/quickstart/native/ios-swift-siwa) + +## Revoke Refresh Token + +```http +POST https://${account.namespace}/oauth/revoke +Content-Type: application/json +{ + "client_id": "${account.clientId}", + "client_secret": "YOUR_CLIENT_SECRET", + "token": "YOUR_REFRESH_TOKEN", +} +``` + +```shell +curl --request POST \ + --url 'https://${account.namespace}/oauth/revoke' \ + --header 'content-type: application/json' \ + --data '{ "client_id": "${account.clientId}", "client_secret": "YOUR_CLIENT_SECRET", "token": "YOUR_REFRESH_TOKEN" }' +``` + +```javascript +var request = require("request"); + +var options = { method: 'POST', + url: 'https://${account.namespace}/oauth/revoke', + headers: { 'content-type': 'application/json' }, + body: + { client_id: '${account.clientId}', + client_secret: 'YOUR_CLIENT_SECRET', + token: 'YOUR_REFRESH_TOKEN' }, + json: true }; + +request(options, function (error, response, body) { + if (error) throw new Error(error); + + console.log(body); +}); +``` + +> RESPONSE SAMPLE: + +```JSON +HTTP/1.1 200 OK +(empty-response-body) +``` + +<%= include('../../../_includes/_http-method', { + "http_badge": "badge-success", + "http_method": "POST", + "path": "/oauth/revoke", + "link": "#revoke-refresh-token" +}) %> + +Use this endpoint to invalidate a Refresh Token if it has been compromised. + +The behaviour of this endpoint depends on the state of the [Refresh Token Revocation Deletes Grant](https://auth0.com/docs/tokens/refresh-tokens/revoke-refresh-tokens#refresh-tokens-and-grants) toggle. +If this toggle is enabled, then each revocation request invalidates not only the specific token, but all other tokens based on the same authorization grant. This means that **all Refresh Tokens that have been issued for the same user, application, and audience will be revoked**. +If this toggle is disabled, then only the refresh token is revoked, while the grant is left intact. + +### Request Parameters + +| Parameter | Description | +|:-----------------|:------------| +| `client_id`
Required | The `client_id` of your application. | +| `client_assertion`| A JWT containing a signed assertion with your application credentials. Required when Private Key JWT is your application authentication method.| +| `client_assertion_type`| The value is `urn:ietf:params:oauth:client-assertion-type:jwt-bearer`. Required when Private Key JWT is the application authentication method.| +| `client_secret` | The `client_secret` of your application. Required when Client Secret Basic or Client Secret Post is the application authentication method. Specifically required for Regular Web Applications **only**. | +| `token`
Required | The Refresh Token you want to revoke. | + +### Remarks + +- For non-confidential applications that cannot keep the Client Secret safe (for example, native apps), the endpoint supports passing no Client Secret but the application itself must have the property `tokenEndpointAuthMethod` set to `none`. You can do this either from the UI ([Dashboard > Applications > Application Settings](${manage_url}/#/applications)) or using the [Management API](/api/management/v2#!/Applications/patch_applications_by_id). + +### Error Codes + +For the complete error code reference for this endpoint refer to [Errors > POST /oauth/revoke](#post-oauth-revoke). + +### Learn More + +- [Refresh Tokens](/tokens/concepts/refresh-tokens) diff --git a/articles/api/authentication/api-authz/_resource-owner.md b/articles/api/authentication/api-authz/_resource-owner.md new file mode 100644 index 0000000000..12aa1927eb --- /dev/null +++ b/articles/api/authentication/api-authz/_resource-owner.md @@ -0,0 +1,96 @@ +# Resource Owner Password Flow + +## Get Token +```http +POST https://${account.namespace}/oauth/token +Content-Type: application/x-www-form-urlencoded + +grant_type=password&username=USERNAME&password=PASSWORD&audience=API_IDENTIFIER&scope=SCOPE&client_id=${account.clientId}&client_secret=YOUR_CLIENT_SECRET +``` + +```shell +curl --request POST \ + --url 'https://${account.namespace}/oauth/token' \ + --header 'content-type: application/x-www-form-urlencoded' \ + --data 'grant_type=password&username=USERNAME&password=PASSWORD&audience=API_IDENTIFIER&scope=SCOPE&client_id=${account.clientId}&client_secret=YOUR_CLIENT_SECRET' +``` + +```javascript +var request = require("request"); + +var options = { method: 'POST', + url: 'https://${account.namespace}/oauth/token', + headers: { 'content-type': 'application/x-www-form-urlencoded' }, + form: + { grant_type: 'password', + username: 'USERNAME', + password: 'PASSWORD', + audience: 'API_IDENTIFIER', + scope: 'SCOPE', + client_id: '${account.clientId}', + client_secret: 'YOUR_CLIENT_SECRET' } + }; + +request(options, function (error, response, body) { + if (error) throw new Error(error); + + console.log(body); +}); +``` + +> RESPONSE SAMPLE: + +```JSON +HTTP/1.1 200 OK +Content-Type: application/json +{ + "access_token":"eyJz93a...k4laUWw", + "token_type":"Bearer", + "expires_in":86400 +} +``` + +<%= include('../../../_includes/_http-method', { + "http_badge": "badge-success", + "http_method": "POST", + "path": "/oauth/token", + "link": "#resource-owner-password" +}) %> + +:::warning +This flow should only be used from highly-trusted applications that **cannot do redirects**. If you can use redirect-based flows from your app, we recommend using the [Authorization Code Flow](#regular-web-app-login-flow) instead. +::: + +This is the OAuth 2.0 grant that highly-trusted apps use to access an API. In this flow, the end-user is asked to fill in credentials (username/password), typically using an interactive form in the user-agent (browser). This information is sent to the backend and from there to Auth0. It is therefore imperative that the application is absolutely trusted with this information. For [single-page applications and native/mobile apps](/flows/concepts/auth-code-pkce), we recommend using web flows instead. + + +### Request Parameters + +| Parameter | Description | +|:-----------------|:------------| +| `grant_type`
Required | Denotes the flow you are using. For Resource Owner Password use `password`. To add realm support use `http://auth0.com/oauth/grant-type/password-realm`. | +| `client_id`
Required | Your application's Client ID. | +| `client_secret` | Your application's Client Secret. Required when the Token Endpoint Authentication Method field at your [Application Settings](${manage_url}/#/applications) is `Post` or `Basic`. | +| `audience` | The unique identifier of the target API you want to access. | +| `username`
Required | Resource Owner's identifier, such as a username or email address. | +| `password`
Required | Resource Owner's secret. | +| `scope` | String value of the different scopes the application is asking for. Multiple scopes are separated with whitespace. | +| `realm` | String value of the realm the user belongs. Set this if you want to add realm support at this grant. For more information on what realms are refer to [Realm Support](/api-auth/grant/password#realm-support). | + +### Request headers + +| Parameter | Description | +|:-----------------|:------------| +| `auth0-forwarded-for` | End-user IP as a string value. Set this if you want brute-force protection to work in server-side scenarios. For more information on how and when to use this header, refer to [Using resource owner password from server-side](/api-auth/tutorials/using-resource-owner-password-from-server-side). | + +### Remarks + +- The scopes issued to the application may differ from the scopes requested. In this case, a `scope` parameter will be included in the response JSON. +- If you don't request specific scopes, all scopes defined for the audience will be returned due to the implied trust to the application in this grant. You can customize the scopes returned in a rule. For more information, refer to [Calling APIs from Highly Trusted Applications](/api-auth/grant/password). +- To add realm support set the `grant_type` to `http://auth0.com/oauth/grant-type/password-realm`, and the `realm` to the realm the user belongs. This maps to a connection in Auth0. For example, if you have configured a database connection for your internal employees and you have named the connection `employees`, then use this value. For more information on how to implement this refer to: [Realm Support](/api-auth/tutorials/password-grant#realm-support). +- In addition to username and password, Auth0 may also require the end-user to provide an additional factor as proof of identity before issuing the requested scopes. In this case, the request described above will return an `mfa_required` error along with an `mfa_token`. You can use these tokens to request a challenge for the possession factor and validate it accordingly. For details refer to [Resource Owner Password and MFA](#resource-owner-password-and-mfa). + +### Learn More +- [Calling APIs from Highly-Trusted Applications](/api-auth/grant/password) +- [Executing the Resource Owner Password Grant](/api-auth/tutorials/password-grant) +- [Multi-factor Authentication and Resource Owner Password](/mfa/guides/mfa-api/multifactor-resource-owner-password) \ No newline at end of file diff --git a/articles/api/authentication/api-authz/_revoke-refersh-token.md b/articles/api/authentication/api-authz/_revoke-refersh-token.md deleted file mode 100644 index 8f9d33c557..0000000000 --- a/articles/api/authentication/api-authz/_revoke-refersh-token.md +++ /dev/null @@ -1,80 +0,0 @@ -# Revoke Refresh Token - -```http -POST https://${account.namespace}/oauth/revoke -Content-Type: application/json -{ - "client_id": "${account.clientId}", - "client_secret": "YOUR_CLIENT_SECRET", - "token": "YOUR_REFRESH_TOKEN", -} -``` - -```shell -curl --request POST \ - --url 'https://${account.namespace}/oauth/revoke' \ - --header 'content-type: application/json' \ - --data '{ "client_id": "${account.clientId}", "client_secret": "YOUR_CLIENT_SECRET", "token": "YOUR_REFRESH_TOKEN" }' -``` - -```javascript -var request = require("request"); - -var options = { method: 'POST', - url: 'https://${account.namespace}/oauth/revoke', - headers: { 'content-type': 'application/json' }, - body: - { client_id: '${account.clientId}', - client_secret: 'YOUR_CLIENT_SECRET', - token: 'YOUR_REFRESH_TOKEN' }, - json: true }; - -request(options, function (error, response, body) { - if (error) throw new Error(error); - - console.log(body); -}); -``` - -> RESPONSE SAMPLE: - -```JSON -HTTP/1.1 200 OK -(empty-response-body) -``` - -<%= include('../../../_includes/_http-method', { - "http_badge": "badge-success", - "http_method": "POST", - "path": "/oauth/revoke", - "link": "#revoke-refresh-token" -}) %> - -Use this endpoint to invalidate a Refresh Token if it has been compromised. - -The behaviour of this endpoint depends on the state of the [Refresh Token Revocation Deletes Grant](https://auth0.com/docs/tokens/refresh-tokens/revoke-refresh-tokens#refresh-tokens-and-grants) toggle. -If this toggle is enabled, then each revocation request invalidates not only the specific token, but all other tokens based on the same authorization grant. This means that **all Refresh Tokens that have been issued for the same user, application, and audience will be revoked**. -If this toggle is disabled, then only the refresh token is revoked, while the grant is left intact. - - -### Request Parameters - -| Parameter | Description | -|:-----------------|:------------| -| `client_id`
Required | The `client_id` of your application. | -| `client_assertion`| A JWT containing a signed assertion with your application credentials. Required when Private Key JWT is your application authentication method.| -| `client_assertion_type`| The value is `urn:ietf:params:oauth:client-assertion-type:jwt-bearer`. Required when Private Key JWT is the application authentication method.| -| `client_secret` | The `client_secret` of your application. Required when Client Secret Basic or Client Secret Post is the application authentication method. Specifically required for Regular Web Applications **only**. | -| `token`
Required | The Refresh Token you want to revoke. | - -### Remarks - -- For non-confidential applications that cannot keep the Client Secret safe (for example, native apps), the endpoint supports passing no Client Secret but the application itself must have the property `tokenEndpointAuthMethod` set to `none`. You can do this either from the UI ([Dashboard > Applications > Application Settings](${manage_url}/#/applications)) or using the [Management API](/api/management/v2#!/Applications/patch_applications_by_id). - -### Error Codes - -For the complete error code reference for this endpoint refer to [Errors > POST /oauth/revoke](#post-oauth-revoke). - -### More Information - -- [Refresh Tokens](/tokens/concepts/refresh-tokens) diff --git a/articles/api/authentication/errors/_errors.md b/articles/api/authentication/errors/_errors.md index 6b4bc8efe2..3b9163d8ae 100644 --- a/articles/api/authentication/errors/_errors.md +++ b/articles/api/authentication/errors/_errors.md @@ -1,95 +1,21 @@ # Standard Error Responses The Authentication API may return the following HTTP Status Codes: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
StatusDescriptionMessage
400Bad Request{"error": "invalid_request", "error_description": "..."}
400Bad Request{"error": "invalid_scope", "error_description": "..."}
400Bad Request{"error": "invalid_scope", "error_description": "Scope must be an array or a string"}
401Unauthorized{"error": "invalid_client", "error_description": "..."}
401Unauthorized{"error": "requires_validation", "error_description": "Suspicious request requires verification"}
403Forbidden{"error": "unauthorized_client", "error_description": "..."}
403Forbidden{"error": "access_denied", "error_description": "..."}
403Forbidden{"error": "access_denied", "error_description": "Unknown or invalid refresh token"}
403Forbidden{"error": "invalid_grant", "error_description": "..."}
404Not Found{"error": "endpoint_disabled", "error_description": "..."}
405Method Not Allowed{"error": "method_not_allowed", "error_description": "..."}
429Too Many Requests{"error": "too_many_requests", "error_description": "..."}
500Internal Server Error 
501Not Implemented{"error": "unsupported_response_type", "error_description": "..."}
501Not Implemented{"error": "unsupported_grant_type", "error_description": "..."}
503Service Unavailable{"error": "temporarily_unavailable", "error_description": "..."}
+| Status | JSON Response | +| :---------------- | :------------ | +| 400 Bad Request|`{"error": "invalid_request", "error_description": "..."}`| +| 400 Bad Request| `{"error": "invalid_request", "error_description": "..."}`| +| 400 Bad Request| `{"error": "invalid_scope", "error_description": "Scope must be an array or a string"}`| +| 401 Unauthorized| `{"error": "invalid_client", "error_description": "..."}`| +| 401 Unauthorized| `{"error": "requires_validation", "error_description": "Suspicious request requires verification"}`| +| 403 Forbidden| `{"error": "unauthorized_client", "error_description": "..."}`| +| 403 Forbidden| `{"error": "access_denied", "error_description": "..."}`| +| 403 Forbidden| `{"error": "access_denied", "error_description": "Unknown or invalid refresh token"}`| +| 403 Forbidden| `{"error": "invalid_grant", "error_description": "..."}`| +| 404 Not Found| `{"error": "endpoint_disabled", "error_description": "..."}`| +| 405 Method Not Allowed| `{"error": "method_not_allowed", "error_description": "..."}`| +| 429 Too Many Requests| `{"error": "too_many_requests", "error_description": "..."}`| +| 500 Internal Server Error | | +| 501 Not Implemented| `{"error": "unsupported_response_type", "error_description": "..."}`| +| 501 Not Implemented| `{"error": "unsupported_grant_type", "error_description": "..."}`| +| 503 Service Unavailable| `{"error": "temporarily_unavailable", "error_description": "..."}`| \ No newline at end of file diff --git a/articles/api/authentication/errors/_oauth-access_token.md b/articles/api/authentication/errors/_oauth-access_token.md index 6572e237b4..44b0f7541e 100644 --- a/articles/api/authentication/errors/_oauth-access_token.md +++ b/articles/api/authentication/errors/_oauth-access_token.md @@ -1,36 +1,10 @@ # POST /oauth/access_token - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
StatusResponse
400{"error": "invalid_request", "error_description": "the connection was disabled"}
The connection is not active or not enabled for your client_id
400{"error": "invalid_request", "error_description": "the connection was not found"}
400{"error": "invalid_request", "error_description": "missing client_id parameter"}
400{"error": "invalid_request", "error_description": "missing access_token parameter"}
401{"error": "invalid_request", "error_description": "invalid access_token: invalid_token"}
The access_token is invalid or does not contain the scope you set
403{"error": "unauthorized_client", "error_description": "invalid client"}
+| Status | JSON Response | +| :--------------- |:------------- | +| 400 Bad Request | `{"error": "invalid_request", "error_description": "the connection was disabled"}`
The connection is not active or not enabled for your `client_id`.| +| 400 Bad Request | `{"error": "invalid_request", "error_description": "the connection was not found"}` | +| 400 Bad Request | `{"error": "invalid_request", "error_description": "missing client_id parameter"}` | +| 400 Bad Request | `{"error": "invalid_request", "error_description": "missing access_token parameter"}` | +| 401 Unauthorized | `{"error": "invalid_request", "error_description": "invalid access_token: invalid_token"}`
The `access_token` is invalid or does not contain the set `scope`| +| 403 Forbidden | `{"error": "unauthorized_client", "error_description": "invalid client"}` | \ No newline at end of file diff --git a/articles/api/authentication/errors/_oauth-revoke.md b/articles/api/authentication/errors/_oauth-revoke.md index 106df5917c..5b97ccb4f9 100644 --- a/articles/api/authentication/errors/_oauth-revoke.md +++ b/articles/api/authentication/errors/_oauth-revoke.md @@ -1,24 +1,7 @@ # POST /oauth/revoke - - - - - - - - - - - - - - - - - - - - - -
StatusDescription
200{"error": "invalid_request", "error_description": "..."}
The Refresh Token is revoked, does not exist, or was not issued to the client making the revocation request.
400{"error": "invalid_request", "error_description": "..."}
The required parameters were not sent in the request.
401<{"error": "invalid_client", "error_description": "..."}
The request is not authorized. Check that the client credentials (client_id and client_secret) are present in the request and hold valid values.
+| Status | JSON Response | +| :--------------- | :------------ | +|200 Success | `{"error": "invalid_request", "error_description": "..."}`
The Refresh Token is revoked, does not exist, or was not issued to the client making the revocation request| +|400 Bad Request | `{"error": "invalid_request", "error_description": "..."}` he required parameters were not sent in the request.| +|401 Unauthorized | `{"error": "invalid_client", "error_description": "..."}`
The request is not authorized. Check that the client credentials `client_id` and client_secret` are present in the request and hold valid values. | \ No newline at end of file diff --git a/articles/api/authentication/errors/_oauth-ro.md b/articles/api/authentication/errors/_oauth-ro.md index eec021ca4f..e552af873a 100644 --- a/articles/api/authentication/errors/_oauth-ro.md +++ b/articles/api/authentication/errors/_oauth-ro.md @@ -2,111 +2,33 @@ ## Grant type: jwt-bearer - - - - - - - - - - - - - - - - - - - - - -
StatusDescription
400{"error": "invalid_request", "error_description": "missing device parameter"}
You need to provide a device name for the caller device (like a browser, app, and so on)
400{"error": "invalid_request", "error_description": "missing id_token parameter"}
For this grant type you need to provide a JWT ID Token
400{"error": "invalid_grant", "error_description": "..."}
Errors related to an invalid ID Token or user
+| Status | JSON Response | +| :----------------| :------------ | +|400 Bad Request|`{"error": "invalid_request", "error_description": "missing device parameter"}`
You need to provide a device name for the caller device (like a browser, app, and so on) | +|400 Bad Request|`{"error": "invalid_request", "error_description": "missing id_token parameter"}`
For this grant type you need to provide a JWT ID Token | +|400 Bad Request|`{"error": "invalid_grant", "error_description": "..."}`
Errors related to an invalid ID Token or user | ## Grant type: password - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
StatusDescription
400{"error": "invalid_request", "error_description": "scope parameter must be a string"}
Incorrect scope formatting; each scope must be separated by whitespace
400{"error": "invalid_request", "error_description": "specified strategy does not support requested operation"}
The connection/provider does not implement username/password authentication
401{"error": "invalid_user_password", "error_description": "Wrong email or password."}
401{"error": "unauthorized", "error_description": "user is blocked"}
401{ "error": "password_leaked", "error_description": "This login has been blocked because your password has been leaked in another website. We’ve sent you an email with instructions on how to unblock it."}
401{ "error": "requires_verification", "error_description": "Suspicious request requires verification" }
429{"error": "too_many_attempts", "error_description": "..."}
Some attack protection features will return this error
429{"error": "too_many_logins", "error_description": "..."}
Some attack protection features will return this error
+| Status | JSON Response | +| :----------------| :------------ | +| 400 Bad Request|`{"error": "invalid_request", "error_description": "scope parameter must be a string"}`
Incorrect scope formatting; each scope must be separated by whitespace| +| 400 Bad Request|`{"error": "invalid_request", "error_description": "specified strategy does not support requested operation"}`
The connection/provider does not implement username/password authentication | +| 401 Unauthorized|`{"error": "invalid_user_password", "error_description": "Wrong email or password."}`| +| 401 Unauthorized|`{"error": "unauthorized", "error_description": "user is blocked"}`| +| 401 Unauthorized|`{ "error": "password_leaked", "error_description": "This login has been blocked because your password has been leaked in another website. We’ve sent you an email with instructions on how to unblock it."}`| +| 401 Unauthorized|`{ "error": "requires_verification", "error_description": "Suspicious request requires verification" }`| +| 429 Too Many Requests|`{"error": "too_many_attempts", "error_description": "..."}`
Some attack protection features will return this error| +| 429 Too Many Requests|`{"error": "too_many_logins", "error_description": "..."}`
Some attack protection features will return this error| ## All grant types - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
StatusDescription
400{"error": "invalid_request", "error_description": "missing client_id parameter"}
400{"error": "invalid_request", "error_description": "the connection was disabled"}
Check the connection in the dashboard, you may have turned it off for the provided client_id
400{"error": "invalid_request", "error_description": "The connection is not yet configured..."}
The connection is not properly configured with custom scripts
400{"error": "invalid_request", "error_description": "the connection was not found for tenant..."}
The connection does not belong to the tenant; check your base url
400{"error": "invalid_request", "error_description": "Fields with "." are not allowed, please remove all dotted fields..."}
If you are using rules, some field name contains dots
403{"error": "unauthorized_client", "error_description": "invalid client"}
The provided client_id is not valid
403{"error": "access_denied", "error_description": "..."}
Validation of specific points raised an access issue
\ No newline at end of file +| Status | JSON Response | +| :--------------- | :----------- | +| 400 Bad Request |`{"error": "invalid_request", "error_description": "missing client_id parameter"}<`| +| 400 Bad Request |`{"error": "invalid_request", "error_description": "the connection was disabled"}`
Check the connection in the dashboard, you may have turned it off for the provided `client_id` | +| 400 Bad Request |`{"error": "invalid_request", "error_description": "The connection is not yet configured..."}`
The connection is not properly configured with custom scripts| +| 400 Bad Request |`{"error": "invalid_request", "error_description": "the connection was not found for tenant..."}`
The connection does not belong to the tenant; check your base url | +| 400 Bad Request |`{"error": "invalid_request", "error_description": "Fields with "." are not allowed, please remove all dotted fields..."}`
If you are using rules, some field name contains dots | +| 403 Forbidden |`{"error": "unauthorized_client", "error_description": "invalid client"}`
The provided `client_id` is not valid | +| 403 Forbidden |`{"error": "access_denied", "error_description": "..."}`
Validation of specific points raised an access issue | \ No newline at end of file diff --git a/articles/api/authentication/errors/_passwordless-start.md b/articles/api/authentication/errors/_passwordless-start.md index 15814aa9ac..348b707a16 100644 --- a/articles/api/authentication/errors/_passwordless-start.md +++ b/articles/api/authentication/errors/_passwordless-start.md @@ -1,56 +1,25 @@ + # POST /passwordless/start - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
StatusResponse
400{"error": "bad.tenant","error_description": "error in tenant - tenant validation failed: invalid_tenant"}
400{"error": "bad.client_id", "error_description": "Missing required property: client_id"}
400{"error": "bad.connection", "error_description": "Missing required property: connection"}
400{"error": "bad.connection", "error_description": "Connection does not exist"}
400{"error": "bad.connection", "error_description": "Connection is disabled"}
400{"error": "bad.connection", "error_description": "Invalid connection strategy. It must either be a passwordless connection"}
400{"error": "bad.authParams", "error_description": "error in authParams - invalid type: string (expected object)"}
400{"error": "bad.request", "error_description": "the following properties are not allowed: "}
400{"error": "bad.phone_number", "error_description": "Missing required property: phone_number"}
400{"error": "bad.phone_number", "error_description": "String does not match pattern: ^\\+[0-9]{1,15}$"}
400{"error": "sms_provider_error", "error_description": " (Code: )"}
+| Status | JSON Response | +| :----------------| :------------ | +|400 Bad Request|`{"error": "bad.tenant","error_description": "error in tenant - tenant validation failed: invalid_tenant"}`| +|400 Bad Request|`{"error": "bad.client_id", "error_description": "Missing required property: client_id"}`| +|400 Bad Request|`{"error": "bad.connection", "error_description": "Missing required property: connection"}`| +|400 Bad Request|`{"error": "bad.connection", "error_description": "Connection does not exist"}`| +|400 Bad Request|`{"error": "bad.connection", "error_description": "Connection is disabled"}`| +|400 Bad Request|`{"error": "bad.connection", "error_description": "Invalid connection strategy. It must either be a passwordless connection"}`| +|400 Bad Request|`{"error": "bad.authParams", "error_description": "error in authParams - invalid type: string (expected object)"}`| +|400 Bad Request|`{"error": "bad.request", "error_description": "the following properties are not allowed: "}`| +|400 Bad Request|`{"error": "bad.phone_number", "error_description": "Missing required property: phone_number"}`| +|400 Bad Request|`{"error": "bad.phone_number", "error_description": "String does not match pattern: ^\\+[0-9]{1,15}$"}`| +|400 Bad Request|`{"error": "sms_provider_error", "error_description": " (Code: )"}`| +|400 Bad Request|`{"error": "invalid_request","error_description": "Expected `auth0-forwarded-for` header to be a valid IP address."}`| +|400 Bad Request|`{"error": "bad.tenant","error_description": "error in tenant - could not find tenant in params"}`| +|400 Bad Request|`{"error": "server_error","error_description": "error resolving client"}`| +|400 Bad Request|`{"error": "invalid_request","error_description": "The client_id in the authentication header does not match the client_id in the payload"}`| +|400 Bad Request|`{"error": "bad.connection","error_description": "Public signup is disabled"}`| +|400 Bad Request|`{"error": "bad.connection","error_description": "Unknown error"}`| +|401 Unauthorized|`{"error": "server_error","error_description": "user is blocked"}`| +|403 Forbidden|`{"error": "unauthorized_client","error_description": "Client authentication is required"}`| +|500 Internal Server Error|`{"error": "server_error","error_description": "IdP Error"}`| \ No newline at end of file diff --git a/articles/api/authentication/errors/_passwordless-verify.md b/articles/api/authentication/errors/_passwordless-verify.md index 78b478a56e..1ea71461b4 100644 --- a/articles/api/authentication/errors/_passwordless-verify.md +++ b/articles/api/authentication/errors/_passwordless-verify.md @@ -1,72 +1,22 @@ # POST /passwordless/verify - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
StatusDescription
400{"error": "invalid_request", "error_description": "missing username parameter"}
400{"error": "invalid_request", "error_description": "missing password parameter"}
400{"error": "invalid_request", "error_description": "missing connection parameter"}
400{"error": "invalid_request", "error_description": "scope parameter must be a string"}
Incorrect scope formatting; each scope must be separated by whitespace
400{"error": "invalid_request", "error_description": "missing client_id parameter"}
400{"error": "invalid_request", "error_description": "the connection was not found"}
400{"error": "invalid_request", "error_description": "the connection was disabled"}
Check the connection in the dashboard, you may have turned it off for the provided client_id
400{"error": "invalid_request", "error_description": "the connection was not found for tenant..."}
The connection does not belong to the tenant; check your base url
400{"error": "invalid_request", "error_description": "Fields with "." are not allowed, please remove all dotted fields..."}
If you are using rules, some field name contains dots
401{"error": "invalid_user_password", "error_description": "Wrong email or password."}
401{"error": "unauthorized", "error_description": "user is blocked"}
403{"error": "unauthorized_client", "error_description": "invalid client"}
The provided client_id is not valid
403{"error": "access_denied", "error_description": "..."}
Validation of specific points raised an access issue
429{"error": "too_many_attempts", "error_description": "..."}
Some attack protection features will return this error
429{"error": "too_many_logins", "error_description": "..."}
Some attack protection features will return this error
+| Status | JSON Response | +| :----------------| :------------ | +|400 Bad Request|`{"error": "invalid_request", "error_description": "missing username parameter"}`| +|400 Bad Request|`{"error": "invalid_request", "error_description": "scope parameter must be a string"}`
Incorrect scope formatting; each scope must be separated by whitespace| +|400 Bad Request|`{"error": "invalid_request", "error_description": "missing client_id parameter"}`| +|400 Bad Request|`{"error": "invalid_request", "error_description": "the connection was not found"}`| +|400 Bad Request|`{"error": "invalid_request", "error_description": "the connection was disabled"}`
Check the connection in the dashboard, you may have turned it off for the provided `client_id`| +|400 Bad Request|`{"error": "invalid_request", "error_description": "the connection was not found for tenant..."}`
The connection does not belong to the tenant; check your base url| +|400 Bad Request|`{"error": "invalid_request", "error_description": "Fields with "." are not allowed, please remove all dotted fields..."}`
If you are using rules, some field name contains dots| +|400 Bad Request|`"error": "bad.tenant","error_description": "error in tenant - could not find tenant in params"`| +|400 Bad Request|`{"error": "bad.tenant","error_description": "error in tenant - tenant validation failed: "}`| +|400 Bad Request|`{"error": "bad.connection","error_description": "Connection does not exist"}`| +|400 Bad Request|`{"error": "bad.connection","error_description": "Invalid connection strategy. It must either be a passwordless connection"}`| +|400 Bad Request|`{"error": "bad.connection","error_description": "The connection is disabled"}`| +|401 Unauthorized|`{"error": "invalid_user_password", "error_description": "Wrong email or password."}`| +|401 Unauthorized|`{"error": "unauthorized", "error_description": "user is blocked"}`| +|403 Forbidden|`{"error": "unauthorized_client", "error_description": "invalid client"}`
The provided `client_id` is not valid| +|403 Forbidden|`{"error": "access_denied", "error_description": "..."}`
Validation of specific points raised an access issue| +|429 Too Many Requests|`{"error": "too_many_attempts", "error_description": "..."}`
Some attack protection features will return this error| +|500 Bad Request|`{"error": "server_error","error_description": "..."}`| \ No newline at end of file diff --git a/articles/api/authentication/index.md b/articles/api/authentication/index.md index 5942e9da93..71075483e0 100644 --- a/articles/api/authentication/index.md +++ b/articles/api/authentication/index.md @@ -55,13 +55,28 @@ contentType: <%= include('./api-authz/_authz-client') %>
- <%= include('./api-authz/_device-code') %> + <%= include('./api-authz/_auth-code-flow') %> +
+
+ <%= include('./api-authz/_auth-code-pkce') %>> +
+
+ <%= include('./api-authz/_highly-regulated') %>> +
+
+ <%= include('./api-authz/_client-credential') %>> +
+
+ <%= include('./api-authz/_implicit') %>> +
+
+ <%= include('./api-authz/_resource-owner.md') %>>
- <%= include('./api-authz/_get-token') %> + <%= include('./api-authz/_device-code') %>
- <%= include('./api-authz/_revoke-refersh-token') %> + <%= include('./api-authz/_refresh-token') %>
Legacy @@ -98,10 +113,10 @@ contentType: <%= include('./errors/_oauth-ro') %>
- <%= include('./errors/_passwordless-verify') %> + <%= include('./errors/_passwordless-start') %>
- <%= include('./errors/_passwordless-start') %> + <%= include('./errors/_passwordless-verify') %>
diff --git a/articles/api/authentication/legacy/_delegation.md b/articles/api/authentication/legacy/_delegation.md index 88ad6dc99a..a173755d24 100644 --- a/articles/api/authentication/legacy/_delegation.md +++ b/articles/api/authentication/legacy/_delegation.md @@ -1,5 +1,3 @@ - - # Delegation ```http @@ -49,22 +47,10 @@ Given an existing token, this endpoint will generate a new token signed with the | `client_id`
Required | Τhe `client_id` of your app | | `grant_type`
Required | Use `urn:ietf:params:oauth:grant-type:jwt-bearer`| | `id_token` or `refresh_token`
Required | The existing token of the user. | -| `target ` | The target `client_id` | +| `target` | The target `client_id` | | `scope` | Use `openid` or `openid profile email` | | `api_type` | The API to be called. | - -### Test with Authentication API Debugger - -<%= include('../../../_includes/_test-this-endpoint') %> - -1. At the *Configuration* tab, set the **Application** field to the app you want to use for the test. - -1. Copy the **Callback URL** and set it as part of the **Allowed Callback URLs** of your [Application Settings](${manage_url}/#/applications). - -1. At the *OAuth2 / OIDC* tab, set the fields **ID Token**, **Refresh Token** and **Target Client ID**. Click **Delegation**. - - ### Remarks - The `profile` scope value requests access to the End-User's default profile Claims, which are: `name`, `family_name`, `given_name`, `middle_name`, `nickname`, `preferred_username`, `profile`, `picture`, `website`, `gender`, `birthdate`, `zoneinfo`, `locale`, and `updated_at`. @@ -81,8 +67,7 @@ Given an existing token, this endpoint will generate a new token signed with the - `X-RateLimit-Reset`: Remaining time until the rate limit (`X-RateLimit-Limit`) resets. The value is in [UTC epoch seconds](https://en.wikipedia.org/wiki/Unix_time). -### More Information +### Learn More - [Delegation Tokens](/tokens/delegation) - -- [Auth0 API Rate Limit Policy](/policies/rate-limits) +- [Auth0 API Rate Limit Policy](/policies/rate-limits) \ No newline at end of file diff --git a/articles/api/authentication/legacy/_linking.md b/articles/api/authentication/legacy/_linking.md index eeca72e100..a100e26e04 100644 --- a/articles/api/authentication/legacy/_linking.md +++ b/articles/api/authentication/legacy/_linking.md @@ -43,7 +43,7 @@ This endpoint will trigger the login flow to link an existing account with a new - The `redirect_uri` value must be specified as a valid callback URL under your [Application's Settings](${manage_url}/#/applications). -### More Information +### Learn More - [Link User Accounts](/users/guides/link-user-accounts) - [Link User Accounts Initiated by Users Scenario](/users/references/link-accounts-user-initiated-scenario) @@ -109,6 +109,6 @@ Given a logged-in user's `access_token` and `user_id`, this endpoint will unlink | `user_id`
Required | The logged-in user's `user_id` | -### More Information +### Learn More - [Unlink User Accounts](/users/guides/unlink-user-accounts) diff --git a/articles/api/authentication/legacy/_login.md b/articles/api/authentication/legacy/_login.md index 8b6cbb2b71..6396f6b091 100644 --- a/articles/api/authentication/legacy/_login.md +++ b/articles/api/authentication/legacy/_login.md @@ -1,5 +1,4 @@ - # Login ## Social with Provider's Access Token @@ -88,12 +87,10 @@ Given the social provider's Access Token and For the complete error code reference for this endpoint refer to [Errors > POST /oauth/access_token](#post-oauth-access_token). -### More Information +### Learn More - [Call an Identity Provider API](/tutorials/calling-an-external-idp-api) - - [Identity Provider Access Tokens](/tokens/overview-idp-access-tokens) - - [Add scopes/permissions to call Identity Provider's APIs](/connections/adding-scopes-for-an-external-idp) ## Database/AD/LDAP (Active) @@ -181,18 +178,6 @@ Use this endpoint for API-based (active) authentication. Given the user credenti | `device` | String value. Required when `grant_type` is `urn:ietf:params:oauth:grant-type:jwt-bearer` | | `id_token` | Used to authenticate using a token instead of username/password, in [Touch ID](/libraries/lock-ios/touchid-authentication) scenarios. Required when `grant_type` is `urn:ietf:params:oauth:grant-type:jwt-bearer` | - -### Test with Authentication API Debugger - -<%= include('../../../_includes/_test-this-endpoint') %> - -1. At the *Configuration* tab, set the fields **Application** (select the application you want to use for the test) and **Connection** (the name of the social connection to use). - -1. Copy the **Callback URL** and set it as part of the **Allowed Callback URLs** of your [Application Settings](${manage_url}/#/applications). - -1. At the *OAuth2 / OIDC* tab, set **Username** and **Password**. Click **Resource Owner Endpoint**. - - ### Remarks - This endpoint only works for database connections, passwordless connections, Active Directory/LDAP, Windows Azure AD and ADFS. @@ -206,10 +191,8 @@ Use this endpoint for API-based (active) authentication. Given the user credenti For the complete error code reference for this endpoint, refer to [Errors > POST /oauth/ro](#post-oauth-ro). -### More Information +### Learn More - [Database Identity Providers](/connections/database) - - [Rate Limits on User/Password Authentication](/policies/rate-limit-policy/database-connections-rate-limits) - -- [Active Directory/LDAP Connector](/connector) +- [Active Directory/LDAP Connector](/connector) \ No newline at end of file diff --git a/articles/api/authentication/legacy/_resource-owner.md b/articles/api/authentication/legacy/_resource-owner.md index d192bd5c36..367ddcd5b8 100644 --- a/articles/api/authentication/legacy/_resource-owner.md +++ b/articles/api/authentication/legacy/_resource-owner.md @@ -83,16 +83,6 @@ Given the user's credentials, this endpoint will authenticate the user with the | `id_token` | Used to authenticate using a token instead of username/password, in [Touch ID](/libraries/lock-ios/touchid-authentication) scenarios. | | `device` | You should set this to a string, if you are requesting a Refresh Token (`scope=offline_access`). | -### Test with Authentication API Debugger - -<%= include('../../../_includes/_test-this-endpoint') %> - -1. At the *Configuration* tab, set the **Application** field to the application you want to use for the test, and **Connection** to the name of the connection to use. - -1. Copy the **Callback URL** and set it as part of the **Allowed Callback URLs** of your [Application Settings](${manage_url}/#/applications). - -1. At the *OAuth2 / OIDC* tab, set the **Username** and **Password**, and click **Resource Owner Endpoint**. - ### Remarks - This endpoint only works for database connections, passwordless connections, Active Directory/LDAP, Windows Azure AD and ADFS. @@ -105,6 +95,6 @@ Given the user's credentials, this endpoint will authenticate the user with the For the complete error code reference for this endpoint refer to [Errors > POST /oauth/ro](#post-oauth-ro). -### More Information +### Learn More - [Calling APIs from Highly Trusted Applications](/api-auth/grant/password) diff --git a/articles/api/authentication/legacy/_userinfo.md b/articles/api/authentication/legacy/_userinfo.md index 4f1f228c34..13f5c8a8c1 100644 --- a/articles/api/authentication/legacy/_userinfo.md +++ b/articles/api/authentication/legacy/_userinfo.md @@ -1,3 +1,5 @@ + + # User Profile ## Get Token Info @@ -89,7 +91,7 @@ This endpoint validates a JSON Web Token (JWT)