Skip to content

Commit 4e093b8

Browse files
hwupathumhwupathum
authored
Merge pull request #5765 from hwupathum/app-native
Add device auth flow app-native documentation
2 parents e55ae63 + 7fc42dd commit 4e093b8

File tree

4 files changed

+187
-11
lines changed

4 files changed

+187
-11
lines changed

‎en/asgardeo/docs/references/app-native-authentication.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,4 +5,6 @@
55
{% include "../../../includes/references/app-native-authentication.md" %}
66
{% include "../../../includes/references/push-notification-app-native-reference.md" %}
77
{% set session_control_scenario_id = "7" %}
8-
{% include "../../../includes/references/concurrent-session-based-access-control-app-native-reference.md" %}
8+
{% include "../../../includes/references/concurrent-session-based-access-control-app-native-reference.md" %}
9+
{% set api_oauth2_path = "https://api.asgardeo.io/t/{organization_name}/oauth2" %}
10+
{% include "../../../includes/references/device-flow-app-native-reference.md" %}

‎en/identity-server/next/docs/references/app-native-authentication.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,4 +5,6 @@
55
{% include "../../../../includes/references/app-native-authentication.md" %}
66
{% include "../../../../includes/references/push-notification-app-native-reference.md" %}
77
{% set session_control_scenario_id = "7" %}
8-
{% include "../../../../includes/references/concurrent-session-based-access-control-app-native-reference.md" %}
8+
{% include "../../../../includes/references/concurrent-session-based-access-control-app-native-reference.md" %}
9+
{% set api_oauth2_path = "https://localhost:9443/oauth2" %}
10+
{% include "../../../../includes/references/device-flow-app-native-reference.md" %}

‎en/includes/guides/authentication/app-native-authentication/handle-advanced-login-scenarios.md‎

Lines changed: 27 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ To do so,
1919

2020
1. In the {{product_name}} Console, go to **Connections** and select your IdP.
2121

22-
2. In its **General** tab,
22+
2. In its **General** tab,
2323

2424
- under **issuer** configure a trusted token issuer.
2525
- under **Certificates**, configure either upload a certificate or configure a JWKS Endpoint.
@@ -29,13 +29,12 @@ To do so,
2929
!!! tip
3030
Refer to the [sample scenario]({{base_path}}/references/app-native-authentication/#scenario-4-user-selects-federated-authentication-native-mode) to see it in action.
3131

32-
3332
### Redirect mode
3433

3534
In the rediect mode, the application redirects the user to the IdP as it does in a [conventional federated login flow]({{base_path}}/guides/authentication/federated-login/). However, under the hood, app-native authentication handles federated authentication slightly differently.
3635

3736
!!! note "How is it different?"
38-
37+
3938
Although federated login flows in both [conventional login]({{base_path}}/guides/authentication/federated-login/) and app-native authentication redirect the user to the external IdP, there is a subtle difference between them.
4039

4140
- **In a conventional flow**,
@@ -94,7 +93,7 @@ The number of login options a login step has is indicated by the `stepType` para
9493

9594
If it is set to:
9695

97-
- `AUTHENTICATOR_PROMPT`, it is a login step with a single login option.
96+
- `AUTHENTICATOR_PROMPT`, it is a login step with a single login option.
9897

9998
The following is part of the response for a single-option login step.
10099

@@ -111,8 +110,8 @@ If it is set to:
111110
...
112111
}
113112
```
114-
115-
- `MULTI_OPTIONS_PROMPT`, it is a login step with multiple login options.
113+
114+
- `MULTI_OPTIONS_PROMPT`, it is a login step with multiple login options.
116115

117116
The following is part of the response for a multi-option login step.
118117

@@ -132,7 +131,7 @@ If it is set to:
132131

133132
In app-native authentication, multi-option steps behave slightly differently compared to a single-option step.
134133

135-
Some authenticators such as `Username & Password` which only require user input, sends its metadata directly in the response. For other authenticators which require a form of 'initiation', the response does not contain the metadata for the authenticator.
134+
Some authenticators such as `Username & Password` which only require user input, sends its metadata directly in the response. For other authenticators which require a form of 'initiation', the response does not contain the metadata for the authenticator.
136135

137136
!!! note "Some authenticatiors that require 'initiation'"
138137

@@ -145,8 +144,8 @@ If during login, the user selects such an authenticator, the application needs t
145144
!!! tip
146145
Refer to the [sample scenario]({{base_path}}/references/app-native-authentication/#scenario-3-user-selects-passkey-login-out-of-multiple-options) to see it in action.
147146

148-
149147
## Handle Single Sign-On
148+
150149
Single Sign-On (SSO) for app-native authentication can be handled in the following two ways.
151150

152151
### Cookie based SSO
@@ -188,4 +187,23 @@ Given below is a sample authorization request using the `isk` value as the `sess
188187
```
189188

190189
!!! note
191-
If both cookie based SSO and SessionId based SSO are used, cookie based SSO takes precedence.
190+
If both cookie-based SSO and SessionId-based SSO are used, cookie-based SSO takes precedence.
191+
192+
{% if product_name == 'Asgardeo' or is_version >= "7.2.0" %}
193+
194+
## Handle device authorization flow
195+
196+
Device authorization flow lets users log in on input-constrained devices. Examples include smart TVs, printers, and gaming consoles without browsers or keyboards.
197+
198+
To enable device authorization flow:
199+
200+
1. Register your application in the {{product_name}} Console.
201+
2. Enable **Device Code** under **Grant Types** in your application settings.
202+
3. Enable [app-native authentication]({{base_path}}/guides/authentication/app-native-authentication/add-app-native-authentication/#enable-app-native-authentication) for your application.
203+
204+
For more information, see [device authorization grant]({{base_path}}/references/grant-types/#device-authorization-grant).
205+
206+
!!! tip
207+
Refer to the [sample scenario]({{base_path}}/references/app-native-authentication/#scenario-8-device-authorization-flow) to see it in action.
208+
209+
{% endif %}

‎en/includes/references/device-flow-app-native-reference.md‎

Lines changed: 154 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,154 @@
1+
### Scenario 8: Device authorization flow
2+
3+
The application goes through the following steps to complete app-native authentication using the device authorization flow.
4+
5+
- **Step 1**: Get the required codes.
6+
7+
The app initiates a login request to the device authorization endpoint.
8+
9+
!!! note
10+
The response contains the `user_code` and `device_code` required for the client device.
11+
12+
=== "Request (`/device_authorize`)"
13+
14+
```bash
15+
curl --location '{{api_oauth2_path}}/device_authorize/'
16+
--header 'Accept: application/json'
17+
--header 'Content-Type: application/x-www-form-urlencoded'
18+
--data-urlencode 'client_id=XWRkRNkJDeTiR5MwHdXROGiJka'
19+
--data-urlencode 'scope=openid profile'
20+
```
21+
=== "Response (`/device_authorize`)"
22+
23+
```json
24+
{
25+
"user_code": "s2DqSNK",
26+
"device_code": "d3fe0db1-2334-48fa-b7d9-821ecfad10d5",
27+
"interval": 5,
28+
"verification_uri": "{{api_oauth2_path}}/authenticationendpoint/device.do",
29+
"verification_uri_complete": "{{api_oauth2_path}}/authenticationendpoint/device.do?user_code=s2DqSNK",
30+
"expires_in": 600
31+
}
32+
```
33+
34+
- **Step 2**: Authorize the client device.
35+
36+
The app on the client device calls the device endpoint with the `user_code` to initiate authentication.
37+
38+
!!! note
39+
Set `response_mode=direct` to initiate app-native authentication.
40+
41+
=== "Request (`/device`)"
42+
43+
```bash
44+
curl --location '{{api_oauth2_path}}/device/'
45+
--header 'Accept: application/json'
46+
--header 'Content-Type: application/x-www-form-urlencoded'
47+
--data-urlencode 'user_code=s2DqSNK'
48+
--data-urlencode 'response_mode=direct'
49+
```
50+
=== "Response (`/device`)"
51+
52+
```json
53+
{
54+
"flowId": "95339089-72d1-4825-80fe-ab7864f4943b",
55+
"flowStatus": "INCOMPLETE",
56+
"flowType": "AUTHENTICATION",
57+
"nextStep": {
58+
"stepType": "AUTHENTICATOR_PROMPT",
59+
"authenticators": [
60+
{
61+
"authenticatorId": "QmFzaWNBdXRoZW50aWNhdG9yOkxPQ0FM",
62+
"authenticator": "Username & Password",
63+
"idp": "LOCAL",
64+
"metadata": {
65+
"i18nKey": "authenticator.basic",
66+
"promptType": "USER_PROMPT",
67+
"params": [
68+
{
69+
"param": "username",
70+
"type": "STRING",
71+
"order": 0,
72+
"i18nKey": "username.param",
73+
"displayName": "Username",
74+
"confidential": false
75+
},
76+
{
77+
"param": "password",
78+
"type": "STRING",
79+
"order": 1,
80+
"i18nKey": "password.param",
81+
"displayName": "Password",
82+
"confidential": true
83+
}
84+
]
85+
},
86+
"requiredParams": [
87+
"username",
88+
"password"
89+
]
90+
}
91+
]
92+
},
93+
"links": [
94+
{
95+
"name": "authentication",
96+
"href": "{{authn_path}}",
97+
"method": "POST"
98+
}
99+
]
100+
}
101+
```
102+
103+
- **Step 3**: Carry the `flowId` received in the above response and request the `/authn` endpoint for username & password authentication.
104+
105+
=== "Request (`/authn`)"
106+
107+
```bash
108+
curl --location '{{authn_path}}'
109+
--header 'Content-Type: application/json'
110+
--data '{
111+
"flowId": "95339089-72d1-4825-80fe-ab7864f4943b",
112+
"selectedAuthenticator": {
113+
"authenticatorId": "QmFzaWNBdXRoZW50aWNhdG9yOkxPQ0FM",
114+
"params": {
115+
"username": "username",
116+
"password": "password"
117+
}
118+
}
119+
}'
120+
```
121+
122+
=== "Response (`/authn`)"
123+
124+
```json
125+
{
126+
"flowStatus": "SUCCESS_COMPLETED",
127+
"authData": {
128+
"app_name": "Mobile App"
129+
}
130+
}
131+
```
132+
133+
- **Step 4**: Once the user completes authentication, the app on the client device polls the token endpoint with the `device_code` to obtain the access token.
134+
135+
=== "Request (`/token`)"
136+
137+
```bash
138+
curl --location '{{api_oauth2_path}}/token/'
139+
--header 'Content-Type: application/x-www-form-urlencoded'
140+
--data-urlencode 'grant_type=urn:ietf:params:oauth:grant-type:device_code'
141+
--data-urlencode 'device_code=d3fe0db1-2334-48fa-b7d9-821ecfad10d5'
142+
--data-urlencode 'client_id=XWRkRNkJDeTiR5MwHdXROGiJka'
143+
```
144+
145+
=== "Response (`/token`)"
146+
147+
```json
148+
{
149+
"access_token": "74d610ab-7f4a-3b11-90e8-279d76644fc7",
150+
"refresh_token": "fdb58069-ecc7-3803-9b8b-6f2ed85eff19",
151+
"token_type": "Bearer",
152+
"expires_in": 3600
153+
}
154+
```

0 commit comments

Comments
 (0)