Skip to content

Commit 8339b5e

Browse files
AfraHussaindeenAfraHussaindeen
authored
Merge pull request #5889 from AfraHussaindeen/master_jwt-scope-array-doc
[DOC] Add docs related to JWT access token scope format support
2 parents ce9d3a3 + a68ee8a commit 8339b5e

File tree

8 files changed

+185
-3
lines changed

8 files changed

+185
-3
lines changed

‎en/asgardeo/docs/apis/organization-apis/restapis/application.yaml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1125,6 +1125,10 @@ components:
11251125
type: boolean
11261126
description: "If enabled, both access token and the token binding needs to be present for a successful API
11271127
invocation."
1128+
enableJwtScopeAsArray:
1129+
type: boolean
1130+
description: "If enabled, the scope claim in JWT access tokens will be formatted as a JSON array instead of a space-separated string."
1131+
example: false
11281132
RefreshTokenConfiguration:
11291133
type: object
11301134
properties:

‎en/asgardeo/docs/apis/organization-apis/restapis/org-application-mgt.yaml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1927,6 +1927,10 @@ components:
19271927
type: array
19281928
items:
19291929
type: string
1930+
enableJwtScopeAsArray:
1931+
type: boolean
1932+
description: "If enabled, the scope claim in JWT access tokens will be formatted as a JSON array instead of a space-separated string."
1933+
example: false
19301934
RefreshTokenConfiguration:
19311935
type: object
19321936
properties:

‎en/asgardeo/docs/apis/restapis/application-management.yaml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4714,6 +4714,10 @@ components:
47144714
validateTokenBinding:
47154715
type: boolean
47164716
description: If enabled, both the access token and the token binding need to be present for a successful API invocation.
4717+
enableJwtScopeAsArray:
4718+
type: boolean
4719+
description: If enabled, the scope claim in JWT access tokens will be formatted as a JSON array instead of a space-separated string.
4720+
example: false
47174721
RefreshTokenConfiguration:
47184722
type: object
47194723
properties:

‎en/identity-server/next/docs/apis/organization-apis/restapis/application.yaml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1120,6 +1120,10 @@ components:
11201120
type: boolean
11211121
description: "If enabled, both access token and the token binding needs to be present for a successful API
11221122
invocation."
1123+
enableJwtScopeAsArray:
1124+
type: boolean
1125+
description: "If enabled, the scope claim in JWT access tokens will be formatted as a JSON array instead of a space-separated string."
1126+
example: false
11231127
RefreshTokenConfiguration:
11241128
type: object
11251129
properties:

‎en/identity-server/next/docs/apis/organization-apis/restapis/org-application-mgt.yaml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2258,6 +2258,10 @@ components:
22582258
type: array
22592259
items:
22602260
type: string
2261+
enableJwtScopeAsArray:
2262+
type: boolean
2263+
description: "If enabled, the scope claim in JWT access tokens will be formatted as a JSON array instead of a space-separated string."
2264+
example: false
22612265
RefreshTokenConfiguration:
22622266
type: object
22632267
properties:

‎en/identity-server/next/docs/apis/restapis/application.yaml‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5635,6 +5635,12 @@ components:
56355635
type: array
56365636
items:
56375637
type: string
5638+
enableJwtScopeAsArray:
5639+
type: boolean
5640+
description: >
5641+
If enabled, the scope claim in JWT access tokens will be formatted as a JSON array
5642+
instead of a space-separated string.
5643+
example: false
56385644
RefreshTokenConfiguration:
56395645
type: object
56405646
properties:

‎en/identity-server/next/docs/apis/restapis/configs.yaml‎

Lines changed: 133 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1169,7 +1169,131 @@ paths:
11691169
curl -X 'DELETE' \
11701170
'https://localhost:9443/api/server/v1/configs/authentication/inbound/passivests' \
11711171
-H 'accept: application/json' \
1172-
-H 'Authorization: Basic YWRtaW46YWRtaW4='
1172+
-H 'Authorization: Basic YWRtaW46YWRtaW4='
1173+
/configs/authentication/inbound/oauth2:
1174+
get:
1175+
tags:
1176+
- Inbound Authentication Configurations
1177+
summary: Retrieve OAuth2 inbound authentication configurations
1178+
description: |
1179+
Retrieve server OAuth2 inbound authentication configurations.
1180+
1181+
<b>Scope(Permission) required:</b> `internal_config_view`
1182+
operationId: getOAuth2InboundAuthConfig
1183+
responses:
1184+
'200':
1185+
description: Successful response
1186+
content:
1187+
application/json:
1188+
schema:
1189+
$ref: '#/components/schemas/InboundAuthOAuth2Config'
1190+
'400':
1191+
description: Bad request
1192+
content:
1193+
application/json:
1194+
schema:
1195+
$ref: '#/components/schemas/Error'
1196+
'401':
1197+
description: Unauthorized
1198+
'403':
1199+
description: Forbidden
1200+
'404':
1201+
description: Not Found
1202+
content:
1203+
application/json:
1204+
schema:
1205+
$ref: '#/components/schemas/Error'
1206+
'500':
1207+
description: Server Error
1208+
content:
1209+
application/json:
1210+
schema:
1211+
$ref: '#/components/schemas/Error'
1212+
x-codeSamples:
1213+
- lang: Curl
1214+
source: |
1215+
curl -X 'GET' \
1216+
'https://localhost:9443/api/server/v1/configs/authentication/inbound/oauth2' \
1217+
-H 'accept: application/json' \
1218+
-H 'Authorization: Basic YWRtaW46YWRtaW4='
1219+
patch:
1220+
tags:
1221+
- Inbound Authentication Configurations
1222+
summary: Update OAuth2 inbound authentication configurations
1223+
description: |
1224+
Patch server OAuth2 inbound authentication configurations.
1225+
1226+
<b>Scope(Permission) required:</b> `internal_config_update`
1227+
operationId: updateOAuth2InboundAuthConfig
1228+
requestBody:
1229+
content:
1230+
application/json:
1231+
schema:
1232+
$ref: '#/components/schemas/InboundAuthOAuth2Config'
1233+
responses:
1234+
'200':
1235+
description: Successful response
1236+
'400':
1237+
description: Bad request
1238+
content:
1239+
application/json:
1240+
schema:
1241+
$ref: '#/components/schemas/Error'
1242+
'401':
1243+
description: Unauthorized
1244+
'403':
1245+
description: Forbidden
1246+
'404':
1247+
description: Not Found
1248+
content:
1249+
application/json:
1250+
schema:
1251+
$ref: '#/components/schemas/Error'
1252+
'500':
1253+
description: Server Error
1254+
content:
1255+
application/json:
1256+
schema:
1257+
$ref: '#/components/schemas/Error'
1258+
x-codeSamples:
1259+
- lang: Curl
1260+
source: |
1261+
curl -X 'PATCH' \
1262+
'https://localhost:9443/api/server/v1/configs/authentication/inbound/oauth2' \
1263+
-H 'accept: */*' \
1264+
-H 'Authorization: Basic YWRtaW46YWRtaW4=' \
1265+
-H 'Content-Type: application/json' \
1266+
-d '{
1267+
"enableJwtScopeAsArray": true
1268+
}'
1269+
delete:
1270+
tags:
1271+
- Inbound Authentication Configurations
1272+
summary: Delete OAuth2 inbound authentication configurations.
1273+
description: |
1274+
Delete all OAuth2 inbound authentication configurations.<br><br>
1275+
<b>Scope (Permission) required:</b> internal_config_update
1276+
operationId: deleteOAuth2InboundAuthConfig
1277+
responses:
1278+
'204':
1279+
description: Successful deletion
1280+
'401':
1281+
description: Unauthorized
1282+
'403':
1283+
description: Forbidden
1284+
'500':
1285+
description: Server Error
1286+
content:
1287+
application/json:
1288+
schema:
1289+
$ref: '#/components/schemas/Error'
1290+
x-codeSamples:
1291+
- lang: Curl
1292+
source: |
1293+
curl -X 'DELETE' \
1294+
'https://localhost:9443/api/server/v1/configs/authentication/inbound/oauth2' \
1295+
-H 'accept: application/json' \
1296+
-H 'Authorization: Basic YWRtaW46YWRtaW4='
11731297
servers:
11741298
- url: 'https://{serverUrl}/t/{tenantDomain}/api/server/v1'
11751299
variables:
@@ -1691,4 +1815,11 @@ components:
16911815
type: string
16921816
description: "Passive STS URL"
16931817
readOnly: true
1694-
example: "https://localhost:9443/passivests"
1818+
example: "https://localhost:9443/passivests"
1819+
InboundAuthOAuth2Config:
1820+
type: object
1821+
properties:
1822+
enableJwtScopeAsArray:
1823+
type: boolean
1824+
description: "Enable formatting scope claim in JWT access tokens as a JSON array instead of a space-separated string."
1825+
example: false

‎en/includes/guides/fragments/manage-app/oidc-settings/access-token.md‎

Lines changed: 26 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,32 @@
2525
"expires_in": 3600
2626
}
2727
```
28-
<br>
28+
29+
!!! note
30+
By default, the `scope` claim in JWT access tokens uses a space-separated string format (e.g., `"scope": "openid profile email"`). This format complies with the **JSON Web Token (JWT) Profile for OAuth 2.0 Access Tokens ([RFC 9068](https://www.rfc-editor.org/rfc/rfc9068.html))**.
31+
32+
You can change this to a JSON array format (e.g., `"scope": ["openid", "profile", "email"]`), but this is **not recommended** as it deviates from the standard specification.
33+
34+
If you still require this configuration, it can be applied at two levels:
35+
36+
- **Application level**: Set the `enableJwtScopeAsArray` property in the application's `accessToken` configuration via the [Application Management API]({{base_path}}/apis/{% if product_name == "Asgardeo" %}application-management{% else %}application-rest-api{% endif %}/). This overrides the tenant-level setting for the specific application.
37+
{% if product_name == "WSO2 Identity Server" %}
38+
- **Tenant level**: Use the [Server Configuration API]({{base_path}}/apis/configs-rest-api/#tag/Inbound-Authentication-Configurations/operation/updateOAuth2InboundAuthConfig) to set the `enableJwtScopeAsArray` property. This applies to all applications in the tenant unless overridden at the application level.
39+
{% endif %}
40+
{% if product_name == "Asgardeo" %}
41+
- **Organization level**: Set the `enableJwtScopeAsArray` property via the following API. This applies to all applications in the organization unless overridden at the application level.
42+
43+
Get an access token with the `internal_config_update` scope and use it to execute the following cURL:
44+
45+
``` curl
46+
curl --location --request PATCH 'https://api.asgardeo.io/t/<organization_name>/api/server/v1/configs/authentication/inbound/oauth2' \
47+
--header 'Content-Type: application/json' \
48+
--header 'Authorization: Bearer <access_token>' \
49+
--data '{
50+
"enableJwtScopeAsArray": true
51+
}'
52+
```
53+
{% endif %}
2954

3055
{% if product_name == "Asgardeo" or (product_name == "WSO2 Identity Server" and is_version != "7.0.0") %}
3156
#### Access Token Attributes

0 commit comments

Comments
 (0)