From 7f126fdbade91900bedce4da131fc79f80672e54 Mon Sep 17 00:00:00 2001 From: Lucy Zhou Date: Thu, 19 Dec 2024 11:01:52 -0800 Subject: [PATCH 01/11] Added backchannel login --- articles/api/authentication/_login.md | 155 ++++++++++++++++++++++++++ 1 file changed, 155 insertions(+) diff --git a/articles/api/authentication/_login.md b/articles/api/authentication/_login.md index aede82e860..e22927d23d 100644 --- a/articles/api/authentication/_login.md +++ b/articles/api/authentication/_login.md @@ -1,4 +1,159 @@ +# Backchannel Login +<%= include('../../_includes/_http-method', { + "http_badge": "badge-primary", + "http_method": "POST", + "path": "/bc-authorize", + "link": "#social" +}) %> + +:::note +This feature is currently in Early Access. To request access, contact your Technical Account Manager. +::: + +The backchannel login endpoint enables applications to send an authentication request to a user’s phone, or the Authentication Device, provided they have an app installed and are enrolled for [push notifications using the Guardian SDK](/secure/multi-factor-authentication/auth0-guardian#enroll-in-push-notifications). It can be useful to authenticate users who are not in front of the application that requires authentication, such as users phoning a call center, or where the Consumption Device, or a device that helps the user consume a service, does not have a screen, such as a shared bicycle or scooter. + +## POST /bc-authorize + +```http +curl --location 'https://[TENANT_DOMAIN]/bc-authorize' \ +--header 'Content-Type: application/x-www-form-urlencoded' \ +--data-urlencode 'client_id=[CLIENT ID]' \ +--data-urlencode 'client_secret=[CLIENT SECRET]' \ +--data-urlencode 'binding_message=[YOUR BINDING MESSAGE]' \ +--data-urlencode 'login_hint={ "format": "iss_sub", "iss": +"https://[TENANT].auth0.com/", "sub": "auth0|[USER ID]" }' \ +--data-urlencode 'scope=openid' +``` + +### Request Parameters + +| Parameter | Description | +|:-----------------|:------------| +| `client_id`
Required | Client ID of your application. | +| `client_id`
Required | Human-readable string displayed on both the device calling `/bc-authorize` and the user’s authentication device (e.g. phone) to ensure the user is approves the correct request. For example: `ABC-123-XYZ`. | +| `login_hint`
Required | String containing information about the user to contact for authentication. It uses the [IETF9493 standard for Subject Identifiers for Security Event Tokens](https://datatracker.ietf.org/doc/html/rfc9493). Auth0 only supports the [Issuer and Identifier format](https://datatracker.ietf.org/doc/html/rfc9493#name-issuer-and-subject-identifi). For an example login hint, see the [Remarks](#remarks). | +| `scope`
Required | Space-separated list of OIDC and custom API scopes. For example: `openid read:timesheets edit:timesheets`. Include `offline_access` to get a refresh token. At a minimum, you must include the scope `openid`. | +| `audience`
Optional | Unique identifier of the audience for an issued token. If you require an access token for an API, pass the unique identifier of the target API you want to access. | +| `request_expiry`
Optional | To configure a custom expiry time in seconds for this request, pass a number between 1 and 300. If not provided, it defaults to 300. | + +### Response Body + +If the request is successful, you should receive a response like the following: + +```http +{ + "auth_req_id": "eyJh...", + "expires_in": 300, + "interval": 5 +} +``` + +The `auth_req_id` value should be kept as it is used later in the flow to identify the authentication request. + +The `expires_in` value tells you how many seconds you have until the authentication request expires. + +The `interval` value tells you how many seconds you must wait between poll requests. + +The request should be approved or rejected on the user’s Authentication Device using the Guardian SDK. + +### Remarks + + - The following code sample is an example login hint: + + ```http + { + "format": "iss_sub", + "iss": "https://[TENANT_DOMAIN]/", + "sub": "auth0|[USER ID]" + } + ``` + + White space is not significant. Replace the `[TENANT_DOMAIN]` with your tenant domain or custom domain. Replace the `[USER ID]` with a valid `user_id` for the authorizing user returned from the [User Search APIs](https://auth0.com/docs/manage-users/user-search). + + - Include an optional parameter for application authentication in the request: + - Client Secret with HTTP Basic auth, in which case no parameters are required. The `client_id` and `client_secret` are passed in a header. + - Client Secret Post, in which case the `client_id` and `client_secret` are required. + - Private Key JWT, where the `client_id`, `client_assertion` and `client_assertion` type are required. + - mTLS, where the `client_id` parameter is required and the `client-certificate` and `client-certificate-ca-verified` headers are required. + +## POST /oauth/token + +```http +curl --location 'https://[TENANT_DOMAIN]/oauth/token' \ +--header 'Content-Type: application/x-www-form-urlencoded' \ +--data-urlencode 'client_id=[CLIENT ID]' \ +--data-urlencode 'client_secret=[CLIENT SECRET]' \ +--data-urlencode 'auth_req_id=[FROM THE BC-AUTHORIZE RESPONSE]' \ +--data-urlencode 'grant_type=urn:openid:params:grant-type:ciba' +``` + +To check on the status of a backchannel login flow, poll the `/oauth/token` endpoint at regular intervals by passing the following: + +- `auth_req_id` returned from the call to `/bc-authorize` +- `urn:openid:params:grant-type:ciba` grant type + +### Request Parameters + +| Parameter | Description | +|:-----------------|:------------| +| `client_id`
Required | Client ID of your application | +| `auth_req_id`
Required | Used to reference the authentication request. Returned from the call to `/bc-authorize` | +| `grant_type`
Required | Must be set to `urn:openid:params:grant-type:ciba` | + +### Response Body + +If the authorizing user has not yet approved or rejected the request, you should receive a response like the following: + +```http +{ + "error": "authorization_pending", + "error_description": "The end-user authorization is pending" +} +``` + +If the authorizing user rejects the request, you should receive a response like the following: + +```http +{ + "error": "access_denied", + "error_description": "The end-user denied the authorization request or it +has been expired" +} +``` + +If you are polling too quickly (faster than the interval value returned from `/bc-authorize`), you should receive a response like the following: + +```http +{ + "error": "slow_down", + "error_description": "You are polling faster than allowed. Try again in 10 seconds." +} +``` + +In addition, Auth0 will add the the [Retry-After](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After) header to the response indicating how many seconds to wait before attempting to poll again. If you consistently poll too frequently, the number of seconds you must wait increases. + +If the authorizing user has approved the push notification, the call returns the ID token and access token (and potentially a refresh token): + +```http +{ + "access_token": "eyJh...", + "id_token": "eyJh...", + "expires_in": 86400, + "scope": "openid" +} +``` + +Once you have exchanged an `auth_req_id` for an ID or access token, it is no longer usable. + +### Remarks + +- Include an optional parameter for application authentication in the request: + - Client Secret with HTTP Basic auth, in which case no parameters are required. The `client_id` and `client_secret` are passed in a header. + - Client Secret Post, in which case the `client_id` and `client_secret` are required. + - Private Key JWT, where the `client_id`, `client_assertion` and `client_assertion` type are required. + - mTLS, where the `client_id` parameter is required and the `client-certificate` and `client-certificate-ca-verified` headers are required. + # Login <%= include('../../_includes/_http-method', { From f8bed68c2430f76833282c32bc3db1edc06a1527 Mon Sep 17 00:00:00 2001 From: Lucy Zhou Date: Fri, 20 Dec 2024 09:47:17 -0800 Subject: [PATCH 02/11] Updated backchannel login --- articles/api/authentication/_login.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/articles/api/authentication/_login.md b/articles/api/authentication/_login.md index e22927d23d..d245373b1c 100644 --- a/articles/api/authentication/_login.md +++ b/articles/api/authentication/_login.md @@ -11,7 +11,13 @@ This feature is currently in Early Access. To request access, contact your Technical Account Manager. ::: -The backchannel login endpoint enables applications to send an authentication request to a user’s phone, or the Authentication Device, provided they have an app installed and are enrolled for [push notifications using the Guardian SDK](/secure/multi-factor-authentication/auth0-guardian#enroll-in-push-notifications). It can be useful to authenticate users who are not in front of the application that requires authentication, such as users phoning a call center, or where the Consumption Device, or a device that helps the user consume a service, does not have a screen, such as a shared bicycle or scooter. +The backchannel login endpoint enables applications to send an authentication request to a user’s phone, or the authentication device, provided they have an app installed and are enrolled for [push notifications using the Guardian SDK](/secure/multi-factor-authentication/auth0-guardian#enroll-in-push-notifications). Use the backchannel login endpoint to authenticate users in the following use cases: + +- Users are not in front of the application that requires authentication, such as when they're telephoning a call center +- The consumption device, or the device that helps the user consume a service, is insecure for sensitive operations e.g. web browser for financial transactions +- The consumption device has limited interactive capability e.g. e-bicycles or e-scooters + +It can be useful to authenticate users who are not in front of the application that requires authentication, such as users phoning a call center, or where the Consumption Device, or a device that helps the user consume a service, does not have a screen, such as a shared bicycle or scooter. ## POST /bc-authorize @@ -35,7 +41,7 @@ curl --location 'https://[TENANT_DOMAIN]/bc-authorize' \ | `login_hint`
Required | String containing information about the user to contact for authentication. It uses the [IETF9493 standard for Subject Identifiers for Security Event Tokens](https://datatracker.ietf.org/doc/html/rfc9493). Auth0 only supports the [Issuer and Identifier format](https://datatracker.ietf.org/doc/html/rfc9493#name-issuer-and-subject-identifi). For an example login hint, see the [Remarks](#remarks). | | `scope`
Required | Space-separated list of OIDC and custom API scopes. For example: `openid read:timesheets edit:timesheets`. Include `offline_access` to get a refresh token. At a minimum, you must include the scope `openid`. | | `audience`
Optional | Unique identifier of the audience for an issued token. If you require an access token for an API, pass the unique identifier of the target API you want to access. | -| `request_expiry`
Optional | To configure a custom expiry time in seconds for this request, pass a number between 1 and 300. If not provided, it defaults to 300. | +| `request_expiry`
Optional | To configure a custom expiry time in seconds for this request, pass a number between 1 and 300. If not provided, it defaults to 300 seconds. | ### Response Body @@ -55,7 +61,7 @@ The `expires_in` value tells you how many seconds you have until the authenticat The `interval` value tells you how many seconds you must wait between poll requests. -The request should be approved or rejected on the user’s Authentication Device using the Guardian SDK. +The request should be approved or rejected on the user’s authentication device using the Guardian SDK. ### Remarks From 49dfdc4e20490b606a98806460860835991d4af1 Mon Sep 17 00:00:00 2001 From: Lucy Zhou Date: Fri, 20 Dec 2024 09:49:42 -0800 Subject: [PATCH 03/11] Cleaned up PR --- articles/api/authentication/_login.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/articles/api/authentication/_login.md b/articles/api/authentication/_login.md index d245373b1c..deedda8e98 100644 --- a/articles/api/authentication/_login.md +++ b/articles/api/authentication/_login.md @@ -11,13 +11,13 @@ This feature is currently in Early Access. To request access, contact your Technical Account Manager. ::: -The backchannel login endpoint enables applications to send an authentication request to a user’s phone, or the authentication device, provided they have an app installed and are enrolled for [push notifications using the Guardian SDK](/secure/multi-factor-authentication/auth0-guardian#enroll-in-push-notifications). Use the backchannel login endpoint to authenticate users in the following use cases: +The backchannel login endpoint enables applications to send an authentication request to a user’s phone, or the authentication device, provided they have an app installed and are enrolled for [push notifications using the Guardian SDK](/secure/multi-factor-authentication/auth0-guardian#enroll-in-push-notifications). -- Users are not in front of the application that requires authentication, such as when they're telephoning a call center -- The consumption device, or the device that helps the user consume a service, is insecure for sensitive operations e.g. web browser for financial transactions -- The consumption device has limited interactive capability e.g. e-bicycles or e-scooters +Use the backchannel login endpoint to authenticate users for the following use cases: -It can be useful to authenticate users who are not in front of the application that requires authentication, such as users phoning a call center, or where the Consumption Device, or a device that helps the user consume a service, does not have a screen, such as a shared bicycle or scooter. +- Users are not in front of the application that requires authentication, such as when they're telephoning a call center. +- The consumption device, or the device that helps the user consume a service, is insecure for sensitive operations e.g. web browser for financial transactions. +- The consumption device has limited interactive capability e.g. e-bicycles or e-scooters. ## POST /bc-authorize From 21f750327eb22d700b9c01a3413e1743895cc137 Mon Sep 17 00:00:00 2001 From: Lucy Zhou Date: Mon, 6 Jan 2025 11:22:38 -0500 Subject: [PATCH 04/11] updated link and other minor updates --- articles/api/authentication/_login.md | 28 ++++++++++++++------------- 1 file changed, 15 insertions(+), 13 deletions(-) diff --git a/articles/api/authentication/_login.md b/articles/api/authentication/_login.md index deedda8e98..a6a5e80c32 100644 --- a/articles/api/authentication/_login.md +++ b/articles/api/authentication/_login.md @@ -4,7 +4,7 @@ "http_badge": "badge-primary", "http_method": "POST", "path": "/bc-authorize", - "link": "#social" + "link": "#backchannel-login" }) %> :::note @@ -65,7 +65,7 @@ The request should be approved or rejected on the user’s authentication device ### Remarks - - The following code sample is an example login hint: +- The following code sample is an example login hint: ```http { @@ -75,13 +75,14 @@ The request should be approved or rejected on the user’s authentication device } ``` - White space is not significant. Replace the `[TENANT_DOMAIN]` with your tenant domain or custom domain. Replace the `[USER ID]` with a valid `user_id` for the authorizing user returned from the [User Search APIs](https://auth0.com/docs/manage-users/user-search). +White space is not significant. Replace the `[TENANT_DOMAIN]` with your tenant domain or custom domain. Replace the `[USER ID]` with a valid `user_id` for the authorizing user returned from the [User Search APIs](https://auth0.com/docs/manage-users/user-search). + +Include an optional parameter for application authentication in the request: - - Include an optional parameter for application authentication in the request: - - Client Secret with HTTP Basic auth, in which case no parameters are required. The `client_id` and `client_secret` are passed in a header. - - Client Secret Post, in which case the `client_id` and `client_secret` are required. - - Private Key JWT, where the `client_id`, `client_assertion` and `client_assertion` type are required. - - mTLS, where the `client_id` parameter is required and the `client-certificate` and `client-certificate-ca-verified` headers are required. +- Client Secret with HTTP Basic auth, in which case no parameters are required. The `client_id` and `client_secret` are passed in a header. +- Client Secret Post, in which case the `client_id` and `client_secret` are required. +- Private Key JWT, where the `client_id`, `client_assertion` and `client_assertion` type are required. +- mTLS, where the `client_id` parameter is required and the `client-certificate` and `client-certificate-ca-verified` headers are required. ## POST /oauth/token @@ -154,11 +155,12 @@ Once you have exchanged an `auth_req_id` for an ID or access token, it is no lon ### Remarks -- Include an optional parameter for application authentication in the request: - - Client Secret with HTTP Basic auth, in which case no parameters are required. The `client_id` and `client_secret` are passed in a header. - - Client Secret Post, in which case the `client_id` and `client_secret` are required. - - Private Key JWT, where the `client_id`, `client_assertion` and `client_assertion` type are required. - - mTLS, where the `client_id` parameter is required and the `client-certificate` and `client-certificate-ca-verified` headers are required. +Include an optional parameter for application authentication in the request: + +- Client Secret with HTTP Basic auth, in which case no parameters are required. The `client_id` and `client_secret` are passed in a header. +- Client Secret Post, in which case the `client_id` and `client_secret` are required. +- Private Key JWT, where the `client_id`, `client_assertion` and `client_assertion` type are required. +- mTLS, where the `client_id` parameter is required and the `client-certificate` and `client-certificate-ca-verified` headers are required. # Login From 5db4ad2119325bdaf3c4957cb7ed6a874a262434 Mon Sep 17 00:00:00 2001 From: Lucy Zhou Date: Mon, 6 Jan 2025 14:46:59 -0500 Subject: [PATCH 05/11] Removed bullet point --- articles/api/authentication/_login.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/articles/api/authentication/_login.md b/articles/api/authentication/_login.md index a6a5e80c32..7ed6dc920c 100644 --- a/articles/api/authentication/_login.md +++ b/articles/api/authentication/_login.md @@ -65,7 +65,7 @@ The request should be approved or rejected on the user’s authentication device ### Remarks -- The following code sample is an example login hint: +The following code sample is an example login hint: ```http { From 5c148c434a23ec3f02d53f33f76dcfa41ef9ef87 Mon Sep 17 00:00:00 2001 From: Lucy Zhou Date: Tue, 7 Jan 2025 08:44:02 -0500 Subject: [PATCH 06/11] Addressed docs team review --- articles/api/authentication/_login.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/articles/api/authentication/_login.md b/articles/api/authentication/_login.md index 7ed6dc920c..7fd0aaae86 100644 --- a/articles/api/authentication/_login.md +++ b/articles/api/authentication/_login.md @@ -1,5 +1,5 @@ -# Backchannel Login +# Back-Channel Login <%= include('../../_includes/_http-method', { "http_badge": "badge-primary", "http_method": "POST", @@ -11,9 +11,9 @@ This feature is currently in Early Access. To request access, contact your Technical Account Manager. ::: -The backchannel login endpoint enables applications to send an authentication request to a user’s phone, or the authentication device, provided they have an app installed and are enrolled for [push notifications using the Guardian SDK](/secure/multi-factor-authentication/auth0-guardian#enroll-in-push-notifications). +The Back-Channel Login endpoint enables applications to send an authentication request to a user’s phone, or the authentication device, provided they have an app installed and are enrolled for [push notifications using the Guardian SDK](/secure/multi-factor-authentication/auth0-guardian#enroll-in-push-notifications). -Use the backchannel login endpoint to authenticate users for the following use cases: +Use the Back-Channel Login endpoint to authenticate users for the following use cases: - Users are not in front of the application that requires authentication, such as when they're telephoning a call center. - The consumption device, or the device that helps the user consume a service, is insecure for sensitive operations e.g. web browser for financial transactions. @@ -37,11 +37,11 @@ curl --location 'https://[TENANT_DOMAIN]/bc-authorize' \ | Parameter | Description | |:-----------------|:------------| | `client_id`
Required | Client ID of your application. | -| `client_id`
Required | Human-readable string displayed on both the device calling `/bc-authorize` and the user’s authentication device (e.g. phone) to ensure the user is approves the correct request. For example: `ABC-123-XYZ`. | -| `login_hint`
Required | String containing information about the user to contact for authentication. It uses the [IETF9493 standard for Subject Identifiers for Security Event Tokens](https://datatracker.ietf.org/doc/html/rfc9493). Auth0 only supports the [Issuer and Identifier format](https://datatracker.ietf.org/doc/html/rfc9493#name-issuer-and-subject-identifi). For an example login hint, see the [Remarks](#remarks). | +| `binding_message`
Required | Human-readable string displayed on both the device calling `/bc-authorize` and the user’s authentication device (e.g. phone) to ensure the user is approves the correct request. For example: `ABC-123-XYZ`. | +| `login_hint`
Required | String containing information about the user to contact for authentication. It uses the [IETF9493 standard for Subject Identifiers for Security Event Tokens](https://datatracker.ietf.org/doc/html/rfc9493). Auth0 only supports the [Issuer and Identifier format](https://datatracker.ietf.org/doc/html/rfc9493#name-issuer-and-subject-identifi). For an example login hint, review the [Remarks](#remarks). | | `scope`
Required | Space-separated list of OIDC and custom API scopes. For example: `openid read:timesheets edit:timesheets`. Include `offline_access` to get a refresh token. At a minimum, you must include the scope `openid`. | | `audience`
Optional | Unique identifier of the audience for an issued token. If you require an access token for an API, pass the unique identifier of the target API you want to access. | -| `request_expiry`
Optional | To configure a custom expiry time in seconds for this request, pass a number between 1 and 300. If not provided, it defaults to 300 seconds. | +| `request_expiry`
Optional | To configure a custom expiry time in seconds for this request, pass a number between 1 and 300. If not provided, expiry defaults to 300 seconds. | ### Response Body @@ -95,7 +95,7 @@ curl --location 'https://[TENANT_DOMAIN]/oauth/token' \ --data-urlencode 'grant_type=urn:openid:params:grant-type:ciba' ``` -To check on the status of a backchannel login flow, poll the `/oauth/token` endpoint at regular intervals by passing the following: +To check on the status of a Back-Channel Login flow, poll the `/oauth/token` endpoint at regular intervals by passing the following: - `auth_req_id` returned from the call to `/bc-authorize` - `urn:openid:params:grant-type:ciba` grant type From 1fe385989039204b5b852e237f07fbc47584d67e Mon Sep 17 00:00:00 2001 From: Lucy Zhou Date: Tue, 7 Jan 2025 08:45:29 -0500 Subject: [PATCH 07/11] Updated link --- articles/api/authentication/_login.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/articles/api/authentication/_login.md b/articles/api/authentication/_login.md index 7fd0aaae86..fa9faaaaa4 100644 --- a/articles/api/authentication/_login.md +++ b/articles/api/authentication/_login.md @@ -4,7 +4,7 @@ "http_badge": "badge-primary", "http_method": "POST", "path": "/bc-authorize", - "link": "#backchannel-login" + "link": "#back-channel-login" }) %> :::note From 6d4e5d0e30d7067dd67f769976212b23427a7a06 Mon Sep 17 00:00:00 2001 From: Lucy Zhou Date: Tue, 7 Jan 2025 14:55:36 -0500 Subject: [PATCH 08/11] Created back-channel-login sidebar --- .../api/authentication/_back-channel-login.md | 169 ++++++++++++++++++ articles/api/authentication/_login.md | 163 ----------------- articles/api/authentication/index.md | 4 + 3 files changed, 173 insertions(+), 163 deletions(-) create mode 100644 articles/api/authentication/_back-channel-login.md diff --git a/articles/api/authentication/_back-channel-login.md b/articles/api/authentication/_back-channel-login.md new file mode 100644 index 0000000000..825c308675 --- /dev/null +++ b/articles/api/authentication/_back-channel-login.md @@ -0,0 +1,169 @@ + +# Back-Channel Login + +:::note +This feature is currently in Early Access. To request access, contact your Technical Account Manager. +::: + +The Back-Channel Login endpoint enables applications to send an authentication request to a user’s phone, or the authentication device, provided they have an app installed and are enrolled for [push notifications using the Guardian SDK](/secure/multi-factor-authentication/auth0-guardian#enroll-in-push-notifications). + +Use the Back-Channel Login endpoint to authenticate users for the following use cases: + +- Users are not in front of the application that requires authentication, such as when they're telephoning a call center. +- The consumption device, or the device that helps the user consume a service, is insecure for sensitive operations e.g. web browser for financial transactions. +- The consumption device has limited interactive capability e.g. e-bicycles or e-scooters. + +## Authorize +<%= include('../../_includes/_http-method', { + "http_badge": "badge-primary", + "http_method": "POST", + "path": "/bc-authorize", + "link": "#authorize" +}) %> + +```http +curl --location 'https://[TENANT_DOMAIN]/bc-authorize' \ +--header 'Content-Type: application/x-www-form-urlencoded' \ +--data-urlencode 'client_id=[CLIENT ID]' \ +--data-urlencode 'client_secret=[CLIENT SECRET]' \ +--data-urlencode 'binding_message=[YOUR BINDING MESSAGE]' \ +--data-urlencode 'login_hint={ "format": "iss_sub", "iss": +"https://[TENANT].auth0.com/", "sub": "auth0|[USER ID]" }' \ +--data-urlencode 'scope=openid' +``` + +### Request Parameters + +| Parameter | Description | +|:-----------------|:------------| +| `client_id`
Required | Client ID of your application. | +| `binding_message`
Required | Human-readable string displayed on both the device calling `/bc-authorize` and the user’s authentication device (e.g. phone) to ensure the user is approves the correct request. For example: `ABC-123-XYZ`. | +| `login_hint`
Required | String containing information about the user to contact for authentication. It uses the [IETF9493 standard for Subject Identifiers for Security Event Tokens](https://datatracker.ietf.org/doc/html/rfc9493). Auth0 only supports the [Issuer and Identifier format](https://datatracker.ietf.org/doc/html/rfc9493#name-issuer-and-subject-identifi). For an example login hint, review the [Remarks](#remarks). | +| `scope`
Required | Space-separated list of OIDC and custom API scopes. For example: `openid read:timesheets edit:timesheets`. Include `offline_access` to get a refresh token. At a minimum, you must include the scope `openid`. | +| `audience`
Optional | Unique identifier of the audience for an issued token. If you require an access token for an API, pass the unique identifier of the target API you want to access. | +| `request_expiry`
Optional | To configure a custom expiry time in seconds for this request, pass a number between 1 and 300. If not provided, expiry defaults to 300 seconds. | + +### Response Body + +If the request is successful, you should receive a response like the following: + +```http +{ + "auth_req_id": "eyJh...", + "expires_in": 300, + "interval": 5 +} +``` + +The `auth_req_id` value should be kept as it is used later in the flow to identify the authentication request. + +The `expires_in` value tells you how many seconds you have until the authentication request expires. + +The `interval` value tells you how many seconds you must wait between poll requests. + +The request should be approved or rejected on the user’s authentication device using the Guardian SDK. + +### Remarks + +The following code sample is an example login hint: + + ```http + { + "format": "iss_sub", + "iss": "https://[TENANT_DOMAIN]/", + "sub": "auth0|[USER ID]" + } + ``` + +White space is not significant. Replace the `[TENANT_DOMAIN]` with your tenant domain or custom domain. Replace the `[USER ID]` with a valid `user_id` for the authorizing user returned from the [User Search APIs](https://auth0.com/docs/manage-users/user-search). + +Include an optional parameter for application authentication in the request: + +- Client Secret with HTTP Basic auth, in which case no parameters are required. The `client_id` and `client_secret` are passed in a header. +- Client Secret Post, in which case the `client_id` and `client_secret` are required. +- Private Key JWT, where the `client_id`, `client_assertion` and `client_assertion` type are required. +- mTLS, where the `client_id` parameter is required and the `client-certificate` and `client-certificate-ca-verified` headers are required. + +## Get Token +<%= include('../../_includes/_http-method', { + "http_badge": "badge-primary", + "http_method": "POST", + "path": "/oauth/token", + "link": "#get-token" +}) %> + +```http +curl --location 'https://[TENANT_DOMAIN]/oauth/token' \ +--header 'Content-Type: application/x-www-form-urlencoded' \ +--data-urlencode 'client_id=[CLIENT ID]' \ +--data-urlencode 'client_secret=[CLIENT SECRET]' \ +--data-urlencode 'auth_req_id=[FROM THE BC-AUTHORIZE RESPONSE]' \ +--data-urlencode 'grant_type=urn:openid:params:grant-type:ciba' +``` + +To check on the status of a Back-Channel Login flow, poll the `/oauth/token` endpoint at regular intervals by passing the following: + +- `auth_req_id` returned from the call to `/bc-authorize` +- `urn:openid:params:grant-type:ciba` grant type + +### Request Parameters + +| Parameter | Description | +|:-----------------|:------------| +| `client_id`
Required | Client ID of your application | +| `auth_req_id`
Required | Used to reference the authentication request. Returned from the call to `/bc-authorize` | +| `grant_type`
Required | Must be set to `urn:openid:params:grant-type:ciba` | + +### Response Body + +If the authorizing user has not yet approved or rejected the request, you should receive a response like the following: + +```http +{ + "error": "authorization_pending", + "error_description": "The end-user authorization is pending" +} +``` + +If the authorizing user rejects the request, you should receive a response like the following: + +```http +{ + "error": "access_denied", + "error_description": "The end-user denied the authorization request or it +has been expired" +} +``` + +If you are polling too quickly (faster than the interval value returned from `/bc-authorize`), you should receive a response like the following: + +```http +{ + "error": "slow_down", + "error_description": "You are polling faster than allowed. Try again in 10 seconds." +} +``` + +In addition, Auth0 will add the the [Retry-After](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After) header to the response indicating how many seconds to wait before attempting to poll again. If you consistently poll too frequently, the number of seconds you must wait increases. + +If the authorizing user has approved the push notification, the call returns the ID token and access token (and potentially a refresh token): + +```http +{ + "access_token": "eyJh...", + "id_token": "eyJh...", + "expires_in": 86400, + "scope": "openid" +} +``` + +Once you have exchanged an `auth_req_id` for an ID or access token, it is no longer usable. + +### Remarks + +Include an optional parameter for application authentication in the request: + +- Client Secret with HTTP Basic auth, in which case no parameters are required. The `client_id` and `client_secret` are passed in a header. +- Client Secret Post, in which case the `client_id` and `client_secret` are required. +- Private Key JWT, where the `client_id`, `client_assertion` and `client_assertion` type are required. +- mTLS, where the `client_id` parameter is required and the `client-certificate` and `client-certificate-ca-verified` headers are required. \ No newline at end of file diff --git a/articles/api/authentication/_login.md b/articles/api/authentication/_login.md index fa9faaaaa4..aede82e860 100644 --- a/articles/api/authentication/_login.md +++ b/articles/api/authentication/_login.md @@ -1,167 +1,4 @@ -# Back-Channel Login -<%= include('../../_includes/_http-method', { - "http_badge": "badge-primary", - "http_method": "POST", - "path": "/bc-authorize", - "link": "#back-channel-login" -}) %> - -:::note -This feature is currently in Early Access. To request access, contact your Technical Account Manager. -::: - -The Back-Channel Login endpoint enables applications to send an authentication request to a user’s phone, or the authentication device, provided they have an app installed and are enrolled for [push notifications using the Guardian SDK](/secure/multi-factor-authentication/auth0-guardian#enroll-in-push-notifications). - -Use the Back-Channel Login endpoint to authenticate users for the following use cases: - -- Users are not in front of the application that requires authentication, such as when they're telephoning a call center. -- The consumption device, or the device that helps the user consume a service, is insecure for sensitive operations e.g. web browser for financial transactions. -- The consumption device has limited interactive capability e.g. e-bicycles or e-scooters. - -## POST /bc-authorize - -```http -curl --location 'https://[TENANT_DOMAIN]/bc-authorize' \ ---header 'Content-Type: application/x-www-form-urlencoded' \ ---data-urlencode 'client_id=[CLIENT ID]' \ ---data-urlencode 'client_secret=[CLIENT SECRET]' \ ---data-urlencode 'binding_message=[YOUR BINDING MESSAGE]' \ ---data-urlencode 'login_hint={ "format": "iss_sub", "iss": -"https://[TENANT].auth0.com/", "sub": "auth0|[USER ID]" }' \ ---data-urlencode 'scope=openid' -``` - -### Request Parameters - -| Parameter | Description | -|:-----------------|:------------| -| `client_id`
Required | Client ID of your application. | -| `binding_message`
Required | Human-readable string displayed on both the device calling `/bc-authorize` and the user’s authentication device (e.g. phone) to ensure the user is approves the correct request. For example: `ABC-123-XYZ`. | -| `login_hint`
Required | String containing information about the user to contact for authentication. It uses the [IETF9493 standard for Subject Identifiers for Security Event Tokens](https://datatracker.ietf.org/doc/html/rfc9493). Auth0 only supports the [Issuer and Identifier format](https://datatracker.ietf.org/doc/html/rfc9493#name-issuer-and-subject-identifi). For an example login hint, review the [Remarks](#remarks). | -| `scope`
Required | Space-separated list of OIDC and custom API scopes. For example: `openid read:timesheets edit:timesheets`. Include `offline_access` to get a refresh token. At a minimum, you must include the scope `openid`. | -| `audience`
Optional | Unique identifier of the audience for an issued token. If you require an access token for an API, pass the unique identifier of the target API you want to access. | -| `request_expiry`
Optional | To configure a custom expiry time in seconds for this request, pass a number between 1 and 300. If not provided, expiry defaults to 300 seconds. | - -### Response Body - -If the request is successful, you should receive a response like the following: - -```http -{ - "auth_req_id": "eyJh...", - "expires_in": 300, - "interval": 5 -} -``` - -The `auth_req_id` value should be kept as it is used later in the flow to identify the authentication request. - -The `expires_in` value tells you how many seconds you have until the authentication request expires. - -The `interval` value tells you how many seconds you must wait between poll requests. - -The request should be approved or rejected on the user’s authentication device using the Guardian SDK. - -### Remarks - -The following code sample is an example login hint: - - ```http - { - "format": "iss_sub", - "iss": "https://[TENANT_DOMAIN]/", - "sub": "auth0|[USER ID]" - } - ``` - -White space is not significant. Replace the `[TENANT_DOMAIN]` with your tenant domain or custom domain. Replace the `[USER ID]` with a valid `user_id` for the authorizing user returned from the [User Search APIs](https://auth0.com/docs/manage-users/user-search). - -Include an optional parameter for application authentication in the request: - -- Client Secret with HTTP Basic auth, in which case no parameters are required. The `client_id` and `client_secret` are passed in a header. -- Client Secret Post, in which case the `client_id` and `client_secret` are required. -- Private Key JWT, where the `client_id`, `client_assertion` and `client_assertion` type are required. -- mTLS, where the `client_id` parameter is required and the `client-certificate` and `client-certificate-ca-verified` headers are required. - -## POST /oauth/token - -```http -curl --location 'https://[TENANT_DOMAIN]/oauth/token' \ ---header 'Content-Type: application/x-www-form-urlencoded' \ ---data-urlencode 'client_id=[CLIENT ID]' \ ---data-urlencode 'client_secret=[CLIENT SECRET]' \ ---data-urlencode 'auth_req_id=[FROM THE BC-AUTHORIZE RESPONSE]' \ ---data-urlencode 'grant_type=urn:openid:params:grant-type:ciba' -``` - -To check on the status of a Back-Channel Login flow, poll the `/oauth/token` endpoint at regular intervals by passing the following: - -- `auth_req_id` returned from the call to `/bc-authorize` -- `urn:openid:params:grant-type:ciba` grant type - -### Request Parameters - -| Parameter | Description | -|:-----------------|:------------| -| `client_id`
Required | Client ID of your application | -| `auth_req_id`
Required | Used to reference the authentication request. Returned from the call to `/bc-authorize` | -| `grant_type`
Required | Must be set to `urn:openid:params:grant-type:ciba` | - -### Response Body - -If the authorizing user has not yet approved or rejected the request, you should receive a response like the following: - -```http -{ - "error": "authorization_pending", - "error_description": "The end-user authorization is pending" -} -``` - -If the authorizing user rejects the request, you should receive a response like the following: - -```http -{ - "error": "access_denied", - "error_description": "The end-user denied the authorization request or it -has been expired" -} -``` - -If you are polling too quickly (faster than the interval value returned from `/bc-authorize`), you should receive a response like the following: - -```http -{ - "error": "slow_down", - "error_description": "You are polling faster than allowed. Try again in 10 seconds." -} -``` - -In addition, Auth0 will add the the [Retry-After](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After) header to the response indicating how many seconds to wait before attempting to poll again. If you consistently poll too frequently, the number of seconds you must wait increases. - -If the authorizing user has approved the push notification, the call returns the ID token and access token (and potentially a refresh token): - -```http -{ - "access_token": "eyJh...", - "id_token": "eyJh...", - "expires_in": 86400, - "scope": "openid" -} -``` - -Once you have exchanged an `auth_req_id` for an ID or access token, it is no longer usable. - -### Remarks - -Include an optional parameter for application authentication in the request: - -- Client Secret with HTTP Basic auth, in which case no parameters are required. The `client_id` and `client_secret` are passed in a header. -- Client Secret Post, in which case the `client_id` and `client_secret` are required. -- Private Key JWT, where the `client_id`, `client_assertion` and `client_assertion` type are required. -- mTLS, where the `client_id` parameter is required and the `client-certificate` and `client-certificate-ca-verified` headers are required. - # Login <%= include('../../_includes/_http-method', { diff --git a/articles/api/authentication/index.md b/articles/api/authentication/index.md index 3edd4a539a..4371261b10 100644 --- a/articles/api/authentication/index.md +++ b/articles/api/authentication/index.md @@ -10,6 +10,10 @@ contentType: <%= include('./_introduction') %> +
+ <%= include('./_back-channel-login') %> +
+
<%= include('./_login') %>
From 86f4dbe12568fa3c2cb54b18cdc34cb992e51c60 Mon Sep 17 00:00:00 2001 From: Lucy Zhou Date: Tue, 7 Jan 2025 15:18:21 -0500 Subject: [PATCH 09/11] Added back back-channel-login to login page --- articles/api/authentication/_login.md | 163 ++++++++++++++++++++++++++ 1 file changed, 163 insertions(+) diff --git a/articles/api/authentication/_login.md b/articles/api/authentication/_login.md index aede82e860..d77dc330e0 100644 --- a/articles/api/authentication/_login.md +++ b/articles/api/authentication/_login.md @@ -1,6 +1,169 @@ # Login +## Back-Channel Login +<%= include('../../_includes/_http-method', { + "http_badge": "badge-primary", + "http_method": "POST", + "path": "/bc-authorize", + "link": "#back-channel-login" +}) %> + +:::note +This feature is currently in Early Access. To request access, contact your Technical Account Manager. +::: + +The Back-Channel Login endpoint enables applications to send an authentication request to a user’s phone, or the authentication device, provided they have an app installed and are enrolled for [push notifications using the Guardian SDK](/secure/multi-factor-authentication/auth0-guardian#enroll-in-push-notifications). + +Use the Back-Channel Login endpoint to authenticate users for the following use cases: + +- Users are not in front of the application that requires authentication, such as when they're telephoning a call center. +- The consumption device, or the device that helps the user consume a service, is insecure for sensitive operations e.g. web browser for financial transactions. +- The consumption device has limited interactive capability e.g. e-bicycles or e-scooters. + +### POST /bc-authorize + +```http +curl --location 'https://[TENANT_DOMAIN]/bc-authorize' \ +--header 'Content-Type: application/x-www-form-urlencoded' \ +--data-urlencode 'client_id=[CLIENT ID]' \ +--data-urlencode 'client_secret=[CLIENT SECRET]' \ +--data-urlencode 'binding_message=[YOUR BINDING MESSAGE]' \ +--data-urlencode 'login_hint={ "format": "iss_sub", "iss": +"https://[TENANT].auth0.com/", "sub": "auth0|[USER ID]" }' \ +--data-urlencode 'scope=openid' +``` + +#### Request Parameters + +| Parameter | Description | +|:-----------------|:------------| +| `client_id`
Required | Client ID of your application. | +| `binding_message`
Required | Human-readable string displayed on both the device calling `/bc-authorize` and the user’s authentication device (e.g. phone) to ensure the user is approves the correct request. For example: `ABC-123-XYZ`. | +| `login_hint`
Required | String containing information about the user to contact for authentication. It uses the [IETF9493 standard for Subject Identifiers for Security Event Tokens](https://datatracker.ietf.org/doc/html/rfc9493). Auth0 only supports the [Issuer and Identifier format](https://datatracker.ietf.org/doc/html/rfc9493#name-issuer-and-subject-identifi). For an example login hint, review the [Remarks](#remarks). | +| `scope`
Required | Space-separated list of OIDC and custom API scopes. For example: `openid read:timesheets edit:timesheets`. Include `offline_access` to get a refresh token. At a minimum, you must include the scope `openid`. | +| `audience`
Optional | Unique identifier of the audience for an issued token. If you require an access token for an API, pass the unique identifier of the target API you want to access. | +| `request_expiry`
Optional | To configure a custom expiry time in seconds for this request, pass a number between 1 and 300. If not provided, expiry defaults to 300 seconds. | + +#### Response Body + +If the request is successful, you should receive a response like the following: + +```http +{ + "auth_req_id": "eyJh...", + "expires_in": 300, + "interval": 5 +} +``` + +The `auth_req_id` value should be kept as it is used later in the flow to identify the authentication request. + +The `expires_in` value tells you how many seconds you have until the authentication request expires. + +The `interval` value tells you how many seconds you must wait between poll requests. + +The request should be approved or rejected on the user’s authentication device using the Guardian SDK. + +#### Remarks + +The following code sample is an example login hint: + + ```http + { + "format": "iss_sub", + "iss": "https://[TENANT_DOMAIN]/", + "sub": "auth0|[USER ID]" + } + ``` + +White space is not significant. Replace the `[TENANT_DOMAIN]` with your tenant domain or custom domain. Replace the `[USER ID]` with a valid `user_id` for the authorizing user returned from the [User Search APIs](https://auth0.com/docs/manage-users/user-search). + +Include an optional parameter for application authentication in the request: + +- Client Secret with HTTP Basic auth, in which case no parameters are required. The `client_id` and `client_secret` are passed in a header. +- Client Secret Post, in which case the `client_id` and `client_secret` are required. +- Private Key JWT, where the `client_id`, `client_assertion` and `client_assertion` type are required. +- mTLS, where the `client_id` parameter is required and the `client-certificate` and `client-certificate-ca-verified` headers are required. + +### POST /oauth/token + +```http +curl --location 'https://[TENANT_DOMAIN]/oauth/token' \ +--header 'Content-Type: application/x-www-form-urlencoded' \ +--data-urlencode 'client_id=[CLIENT ID]' \ +--data-urlencode 'client_secret=[CLIENT SECRET]' \ +--data-urlencode 'auth_req_id=[FROM THE BC-AUTHORIZE RESPONSE]' \ +--data-urlencode 'grant_type=urn:openid:params:grant-type:ciba' +``` + +To check on the status of a Back-Channel Login flow, poll the `/oauth/token` endpoint at regular intervals by passing the following: + +- `auth_req_id` returned from the call to `/bc-authorize` +- `urn:openid:params:grant-type:ciba` grant type + +#### Request Parameters + +| Parameter | Description | +|:-----------------|:------------| +| `client_id`
Required | Client ID of your application | +| `auth_req_id`
Required | Used to reference the authentication request. Returned from the call to `/bc-authorize` | +| `grant_type`
Required | Must be set to `urn:openid:params:grant-type:ciba` | + +#### Response Body + +If the authorizing user has not yet approved or rejected the request, you should receive a response like the following: + +```http +{ + "error": "authorization_pending", + "error_description": "The end-user authorization is pending" +} +``` + +If the authorizing user rejects the request, you should receive a response like the following: + +```http +{ + "error": "access_denied", + "error_description": "The end-user denied the authorization request or it +has been expired" +} +``` + +If you are polling too quickly (faster than the interval value returned from `/bc-authorize`), you should receive a response like the following: + +```http +{ + "error": "slow_down", + "error_description": "You are polling faster than allowed. Try again in 10 seconds." +} +``` + +In addition, Auth0 will add the the [Retry-After](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After) header to the response indicating how many seconds to wait before attempting to poll again. If you consistently poll too frequently, the number of seconds you must wait increases. + +If the authorizing user has approved the push notification, the call returns the ID token and access token (and potentially a refresh token): + +```http +{ + "access_token": "eyJh...", + "id_token": "eyJh...", + "expires_in": 86400, + "scope": "openid" +} +``` + +Once you have exchanged an `auth_req_id` for an ID or access token, it is no longer usable. + +#### Remarks + +Include an optional parameter for application authentication in the request: + +- Client Secret with HTTP Basic auth, in which case no parameters are required. The `client_id` and `client_secret` are passed in a header. +- Client Secret Post, in which case the `client_id` and `client_secret` are required. +- Private Key JWT, where the `client_id`, `client_assertion` and `client_assertion` type are required. +- mTLS, where the `client_id` parameter is required and the `client-certificate` and `client-certificate-ca-verified` headers are required. + <%= include('../../_includes/_http-method', { "http_badge": "badge-primary", "http_method": "GET", From d26aeb489cd2552ccaaf4ae4570d0dc03df4bee1 Mon Sep 17 00:00:00 2001 From: Lucy Zhou Date: Tue, 7 Jan 2025 15:18:32 -0500 Subject: [PATCH 10/11] Revert "Created back-channel-login sidebar" This reverts commit 6d4e5d0e30d7067dd67f769976212b23427a7a06. Reverting commit adding back-channel login to sidebar --- .../api/authentication/_back-channel-login.md | 169 ------------------ articles/api/authentication/_login.md | 163 +++++++++++++++++ articles/api/authentication/index.md | 4 - 3 files changed, 163 insertions(+), 173 deletions(-) delete mode 100644 articles/api/authentication/_back-channel-login.md diff --git a/articles/api/authentication/_back-channel-login.md b/articles/api/authentication/_back-channel-login.md deleted file mode 100644 index 825c308675..0000000000 --- a/articles/api/authentication/_back-channel-login.md +++ /dev/null @@ -1,169 +0,0 @@ - -# Back-Channel Login - -:::note -This feature is currently in Early Access. To request access, contact your Technical Account Manager. -::: - -The Back-Channel Login endpoint enables applications to send an authentication request to a user’s phone, or the authentication device, provided they have an app installed and are enrolled for [push notifications using the Guardian SDK](/secure/multi-factor-authentication/auth0-guardian#enroll-in-push-notifications). - -Use the Back-Channel Login endpoint to authenticate users for the following use cases: - -- Users are not in front of the application that requires authentication, such as when they're telephoning a call center. -- The consumption device, or the device that helps the user consume a service, is insecure for sensitive operations e.g. web browser for financial transactions. -- The consumption device has limited interactive capability e.g. e-bicycles or e-scooters. - -## Authorize -<%= include('../../_includes/_http-method', { - "http_badge": "badge-primary", - "http_method": "POST", - "path": "/bc-authorize", - "link": "#authorize" -}) %> - -```http -curl --location 'https://[TENANT_DOMAIN]/bc-authorize' \ ---header 'Content-Type: application/x-www-form-urlencoded' \ ---data-urlencode 'client_id=[CLIENT ID]' \ ---data-urlencode 'client_secret=[CLIENT SECRET]' \ ---data-urlencode 'binding_message=[YOUR BINDING MESSAGE]' \ ---data-urlencode 'login_hint={ "format": "iss_sub", "iss": -"https://[TENANT].auth0.com/", "sub": "auth0|[USER ID]" }' \ ---data-urlencode 'scope=openid' -``` - -### Request Parameters - -| Parameter | Description | -|:-----------------|:------------| -| `client_id`
Required | Client ID of your application. | -| `binding_message`
Required | Human-readable string displayed on both the device calling `/bc-authorize` and the user’s authentication device (e.g. phone) to ensure the user is approves the correct request. For example: `ABC-123-XYZ`. | -| `login_hint`
Required | String containing information about the user to contact for authentication. It uses the [IETF9493 standard for Subject Identifiers for Security Event Tokens](https://datatracker.ietf.org/doc/html/rfc9493). Auth0 only supports the [Issuer and Identifier format](https://datatracker.ietf.org/doc/html/rfc9493#name-issuer-and-subject-identifi). For an example login hint, review the [Remarks](#remarks). | -| `scope`
Required | Space-separated list of OIDC and custom API scopes. For example: `openid read:timesheets edit:timesheets`. Include `offline_access` to get a refresh token. At a minimum, you must include the scope `openid`. | -| `audience`
Optional | Unique identifier of the audience for an issued token. If you require an access token for an API, pass the unique identifier of the target API you want to access. | -| `request_expiry`
Optional | To configure a custom expiry time in seconds for this request, pass a number between 1 and 300. If not provided, expiry defaults to 300 seconds. | - -### Response Body - -If the request is successful, you should receive a response like the following: - -```http -{ - "auth_req_id": "eyJh...", - "expires_in": 300, - "interval": 5 -} -``` - -The `auth_req_id` value should be kept as it is used later in the flow to identify the authentication request. - -The `expires_in` value tells you how many seconds you have until the authentication request expires. - -The `interval` value tells you how many seconds you must wait between poll requests. - -The request should be approved or rejected on the user’s authentication device using the Guardian SDK. - -### Remarks - -The following code sample is an example login hint: - - ```http - { - "format": "iss_sub", - "iss": "https://[TENANT_DOMAIN]/", - "sub": "auth0|[USER ID]" - } - ``` - -White space is not significant. Replace the `[TENANT_DOMAIN]` with your tenant domain or custom domain. Replace the `[USER ID]` with a valid `user_id` for the authorizing user returned from the [User Search APIs](https://auth0.com/docs/manage-users/user-search). - -Include an optional parameter for application authentication in the request: - -- Client Secret with HTTP Basic auth, in which case no parameters are required. The `client_id` and `client_secret` are passed in a header. -- Client Secret Post, in which case the `client_id` and `client_secret` are required. -- Private Key JWT, where the `client_id`, `client_assertion` and `client_assertion` type are required. -- mTLS, where the `client_id` parameter is required and the `client-certificate` and `client-certificate-ca-verified` headers are required. - -## Get Token -<%= include('../../_includes/_http-method', { - "http_badge": "badge-primary", - "http_method": "POST", - "path": "/oauth/token", - "link": "#get-token" -}) %> - -```http -curl --location 'https://[TENANT_DOMAIN]/oauth/token' \ ---header 'Content-Type: application/x-www-form-urlencoded' \ ---data-urlencode 'client_id=[CLIENT ID]' \ ---data-urlencode 'client_secret=[CLIENT SECRET]' \ ---data-urlencode 'auth_req_id=[FROM THE BC-AUTHORIZE RESPONSE]' \ ---data-urlencode 'grant_type=urn:openid:params:grant-type:ciba' -``` - -To check on the status of a Back-Channel Login flow, poll the `/oauth/token` endpoint at regular intervals by passing the following: - -- `auth_req_id` returned from the call to `/bc-authorize` -- `urn:openid:params:grant-type:ciba` grant type - -### Request Parameters - -| Parameter | Description | -|:-----------------|:------------| -| `client_id`
Required | Client ID of your application | -| `auth_req_id`
Required | Used to reference the authentication request. Returned from the call to `/bc-authorize` | -| `grant_type`
Required | Must be set to `urn:openid:params:grant-type:ciba` | - -### Response Body - -If the authorizing user has not yet approved or rejected the request, you should receive a response like the following: - -```http -{ - "error": "authorization_pending", - "error_description": "The end-user authorization is pending" -} -``` - -If the authorizing user rejects the request, you should receive a response like the following: - -```http -{ - "error": "access_denied", - "error_description": "The end-user denied the authorization request or it -has been expired" -} -``` - -If you are polling too quickly (faster than the interval value returned from `/bc-authorize`), you should receive a response like the following: - -```http -{ - "error": "slow_down", - "error_description": "You are polling faster than allowed. Try again in 10 seconds." -} -``` - -In addition, Auth0 will add the the [Retry-After](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After) header to the response indicating how many seconds to wait before attempting to poll again. If you consistently poll too frequently, the number of seconds you must wait increases. - -If the authorizing user has approved the push notification, the call returns the ID token and access token (and potentially a refresh token): - -```http -{ - "access_token": "eyJh...", - "id_token": "eyJh...", - "expires_in": 86400, - "scope": "openid" -} -``` - -Once you have exchanged an `auth_req_id` for an ID or access token, it is no longer usable. - -### Remarks - -Include an optional parameter for application authentication in the request: - -- Client Secret with HTTP Basic auth, in which case no parameters are required. The `client_id` and `client_secret` are passed in a header. -- Client Secret Post, in which case the `client_id` and `client_secret` are required. -- Private Key JWT, where the `client_id`, `client_assertion` and `client_assertion` type are required. -- mTLS, where the `client_id` parameter is required and the `client-certificate` and `client-certificate-ca-verified` headers are required. \ No newline at end of file diff --git a/articles/api/authentication/_login.md b/articles/api/authentication/_login.md index d77dc330e0..1b9b0fa735 100644 --- a/articles/api/authentication/_login.md +++ b/articles/api/authentication/_login.md @@ -1,4 +1,167 @@ +# Back-Channel Login +<%= include('../../_includes/_http-method', { + "http_badge": "badge-primary", + "http_method": "POST", + "path": "/bc-authorize", + "link": "#back-channel-login" +}) %> + +:::note +This feature is currently in Early Access. To request access, contact your Technical Account Manager. +::: + +The Back-Channel Login endpoint enables applications to send an authentication request to a user’s phone, or the authentication device, provided they have an app installed and are enrolled for [push notifications using the Guardian SDK](/secure/multi-factor-authentication/auth0-guardian#enroll-in-push-notifications). + +Use the Back-Channel Login endpoint to authenticate users for the following use cases: + +- Users are not in front of the application that requires authentication, such as when they're telephoning a call center. +- The consumption device, or the device that helps the user consume a service, is insecure for sensitive operations e.g. web browser for financial transactions. +- The consumption device has limited interactive capability e.g. e-bicycles or e-scooters. + +## POST /bc-authorize + +```http +curl --location 'https://[TENANT_DOMAIN]/bc-authorize' \ +--header 'Content-Type: application/x-www-form-urlencoded' \ +--data-urlencode 'client_id=[CLIENT ID]' \ +--data-urlencode 'client_secret=[CLIENT SECRET]' \ +--data-urlencode 'binding_message=[YOUR BINDING MESSAGE]' \ +--data-urlencode 'login_hint={ "format": "iss_sub", "iss": +"https://[TENANT].auth0.com/", "sub": "auth0|[USER ID]" }' \ +--data-urlencode 'scope=openid' +``` + +### Request Parameters + +| Parameter | Description | +|:-----------------|:------------| +| `client_id`
Required | Client ID of your application. | +| `binding_message`
Required | Human-readable string displayed on both the device calling `/bc-authorize` and the user’s authentication device (e.g. phone) to ensure the user is approves the correct request. For example: `ABC-123-XYZ`. | +| `login_hint`
Required | String containing information about the user to contact for authentication. It uses the [IETF9493 standard for Subject Identifiers for Security Event Tokens](https://datatracker.ietf.org/doc/html/rfc9493). Auth0 only supports the [Issuer and Identifier format](https://datatracker.ietf.org/doc/html/rfc9493#name-issuer-and-subject-identifi). For an example login hint, review the [Remarks](#remarks). | +| `scope`
Required | Space-separated list of OIDC and custom API scopes. For example: `openid read:timesheets edit:timesheets`. Include `offline_access` to get a refresh token. At a minimum, you must include the scope `openid`. | +| `audience`
Optional | Unique identifier of the audience for an issued token. If you require an access token for an API, pass the unique identifier of the target API you want to access. | +| `request_expiry`
Optional | To configure a custom expiry time in seconds for this request, pass a number between 1 and 300. If not provided, expiry defaults to 300 seconds. | + +### Response Body + +If the request is successful, you should receive a response like the following: + +```http +{ + "auth_req_id": "eyJh...", + "expires_in": 300, + "interval": 5 +} +``` + +The `auth_req_id` value should be kept as it is used later in the flow to identify the authentication request. + +The `expires_in` value tells you how many seconds you have until the authentication request expires. + +The `interval` value tells you how many seconds you must wait between poll requests. + +The request should be approved or rejected on the user’s authentication device using the Guardian SDK. + +### Remarks + +The following code sample is an example login hint: + + ```http + { + "format": "iss_sub", + "iss": "https://[TENANT_DOMAIN]/", + "sub": "auth0|[USER ID]" + } + ``` + +White space is not significant. Replace the `[TENANT_DOMAIN]` with your tenant domain or custom domain. Replace the `[USER ID]` with a valid `user_id` for the authorizing user returned from the [User Search APIs](https://auth0.com/docs/manage-users/user-search). + +Include an optional parameter for application authentication in the request: + +- Client Secret with HTTP Basic auth, in which case no parameters are required. The `client_id` and `client_secret` are passed in a header. +- Client Secret Post, in which case the `client_id` and `client_secret` are required. +- Private Key JWT, where the `client_id`, `client_assertion` and `client_assertion` type are required. +- mTLS, where the `client_id` parameter is required and the `client-certificate` and `client-certificate-ca-verified` headers are required. + +## POST /oauth/token + +```http +curl --location 'https://[TENANT_DOMAIN]/oauth/token' \ +--header 'Content-Type: application/x-www-form-urlencoded' \ +--data-urlencode 'client_id=[CLIENT ID]' \ +--data-urlencode 'client_secret=[CLIENT SECRET]' \ +--data-urlencode 'auth_req_id=[FROM THE BC-AUTHORIZE RESPONSE]' \ +--data-urlencode 'grant_type=urn:openid:params:grant-type:ciba' +``` + +To check on the status of a Back-Channel Login flow, poll the `/oauth/token` endpoint at regular intervals by passing the following: + +- `auth_req_id` returned from the call to `/bc-authorize` +- `urn:openid:params:grant-type:ciba` grant type + +### Request Parameters + +| Parameter | Description | +|:-----------------|:------------| +| `client_id`
Required | Client ID of your application | +| `auth_req_id`
Required | Used to reference the authentication request. Returned from the call to `/bc-authorize` | +| `grant_type`
Required | Must be set to `urn:openid:params:grant-type:ciba` | + +### Response Body + +If the authorizing user has not yet approved or rejected the request, you should receive a response like the following: + +```http +{ + "error": "authorization_pending", + "error_description": "The end-user authorization is pending" +} +``` + +If the authorizing user rejects the request, you should receive a response like the following: + +```http +{ + "error": "access_denied", + "error_description": "The end-user denied the authorization request or it +has been expired" +} +``` + +If you are polling too quickly (faster than the interval value returned from `/bc-authorize`), you should receive a response like the following: + +```http +{ + "error": "slow_down", + "error_description": "You are polling faster than allowed. Try again in 10 seconds." +} +``` + +In addition, Auth0 will add the the [Retry-After](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After) header to the response indicating how many seconds to wait before attempting to poll again. If you consistently poll too frequently, the number of seconds you must wait increases. + +If the authorizing user has approved the push notification, the call returns the ID token and access token (and potentially a refresh token): + +```http +{ + "access_token": "eyJh...", + "id_token": "eyJh...", + "expires_in": 86400, + "scope": "openid" +} +``` + +Once you have exchanged an `auth_req_id` for an ID or access token, it is no longer usable. + +### Remarks + +Include an optional parameter for application authentication in the request: + +- Client Secret with HTTP Basic auth, in which case no parameters are required. The `client_id` and `client_secret` are passed in a header. +- Client Secret Post, in which case the `client_id` and `client_secret` are required. +- Private Key JWT, where the `client_id`, `client_assertion` and `client_assertion` type are required. +- mTLS, where the `client_id` parameter is required and the `client-certificate` and `client-certificate-ca-verified` headers are required. + # Login ## Back-Channel Login diff --git a/articles/api/authentication/index.md b/articles/api/authentication/index.md index 4371261b10..3edd4a539a 100644 --- a/articles/api/authentication/index.md +++ b/articles/api/authentication/index.md @@ -10,10 +10,6 @@ contentType: <%= include('./_introduction') %> -
- <%= include('./_back-channel-login') %> -
-
<%= include('./_login') %>
From 8c3609eb1cd991ec78cee93d160ed9c2285225a8 Mon Sep 17 00:00:00 2001 From: Lucy Zhou Date: Tue, 7 Jan 2025 15:26:26 -0500 Subject: [PATCH 11/11] Added back-channel login to end --- articles/api/authentication/_login.md | 495 +++++++++----------------- 1 file changed, 168 insertions(+), 327 deletions(-) diff --git a/articles/api/authentication/_login.md b/articles/api/authentication/_login.md index 1b9b0fa735..291091ada0 100644 --- a/articles/api/authentication/_login.md +++ b/articles/api/authentication/_login.md @@ -1,332 +1,6 @@ -# Back-Channel Login -<%= include('../../_includes/_http-method', { - "http_badge": "badge-primary", - "http_method": "POST", - "path": "/bc-authorize", - "link": "#back-channel-login" -}) %> - -:::note -This feature is currently in Early Access. To request access, contact your Technical Account Manager. -::: - -The Back-Channel Login endpoint enables applications to send an authentication request to a user’s phone, or the authentication device, provided they have an app installed and are enrolled for [push notifications using the Guardian SDK](/secure/multi-factor-authentication/auth0-guardian#enroll-in-push-notifications). - -Use the Back-Channel Login endpoint to authenticate users for the following use cases: - -- Users are not in front of the application that requires authentication, such as when they're telephoning a call center. -- The consumption device, or the device that helps the user consume a service, is insecure for sensitive operations e.g. web browser for financial transactions. -- The consumption device has limited interactive capability e.g. e-bicycles or e-scooters. - -## POST /bc-authorize - -```http -curl --location 'https://[TENANT_DOMAIN]/bc-authorize' \ ---header 'Content-Type: application/x-www-form-urlencoded' \ ---data-urlencode 'client_id=[CLIENT ID]' \ ---data-urlencode 'client_secret=[CLIENT SECRET]' \ ---data-urlencode 'binding_message=[YOUR BINDING MESSAGE]' \ ---data-urlencode 'login_hint={ "format": "iss_sub", "iss": -"https://[TENANT].auth0.com/", "sub": "auth0|[USER ID]" }' \ ---data-urlencode 'scope=openid' -``` - -### Request Parameters - -| Parameter | Description | -|:-----------------|:------------| -| `client_id`
Required | Client ID of your application. | -| `binding_message`
Required | Human-readable string displayed on both the device calling `/bc-authorize` and the user’s authentication device (e.g. phone) to ensure the user is approves the correct request. For example: `ABC-123-XYZ`. | -| `login_hint`
Required | String containing information about the user to contact for authentication. It uses the [IETF9493 standard for Subject Identifiers for Security Event Tokens](https://datatracker.ietf.org/doc/html/rfc9493). Auth0 only supports the [Issuer and Identifier format](https://datatracker.ietf.org/doc/html/rfc9493#name-issuer-and-subject-identifi). For an example login hint, review the [Remarks](#remarks). | -| `scope`
Required | Space-separated list of OIDC and custom API scopes. For example: `openid read:timesheets edit:timesheets`. Include `offline_access` to get a refresh token. At a minimum, you must include the scope `openid`. | -| `audience`
Optional | Unique identifier of the audience for an issued token. If you require an access token for an API, pass the unique identifier of the target API you want to access. | -| `request_expiry`
Optional | To configure a custom expiry time in seconds for this request, pass a number between 1 and 300. If not provided, expiry defaults to 300 seconds. | - -### Response Body - -If the request is successful, you should receive a response like the following: - -```http -{ - "auth_req_id": "eyJh...", - "expires_in": 300, - "interval": 5 -} -``` - -The `auth_req_id` value should be kept as it is used later in the flow to identify the authentication request. - -The `expires_in` value tells you how many seconds you have until the authentication request expires. - -The `interval` value tells you how many seconds you must wait between poll requests. - -The request should be approved or rejected on the user’s authentication device using the Guardian SDK. - -### Remarks - -The following code sample is an example login hint: - - ```http - { - "format": "iss_sub", - "iss": "https://[TENANT_DOMAIN]/", - "sub": "auth0|[USER ID]" - } - ``` - -White space is not significant. Replace the `[TENANT_DOMAIN]` with your tenant domain or custom domain. Replace the `[USER ID]` with a valid `user_id` for the authorizing user returned from the [User Search APIs](https://auth0.com/docs/manage-users/user-search). - -Include an optional parameter for application authentication in the request: - -- Client Secret with HTTP Basic auth, in which case no parameters are required. The `client_id` and `client_secret` are passed in a header. -- Client Secret Post, in which case the `client_id` and `client_secret` are required. -- Private Key JWT, where the `client_id`, `client_assertion` and `client_assertion` type are required. -- mTLS, where the `client_id` parameter is required and the `client-certificate` and `client-certificate-ca-verified` headers are required. - -## POST /oauth/token - -```http -curl --location 'https://[TENANT_DOMAIN]/oauth/token' \ ---header 'Content-Type: application/x-www-form-urlencoded' \ ---data-urlencode 'client_id=[CLIENT ID]' \ ---data-urlencode 'client_secret=[CLIENT SECRET]' \ ---data-urlencode 'auth_req_id=[FROM THE BC-AUTHORIZE RESPONSE]' \ ---data-urlencode 'grant_type=urn:openid:params:grant-type:ciba' -``` - -To check on the status of a Back-Channel Login flow, poll the `/oauth/token` endpoint at regular intervals by passing the following: - -- `auth_req_id` returned from the call to `/bc-authorize` -- `urn:openid:params:grant-type:ciba` grant type - -### Request Parameters - -| Parameter | Description | -|:-----------------|:------------| -| `client_id`
Required | Client ID of your application | -| `auth_req_id`
Required | Used to reference the authentication request. Returned from the call to `/bc-authorize` | -| `grant_type`
Required | Must be set to `urn:openid:params:grant-type:ciba` | - -### Response Body - -If the authorizing user has not yet approved or rejected the request, you should receive a response like the following: - -```http -{ - "error": "authorization_pending", - "error_description": "The end-user authorization is pending" -} -``` - -If the authorizing user rejects the request, you should receive a response like the following: - -```http -{ - "error": "access_denied", - "error_description": "The end-user denied the authorization request or it -has been expired" -} -``` - -If you are polling too quickly (faster than the interval value returned from `/bc-authorize`), you should receive a response like the following: - -```http -{ - "error": "slow_down", - "error_description": "You are polling faster than allowed. Try again in 10 seconds." -} -``` - -In addition, Auth0 will add the the [Retry-After](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After) header to the response indicating how many seconds to wait before attempting to poll again. If you consistently poll too frequently, the number of seconds you must wait increases. - -If the authorizing user has approved the push notification, the call returns the ID token and access token (and potentially a refresh token): - -```http -{ - "access_token": "eyJh...", - "id_token": "eyJh...", - "expires_in": 86400, - "scope": "openid" -} -``` - -Once you have exchanged an `auth_req_id` for an ID or access token, it is no longer usable. - -### Remarks - -Include an optional parameter for application authentication in the request: - -- Client Secret with HTTP Basic auth, in which case no parameters are required. The `client_id` and `client_secret` are passed in a header. -- Client Secret Post, in which case the `client_id` and `client_secret` are required. -- Private Key JWT, where the `client_id`, `client_assertion` and `client_assertion` type are required. -- mTLS, where the `client_id` parameter is required and the `client-certificate` and `client-certificate-ca-verified` headers are required. - # Login -## Back-Channel Login -<%= include('../../_includes/_http-method', { - "http_badge": "badge-primary", - "http_method": "POST", - "path": "/bc-authorize", - "link": "#back-channel-login" -}) %> - -:::note -This feature is currently in Early Access. To request access, contact your Technical Account Manager. -::: - -The Back-Channel Login endpoint enables applications to send an authentication request to a user’s phone, or the authentication device, provided they have an app installed and are enrolled for [push notifications using the Guardian SDK](/secure/multi-factor-authentication/auth0-guardian#enroll-in-push-notifications). - -Use the Back-Channel Login endpoint to authenticate users for the following use cases: - -- Users are not in front of the application that requires authentication, such as when they're telephoning a call center. -- The consumption device, or the device that helps the user consume a service, is insecure for sensitive operations e.g. web browser for financial transactions. -- The consumption device has limited interactive capability e.g. e-bicycles or e-scooters. - -### POST /bc-authorize - -```http -curl --location 'https://[TENANT_DOMAIN]/bc-authorize' \ ---header 'Content-Type: application/x-www-form-urlencoded' \ ---data-urlencode 'client_id=[CLIENT ID]' \ ---data-urlencode 'client_secret=[CLIENT SECRET]' \ ---data-urlencode 'binding_message=[YOUR BINDING MESSAGE]' \ ---data-urlencode 'login_hint={ "format": "iss_sub", "iss": -"https://[TENANT].auth0.com/", "sub": "auth0|[USER ID]" }' \ ---data-urlencode 'scope=openid' -``` - -#### Request Parameters - -| Parameter | Description | -|:-----------------|:------------| -| `client_id`
Required | Client ID of your application. | -| `binding_message`
Required | Human-readable string displayed on both the device calling `/bc-authorize` and the user’s authentication device (e.g. phone) to ensure the user is approves the correct request. For example: `ABC-123-XYZ`. | -| `login_hint`
Required | String containing information about the user to contact for authentication. It uses the [IETF9493 standard for Subject Identifiers for Security Event Tokens](https://datatracker.ietf.org/doc/html/rfc9493). Auth0 only supports the [Issuer and Identifier format](https://datatracker.ietf.org/doc/html/rfc9493#name-issuer-and-subject-identifi). For an example login hint, review the [Remarks](#remarks). | -| `scope`
Required | Space-separated list of OIDC and custom API scopes. For example: `openid read:timesheets edit:timesheets`. Include `offline_access` to get a refresh token. At a minimum, you must include the scope `openid`. | -| `audience`
Optional | Unique identifier of the audience for an issued token. If you require an access token for an API, pass the unique identifier of the target API you want to access. | -| `request_expiry`
Optional | To configure a custom expiry time in seconds for this request, pass a number between 1 and 300. If not provided, expiry defaults to 300 seconds. | - -#### Response Body - -If the request is successful, you should receive a response like the following: - -```http -{ - "auth_req_id": "eyJh...", - "expires_in": 300, - "interval": 5 -} -``` - -The `auth_req_id` value should be kept as it is used later in the flow to identify the authentication request. - -The `expires_in` value tells you how many seconds you have until the authentication request expires. - -The `interval` value tells you how many seconds you must wait between poll requests. - -The request should be approved or rejected on the user’s authentication device using the Guardian SDK. - -#### Remarks - -The following code sample is an example login hint: - - ```http - { - "format": "iss_sub", - "iss": "https://[TENANT_DOMAIN]/", - "sub": "auth0|[USER ID]" - } - ``` - -White space is not significant. Replace the `[TENANT_DOMAIN]` with your tenant domain or custom domain. Replace the `[USER ID]` with a valid `user_id` for the authorizing user returned from the [User Search APIs](https://auth0.com/docs/manage-users/user-search). - -Include an optional parameter for application authentication in the request: - -- Client Secret with HTTP Basic auth, in which case no parameters are required. The `client_id` and `client_secret` are passed in a header. -- Client Secret Post, in which case the `client_id` and `client_secret` are required. -- Private Key JWT, where the `client_id`, `client_assertion` and `client_assertion` type are required. -- mTLS, where the `client_id` parameter is required and the `client-certificate` and `client-certificate-ca-verified` headers are required. - -### POST /oauth/token - -```http -curl --location 'https://[TENANT_DOMAIN]/oauth/token' \ ---header 'Content-Type: application/x-www-form-urlencoded' \ ---data-urlencode 'client_id=[CLIENT ID]' \ ---data-urlencode 'client_secret=[CLIENT SECRET]' \ ---data-urlencode 'auth_req_id=[FROM THE BC-AUTHORIZE RESPONSE]' \ ---data-urlencode 'grant_type=urn:openid:params:grant-type:ciba' -``` - -To check on the status of a Back-Channel Login flow, poll the `/oauth/token` endpoint at regular intervals by passing the following: - -- `auth_req_id` returned from the call to `/bc-authorize` -- `urn:openid:params:grant-type:ciba` grant type - -#### Request Parameters - -| Parameter | Description | -|:-----------------|:------------| -| `client_id`
Required | Client ID of your application | -| `auth_req_id`
Required | Used to reference the authentication request. Returned from the call to `/bc-authorize` | -| `grant_type`
Required | Must be set to `urn:openid:params:grant-type:ciba` | - -#### Response Body - -If the authorizing user has not yet approved or rejected the request, you should receive a response like the following: - -```http -{ - "error": "authorization_pending", - "error_description": "The end-user authorization is pending" -} -``` - -If the authorizing user rejects the request, you should receive a response like the following: - -```http -{ - "error": "access_denied", - "error_description": "The end-user denied the authorization request or it -has been expired" -} -``` - -If you are polling too quickly (faster than the interval value returned from `/bc-authorize`), you should receive a response like the following: - -```http -{ - "error": "slow_down", - "error_description": "You are polling faster than allowed. Try again in 10 seconds." -} -``` - -In addition, Auth0 will add the the [Retry-After](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After) header to the response indicating how many seconds to wait before attempting to poll again. If you consistently poll too frequently, the number of seconds you must wait increases. - -If the authorizing user has approved the push notification, the call returns the ID token and access token (and potentially a refresh token): - -```http -{ - "access_token": "eyJh...", - "id_token": "eyJh...", - "expires_in": 86400, - "scope": "openid" -} -``` - -Once you have exchanged an `auth_req_id` for an ID or access token, it is no longer usable. - -#### Remarks - -Include an optional parameter for application authentication in the request: - -- Client Secret with HTTP Basic auth, in which case no parameters are required. The `client_id` and `client_secret` are passed in a header. -- Client Secret Post, in which case the `client_id` and `client_secret` are required. -- Private Key JWT, where the `client_id`, `client_assertion` and `client_assertion` type are required. -- mTLS, where the `client_id` parameter is required and the `client-certificate` and `client-certificate-ca-verified` headers are required. - <%= include('../../_includes/_http-method', { "http_badge": "badge-primary", "http_method": "GET", @@ -529,4 +203,171 @@ Make a `GET` call to the `/authorize` endpoint for passive authentication. It re - [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-) \ No newline at end of file +- [Auth0.js /authorize Method Reference](/libraries/auth0js#webauth-authorize-) + +## Back-Channel Login + +:::note +This feature is currently in Early Access. To request access, contact your Technical Account Manager. +::: + +The Back-Channel Login endpoint enables applications to send an authentication request to a user’s phone, or the authentication device, provided they have an app installed and are enrolled for [push notifications using the Guardian SDK](/secure/multi-factor-authentication/auth0-guardian#enroll-in-push-notifications). + +Use the Back-Channel Login endpoint to authenticate users for the following use cases: + +- Users are not in front of the application that requires authentication, such as when they're telephoning a call center. +- The consumption device, or the device that helps the user consume a service, is insecure for sensitive operations e.g. web browser for financial transactions. +- The consumption device has limited interactive capability e.g. e-bicycles or e-scooters. + +<%= include('../../_includes/_http-method', { + "http_badge": "badge-primary", + "http_method": "POST", + "path": "/bc-authorize", + "link": "#back-channel-login" +}) %> + +```http +curl --location 'https://[TENANT_DOMAIN]/bc-authorize' \ +--header 'Content-Type: application/x-www-form-urlencoded' \ +--data-urlencode 'client_id=[CLIENT ID]' \ +--data-urlencode 'client_secret=[CLIENT SECRET]' \ +--data-urlencode 'binding_message=[YOUR BINDING MESSAGE]' \ +--data-urlencode 'login_hint={ "format": "iss_sub", "iss": +"https://[TENANT].auth0.com/", "sub": "auth0|[USER ID]" }' \ +--data-urlencode 'scope=openid' +``` + +### Request Parameters + +| Parameter | Description | +|:-----------------|:------------| +| `client_id`
Required | Client ID of your application. | +| `binding_message`
Required | Human-readable string displayed on both the device calling `/bc-authorize` and the user’s authentication device (e.g. phone) to ensure the user is approves the correct request. For example: `ABC-123-XYZ`. | +| `login_hint`
Required | String containing information about the user to contact for authentication. It uses the [IETF9493 standard for Subject Identifiers for Security Event Tokens](https://datatracker.ietf.org/doc/html/rfc9493). Auth0 only supports the [Issuer and Identifier format](https://datatracker.ietf.org/doc/html/rfc9493#name-issuer-and-subject-identifi). For an example login hint, review the [Remarks](#remarks). | +| `scope`
Required | Space-separated list of OIDC and custom API scopes. For example: `openid read:timesheets edit:timesheets`. Include `offline_access` to get a refresh token. At a minimum, you must include the scope `openid`. | +| `audience`
Optional | Unique identifier of the audience for an issued token. If you require an access token for an API, pass the unique identifier of the target API you want to access. | +| `request_expiry`
Optional | To configure a custom expiry time in seconds for this request, pass a number between 1 and 300. If not provided, expiry defaults to 300 seconds. | + +### Response Body + +If the request is successful, you should receive a response like the following: + +```http +{ + "auth_req_id": "eyJh...", + "expires_in": 300, + "interval": 5 +} +``` + +The `auth_req_id` value should be kept as it is used later in the flow to identify the authentication request. + +The `expires_in` value tells you how many seconds you have until the authentication request expires. + +The `interval` value tells you how many seconds you must wait between poll requests. + +The request should be approved or rejected on the user’s authentication device using the Guardian SDK. + +### Remarks + +The following code sample is an example login hint: + + ```http + { + "format": "iss_sub", + "iss": "https://[TENANT_DOMAIN]/", + "sub": "auth0|[USER ID]" + } + ``` + +White space is not significant. Replace the `[TENANT_DOMAIN]` with your tenant domain or custom domain. Replace the `[USER ID]` with a valid `user_id` for the authorizing user returned from the [User Search APIs](https://auth0.com/docs/manage-users/user-search). + +Include an optional parameter for application authentication in the request: + +- Client Secret with HTTP Basic auth, in which case no parameters are required. The `client_id` and `client_secret` are passed in a header. +- Client Secret Post, in which case the `client_id` and `client_secret` are required. +- Private Key JWT, where the `client_id`, `client_assertion` and `client_assertion` type are required. +- mTLS, where the `client_id` parameter is required and the `client-certificate` and `client-certificate-ca-verified` headers are required. + +<%= include('../../_includes/_http-method', { + "http_badge": "badge-primary", + "http_method": "POST", + "path": "/oauth/token", + "link": "#post-token" +}) %> + +```http +curl --location 'https://[TENANT_DOMAIN]/oauth/token' \ +--header 'Content-Type: application/x-www-form-urlencoded' \ +--data-urlencode 'client_id=[CLIENT ID]' \ +--data-urlencode 'client_secret=[CLIENT SECRET]' \ +--data-urlencode 'auth_req_id=[FROM THE BC-AUTHORIZE RESPONSE]' \ +--data-urlencode 'grant_type=urn:openid:params:grant-type:ciba' +``` + +To check on the status of a Back-Channel Login flow, poll the `/oauth/token` endpoint at regular intervals by passing the following: + +- `auth_req_id` returned from the call to `/bc-authorize` +- `urn:openid:params:grant-type:ciba` grant type + +### Request Parameters + +| Parameter | Description | +|:-----------------|:------------| +| `client_id`
Required | Client ID of your application | +| `auth_req_id`
Required | Used to reference the authentication request. Returned from the call to `/bc-authorize` | +| `grant_type`
Required | Must be set to `urn:openid:params:grant-type:ciba` | + +### Response Body + +If the authorizing user has not yet approved or rejected the request, you should receive a response like the following: + +```http +{ + "error": "authorization_pending", + "error_description": "The end-user authorization is pending" +} +``` + +If the authorizing user rejects the request, you should receive a response like the following: + +```http +{ + "error": "access_denied", + "error_description": "The end-user denied the authorization request or it +has been expired" +} +``` + +If you are polling too quickly (faster than the interval value returned from `/bc-authorize`), you should receive a response like the following: + +```http +{ + "error": "slow_down", + "error_description": "You are polling faster than allowed. Try again in 10 seconds." +} +``` + +In addition, Auth0 will add the the [Retry-After](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After) header to the response indicating how many seconds to wait before attempting to poll again. If you consistently poll too frequently, the number of seconds you must wait increases. + +If the authorizing user has approved the push notification, the call returns the ID token and access token (and potentially a refresh token): + +```http +{ + "access_token": "eyJh...", + "id_token": "eyJh...", + "expires_in": 86400, + "scope": "openid" +} +``` + +Once you have exchanged an `auth_req_id` for an ID or access token, it is no longer usable. + +### Remarks + +Include an optional parameter for application authentication in the request: + +- Client Secret with HTTP Basic auth, in which case no parameters are required. The `client_id` and `client_secret` are passed in a header. +- Client Secret Post, in which case the `client_id` and `client_secret` are required. +- Private Key JWT, where the `client_id`, `client_assertion` and `client_assertion` type are required. +- mTLS, where the `client_id` parameter is required and the `client-certificate` and `client-certificate-ca-verified` headers are required. \ No newline at end of file