Skip to content

Commit d26aeb4

Browse files
lrzhou25lrzhou25
committed
Revert "Created back-channel-login sidebar"
This reverts commit 6d4e5d0. Reverting commit adding back-channel login to sidebar
1 parent 86f4dbe commit d26aeb4

File tree

3 files changed

+163
-173
lines changed

3 files changed

+163
-173
lines changed

‎articles/api/authentication/_back-channel-login.md

-169
This file was deleted.

‎articles/api/authentication/_login.md

+163
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,167 @@
11
<!-- markdownlint-disable MD024 MD033 -->
2+
# Back-Channel Login
3+
<%= include('../../_includes/_http-method', {
4+
"http_badge": "badge-primary",
5+
"http_method": "POST",
6+
"path": "/bc-authorize",
7+
"link": "#back-channel-login"
8+
}) %>
9+
10+
:::note
11+
This feature is currently in Early Access. To request access, contact your Technical Account Manager.
12+
:::
13+
14+
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).
15+
16+
Use the Back-Channel Login endpoint to authenticate users for the following use cases:
17+
18+
- Users are not in front of the application that requires authentication, such as when they're telephoning a call center.
19+
- 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.
20+
- The consumption device has limited interactive capability e.g. e-bicycles or e-scooters.
21+
22+
## POST /bc-authorize
23+
24+
```http
25+
curl --location 'https://[TENANT_DOMAIN]/bc-authorize' \
26+
--header 'Content-Type: application/x-www-form-urlencoded' \
27+
--data-urlencode 'client_id=[CLIENT ID]' \
28+
--data-urlencode 'client_secret=[CLIENT SECRET]' \
29+
--data-urlencode 'binding_message=[YOUR BINDING MESSAGE]' \
30+
--data-urlencode 'login_hint={ "format": "iss_sub", "iss":
31+
"https://[TENANT].auth0.com/", "sub": "auth0|[USER ID]" }' \
32+
--data-urlencode 'scope=openid'
33+
```
34+
35+
### Request Parameters
36+
37+
| Parameter | Description |
38+
|:-----------------|:------------|
39+
| `client_id` <br/><span class="label label-danger">Required</span> | Client ID of your application. |
40+
| `binding_message` <br/><span class="label label-danger">Required</span> | 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`. |
41+
| `login_hint` <br/><span class="label label-danger">Required</span> | 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). |
42+
| `scope` <br/><span class="label label-danger">Required</span> | 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`. |
43+
| `audience` <br/><span class="label label-danger">Optional</span> | 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. |
44+
| `request_expiry` <br/><span class="label label-danger">Optional</span> | 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. |
45+
46+
### Response Body
47+
48+
If the request is successful, you should receive a response like the following:
49+
50+
```http
51+
{
52+
"auth_req_id": "eyJh...",
53+
"expires_in": 300,
54+
"interval": 5
55+
}
56+
```
57+
58+
The `auth_req_id` value should be kept as it is used later in the flow to identify the authentication request.
59+
60+
The `expires_in` value tells you how many seconds you have until the authentication request expires.
61+
62+
The `interval` value tells you how many seconds you must wait between poll requests.
63+
64+
The request should be approved or rejected on the user’s authentication device using the Guardian SDK.
65+
66+
### Remarks
67+
68+
The following code sample is an example login hint:
69+
70+
```http
71+
{
72+
"format": "iss_sub",
73+
"iss": "https://[TENANT_DOMAIN]/",
74+
"sub": "auth0|[USER ID]"
75+
}
76+
```
77+
78+
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).
79+
80+
Include an optional parameter for application authentication in the request:
81+
82+
- Client Secret with HTTP Basic auth, in which case no parameters are required. The `client_id` and `client_secret` are passed in a header.
83+
- Client Secret Post, in which case the `client_id` and `client_secret` are required.
84+
- Private Key JWT, where the `client_id`, `client_assertion` and `client_assertion` type are required.
85+
- mTLS, where the `client_id` parameter is required and the `client-certificate` and `client-certificate-ca-verified` headers are required.
86+
87+
## POST /oauth/token
88+
89+
```http
90+
curl --location 'https://[TENANT_DOMAIN]/oauth/token' \
91+
--header 'Content-Type: application/x-www-form-urlencoded' \
92+
--data-urlencode 'client_id=[CLIENT ID]' \
93+
--data-urlencode 'client_secret=[CLIENT SECRET]' \
94+
--data-urlencode 'auth_req_id=[FROM THE BC-AUTHORIZE RESPONSE]' \
95+
--data-urlencode 'grant_type=urn:openid:params:grant-type:ciba'
96+
```
97+
98+
To check on the status of a Back-Channel Login flow, poll the `/oauth/token` endpoint at regular intervals by passing the following:
99+
100+
- `auth_req_id` returned from the call to `/bc-authorize`
101+
- `urn:openid:params:grant-type:ciba` grant type
102+
103+
### Request Parameters
104+
105+
| Parameter | Description |
106+
|:-----------------|:------------|
107+
| `client_id` <br/><span class="label label-danger">Required</span> | Client ID of your application |
108+
| `auth_req_id` <br/><span class="label label-danger">Required</span> | Used to reference the authentication request. Returned from the call to `/bc-authorize` |
109+
| `grant_type` <br/><span class="label label-danger">Required</span> | Must be set to `urn:openid:params:grant-type:ciba` |
110+
111+
### Response Body
112+
113+
If the authorizing user has not yet approved or rejected the request, you should receive a response like the following:
114+
115+
```http
116+
{
117+
"error": "authorization_pending",
118+
"error_description": "The end-user authorization is pending"
119+
}
120+
```
121+
122+
If the authorizing user rejects the request, you should receive a response like the following:
123+
124+
```http
125+
{
126+
"error": "access_denied",
127+
"error_description": "The end-user denied the authorization request or it
128+
has been expired"
129+
}
130+
```
131+
132+
If you are polling too quickly (faster than the interval value returned from `/bc-authorize`), you should receive a response like the following:
133+
134+
```http
135+
{
136+
"error": "slow_down",
137+
"error_description": "You are polling faster than allowed. Try again in 10 seconds."
138+
}
139+
```
140+
141+
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.
142+
143+
If the authorizing user has approved the push notification, the call returns the ID token and access token (and potentially a refresh token):
144+
145+
```http
146+
{
147+
"access_token": "eyJh...",
148+
"id_token": "eyJh...",
149+
"expires_in": 86400,
150+
"scope": "openid"
151+
}
152+
```
153+
154+
Once you have exchanged an `auth_req_id` for an ID or access token, it is no longer usable.
155+
156+
### Remarks
157+
158+
Include an optional parameter for application authentication in the request:
159+
160+
- Client Secret with HTTP Basic auth, in which case no parameters are required. The `client_id` and `client_secret` are passed in a header.
161+
- Client Secret Post, in which case the `client_id` and `client_secret` are required.
162+
- Private Key JWT, where the `client_id`, `client_assertion` and `client_assertion` type are required.
163+
- mTLS, where the `client_id` parameter is required and the `client-certificate` and `client-certificate-ca-verified` headers are required.
164+
2165
# Login
3166

4167
## Back-Channel Login

‎articles/api/authentication/index.md

-4
Original file line numberDiff line numberDiff line change
@@ -10,10 +10,6 @@ contentType:
1010
<%= include('./_introduction') %>
1111
</div>
1212

13-
<div class="api-section" data-section="none">
14-
<%= include('./_back-channel-login') %>
15-
</div>
16-
1713
<div class="api-section" data-section="none">
1814
<%= include('./_login') %>
1915
</div>

0 commit comments

Comments
 (0)