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/api/authentication/_change-password.md b/articles/api/authentication/_change-password.md index 4f99e81283..50915c6c37 100644 --- a/articles/api/authentication/_change-password.md +++ b/articles/api/authentication/_change-password.md @@ -79,7 +79,7 @@ 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) diff --git a/articles/api/authentication/_introduction.md b/articles/api/authentication/_introduction.md index 965d1370b6..a4f9870415 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](https://auth0.com/docs/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). @@ -120,4 +120,4 @@ Note that for database connections Auth0 limits certain types of repeat login at If you have problems or need help with your case, you can always reach out to our [Support](${env.DOMAIN_URL_SUPPORT}). -Note that if you have a free subscription plan, and you are not in your 22-day trial period, you will not be able to access or open tickets in the [Support Center](${env.DOMAIN_URL_SUPPORT}). In this case, you can seek support through the [Auth0 Community](https://community.auth0.com/). For more info on our support program, refer to [Support Options](/support). +Note that if you have a free subscription plan, and you are not in your 22-day trial period, you will not be able to access or open tickets in the [Support Center](${env.DOMAIN_URL_SUPPORT}). In this case, you can seek support through the [Auth0 Community](https://community.auth0.com/). For more info on our support program, refer to [Support Options](/support). \ No newline at end of file diff --git a/articles/api/authentication/_login.md b/articles/api/authentication/_login.md index f170793af1..5b6dc26da4 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](https://auth0.com/docs/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,244 @@ 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 [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-) + +## Highly Regulated Identity +### Push Authorization Requests (PAR) + +<%= include('../../_includes/_http-method', { + "http_badge": "badge-primary", + "http_method": "POST", + "path": "/oauth/par", + "link": "#hri" +}) %> + +```http +POST ${account.namespace}/oauth/par +Content-Type: 'application/x-www-form-urlencoded' + 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: { + 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' + } +}; + +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 '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' +``` + +> 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/). +::: +Push Authorization Requests (PAR), a service of [Highly Regulated Identity](https://auth0.com/docs/secure/highly-regulated-identity), uses the `/oauth/par` endpoint to allow applications to send the authentication 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 standard authorization parameters similar 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 Push Authorization Requests (PAR)](/get-started/applications/configure-par). + +### Request Parameters +| Parameter | Description | +|:-----------------|:------------| +| `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 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. | +| `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). + +### Redirect from PAR to Authorize + +<%= include('../../_includes/_http-method', { + "http_badge": "badge-primary", + "http_method": "GET", + "path": "/authorize", + "link": "#hri" +}) %> + +```http +GET https://{yourDomain}/authorize + request_uri={yourRequestUri}& + client_id={yourClientId} +``` + +After calling the `/oauth/par` endpoint, redirect the end user with a `GET` call to the /authorize endpoint. + +:::note +The `/authorize` endpoint will respond based on the parameters passed to the `/oauth/par` endpoint. If you request a `response_type` of code, 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": "#hri" +}) %> + +```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' +``` + +> 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", + "id_token":"eyJ0XAi...4faeEoQ", + "token_type":"Bearer", + "expires_in":86400 +} +``` + +```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); +}); +``` + +When users are redirected to `/authorize`, 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 must match. | +| `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/_logout.md b/articles/api/authentication/_logout.md index 5443ea80f9..211464df33 100644 --- a/articles/api/authentication/_logout.md +++ b/articles/api/authentication/_logout.md @@ -49,7 +49,7 @@ Use this endpoint to logout a user. If you want to navigate the user to a specif | 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`. | @@ -70,7 +70,7 @@ Use this endpoint to logout a user. If you want to navigate the user to a specif - 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) @@ -141,18 +141,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 +150,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 +183,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..9647ac6333 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: +Learn More: - [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 @@ -118,7 +120,7 @@ If OTP is supported by the user and you don't want to request a different factor - 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. -### 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 +163,7 @@ request(options, function (error, response, body) { ``` > RESPONSE SAMPLE FOR OTP: + ```JSON HTTP/1.1 200 OK Content-Type: application/json @@ -196,7 +199,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 +242,7 @@ request(options, function (error, response, body) { ``` > RESPONSE SAMPLE FOR PENDING CHALLENGE: + ```JSON HTTP/1.1 200 OK Content-Type: application/json @@ -249,6 +253,7 @@ Content-Type: application/json ``` > RESPONSE SAMPLE FOR VERIFIED CHALLENGE: + ```JSON HTTP/1.1 200 OK Content-Type: application/json @@ -260,6 +265,7 @@ Content-Type: application/json ``` > RESPONSE SAMPLE FOR REJECTED CHALLENGE: + ```JSON HTTP/1.1 200 OK Content-Type: application/json @@ -300,7 +306,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 +348,7 @@ request(options, function (error, response, body) { ``` > RESPONSE SAMPLE FOR OTP: + ```JSON HTTP/1.1 200 OK Content-Type: application/json @@ -426,6 +433,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 +447,7 @@ Content-Type: application/json ``` > RESPONSE SAMPLE FOR OOB (Auth0 channel): + ```JSON HTTP/1.1 200 OK Content-Type: application/json @@ -452,6 +461,7 @@ Content-Type: application/json ``` > RESPONSE SAMPLE FOR OTP: + ```JSON HTTP/1.1 200 OK Content-Type: application/json @@ -495,7 +505,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 +543,7 @@ request(options, function (error, response, body) { ``` > RESPONSE SAMPLE: + ```JSON HTTP/1.1 200 OK Content-Type: application/json @@ -570,6 +581,7 @@ Content-Type: application/json } ] ``` + <%= include('../../_includes/_http-method', { "http_badge": "badge-primary", "http_method": "GET", @@ -590,7 +602,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 +638,7 @@ request(options, function (error, response, body) { ``` > RESPONSE SAMPLE: + ```JSON HTTP/1.1 204 OK ``` @@ -644,7 +657,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 +664,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/_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/_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/_authz-client.md b/articles/api/authentication/api-authz/_authz-client.md index cd711d31f2..ea4ab2070f 100644 --- a/articles/api/authentication/api-authz/_authz-client.md +++ b/articles/api/authentication/api-authz/_authz-client.md @@ -9,228 +9,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/_device-code.md b/articles/api/authentication/api-authz/_device-code.md index 76bb7dacec..c416fb393c 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 +## Device code ```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/_revoke-refersh-token.md b/articles/api/authentication/api-authz/_revoke-refersh-token.md index 8f9d33c557..d50f4be8ab 100644 --- a/articles/api/authentication/api-authz/_revoke-refersh-token.md +++ b/articles/api/authentication/api-authz/_revoke-refersh-token.md @@ -56,7 +56,6 @@ The behaviour of this endpoint depends on the state of the [Refresh Token Revoca 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 | @@ -75,6 +74,6 @@ If this toggle is disabled, then only the refresh token is revoked, while the gr For the complete error code reference for this endpoint refer to [Errors > POST /oauth/revoke](#post-oauth-revoke). -### More Information +### Learn More - [Refresh Tokens](/tokens/concepts/refresh-tokens) 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..2ac941b02d --- /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 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. | + +## 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 must match. | + +### 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..1705fff13c --- /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 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. | + +## 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 must match. | + +### 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/client-credential.md b/articles/api/authentication/api-authz/client-credential.md new file mode 100644 index 0000000000..f00509605c --- /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 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. | + +### 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/implicit.md b/articles/api/authentication/api-authz/implicit.md new file mode 100644 index 0000000000..783ca1af07 --- /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 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. | + +### 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. + +### 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..9a7c65947b --- /dev/null +++ b/articles/api/authentication/api-authz/refresh-token.md @@ -0,0 +1,167 @@ +# 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 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). + +### 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) \ No newline at end of file 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..f00509605c --- /dev/null +++ b/articles/api/authentication/api-authz/resource-owner.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 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. | + +### 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/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..edaf11c423 100644 --- a/articles/api/authentication/errors/_passwordless-start.md +++ b/articles/api/authentication/errors/_passwordless-start.md @@ -1,56 +1,15 @@ # 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: )"}`| \ 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..807dceb58c 100644 --- a/articles/api/authentication/errors/_passwordless-verify.md +++ b/articles/api/authentication/errors/_passwordless-verify.md @@ -1,72 +1,16 @@ # 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| +|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| \ No newline at end of file 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) + +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**. + +## Other endpoints +To use Authentication API Debuggar with: +- Passwordless: 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**. +- SAML SSO: At the *Other Flows* tab, click **SAML**. +- WS-Federation: At the *Other Flows* tab, click **WS-Federation**. +- Logout: At the *Other Flows* tab, click **Logout**, or **Logout (Federated)** to log the user out of the identity provider as well. +- Legacy Login: At the *OAuth2 / OIDC* tab, set the fields **ID Token**, **Refresh Token** and **Target Client ID**. Click **Delegation**. +- Legacy Delegation: At the *OAuth2 / OIDC* tab, set **Username** and **Password**. Click **Resource Owner Endpoint**. +- Legacy Resource Owner: At the *OAuth2 / OIDC* tab, set the **Username** and **Password**, and click **Resource Owner Endpoint**. + +## Authentications Flows +Use the Authentication API Debuggar with: +- Authorization Code Flow: 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**. +- Authorization Code Flow + PKCE: 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**. +- Client Credential Flow: At the *OAuth2 / OIDC* tab, click **OAuth2 Client Credentials**. diff --git a/config/glossary.json b/config/glossary.json index 3dd8a3fc21..eb364974c2 100644 --- a/config/glossary.json +++ b/config/glossary.json @@ -169,6 +169,11 @@ "definition": "The date that access to a feature or behavior is removed from the platform. End Of Life Dates can vary between different plan types.", "short": "The date that access to a feature or behavior is removed from the platform. End Of Life Dates can vary between different plan types." }, + "fapi": { + "title": "OpenID FAPI", + "definition": "A suite of security and privacy specifications developed by the OpenID Foundation to allow applications to interact with and use data from financial accounts.", + "short": "A suite of security and privacy specifications developed by the OpenID Foundation." + }, "fine-grained-auth": { "title": "Fine Grained Authorization (FGA) ", "definition": "Auth0’s SaaS product gives individual users access to specific objects or resources within your application.",