Skip to content

Commit b2adaf6

Browse files
ThumimkuThumimku
authored
Merge pull request #5010 from VimukthiRajapaksha/master_rar
Add Rich Authorization Requests Documentation
2 parents dd0af05 + 8328417 commit b2adaf6

File tree

4 files changed

+163
-1
lines changed

4 files changed

+163
-1
lines changed

‎en/identity-server/next/docs/guides/authorization/rich-authorization-requests.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
{% set base_url = "localhost:9443" %} {% set base_url_sample = "localhost:9443" %}
2+
3+
{% include "../../../../../includes/guides/authorization/rich-authorization-requests.md" %}

‎en/identity-server/next/mkdocs.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -494,6 +494,7 @@ nav:
494494
- API authorization:
495495
- Role-based access control: guides/authorization/api-authorization/api-authorization.md
496496
- User Impersonation: guides/authorization/user-impersonation.md
497+
- Rich Authorization Requests: guides/authorization/rich-authorization-requests.md
497498
- Identity Verification:
498499
- Identity Verification: guides/identity-verification/index.md
499500
- Configure an Identity Verification Provider: guides/identity-verification/configure-identity-verification-provider.md

‎en/includes/guides/authorization/index.md‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,4 +8,8 @@ Role Based Access Control (RBAC) lets organizations grant limited access to its
88

99
## User impersonation
1010

11-
User impersonation involves granting temporary access to another user's account. Learn how to implement it in [User impersonation]({{base_path}}/guides/authorization/user-impersonation/).
11+
User impersonation involves granting temporary access to another user's account. Learn how to implement it in [User impersonation]({{base_path}}/guides/authorization/user-impersonation/).
12+
13+
## Rich authorization requests
14+
15+
Rich Authorization Requests (RAR) (RFC 9396) enhance authorization mechanisms by allowing clients to specify fine-grained authorization details. Learn how to use it in [Rich Authorization Requests]({{base_path}}/guides/authorization/rich-authorization-requests/).

‎en/includes/guides/authorization/rich-authorization-requests.md‎

Lines changed: 154 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,154 @@
1+
# Rich Authorization Requests
2+
3+
Rich Authorization Requests (RAR) (RFC 9396) enhance authorization mechanisms by allowing clients to specify fine-grained authorization details in a structured format.
4+
This guide outlines how to configure your application for RAR, authorize API resources, customize authorization validation, and obtain tokens with authorization details.
5+
6+
## Configuring your application for RAR
7+
You can go through the following steps to prepare your application for rich authorization requests.
8+
9+
### Step 1: Register a new authorization details type
10+
11+
Before using RAR, you need to define the authorization details types that your application supports.
12+
This involves registering an authorization details types using the [API Resource Management Rest API]({{base_path}}/apis/api-resource-management-rest-api/).
13+
(The `authorizationDetailsTypes` field in the request payload follows the JSON Schema Draft 2020-12 standard.)
14+
15+
The following request registers a new authorization details types named `payment_initiation` for a Payments API
16+
and the response contains details of the newly registered API resource and its authorization details types.
17+
18+
Sample request
19+
20+
```curl
21+
curl --location 'https://<serverUrl>/api/server/v1/api-resources' \
22+
--header 'accept: application/json' \
23+
--header 'Content-Type: application/json' \
24+
--header 'Authorization: Basic YWRtaW46YWRtaW4=' \
25+
--data '{"name":"Payments API","identifier":"payments_api","description":"Payments API representation","requiresAuthorization":true,"authorizationDetailsTypes":[{"type":"payment_initiation","name":"Payment Initiations Type","description":"Payment initiation authorization details type","schema":{"type":"object","required":["type","actions","locations","instructedAmount"],"properties":{"locations":{"type":"array","items":{"type":"string","format":"uri"}},"instructedAmount":{"type":"object","properties":{"currency":{"type":"string","minLength":3},"amount":{"type":"string"}}},"type":{"type":"string","enum":["payment_initiation"]},"creditorName":{"type":"string"},"actions":{"type":"array","items":{"type":"string","enum":["initiate","status","cancel"]}},"creditorAccount":{"type":"object"}}}}]}'
26+
```
27+
Sample response
28+
29+
```json
30+
{"id":"ae1c234f-6497-42f5-8bbd-b4a7e2237807","name":"Payments API","identifier":"payments_api","description":"Payments API representation","requiresAuthorization":true,"type":"BUSINESS","authorizationDetailsTypes":[{"id":"e2134d3b-9efc-454c-8fcc-985c414bf6cb","type":"payment_initiation","name":"Payment Initiations Type","description":"Payment initiation authorization details type","schema":{"type":"object","required":["type","actions","locations","instructedAmount"],"properties":{"locations":{"type":"array","items":{"type":"string","format":"uri"}},"instructedAmount":{"type":"object","properties":{"currency":{"type":"string","minLength":3},"amount":{"type":"string"}}},"type":{"type":"string","enum":["payment_initiation"]},"creditorName":{"type":"string"},"actions":{"type":"array","items":{"type":"string","enum":["initiate","status","cancel"]}},"creditorAccount":{"type":"object"}}}}],"properties":[]}
31+
```
32+
33+
Once registered, to retrieve the supported authorization details types, invoke the discovery endpoint of {{product_name}}.
34+
The response confirms that the `payment_initiation` authorization details type is registered and available for use.
35+
36+
Sample request
37+
38+
```curl
39+
curl --location 'https://<serverUrl>/oauth2/token/.well-known/openid-configuration'
40+
```
41+
42+
Sample response
43+
44+
```json
45+
{
46+
"introspection_endpoint" : "https://localhost:9443/oauth2/introspect",
47+
"end_session_endpoint" : "https://localhost:9443/oidc/logout",
48+
"registration_endpoint" : "https://localhost:9443/api/identity/oauth2/dcr/v1.0/register",
49+
"token_endpoint" : "https://localhost:9443/oauth2/token",
50+
"jwks_uri" : "https://localhost:9443/oauth2/jwks",
51+
"revocation_endpoint" : "https://localhost:9443/oauth2/revoke",
52+
"authorization_endpoint" : "https://localhost:9443/oauth2/authorize",
53+
"issuer" : "https://localhost:9443/oauth2/token",
54+
"authorization_details_types_supported": ["payment_initiation"]
55+
}
56+
```
57+
58+
### Step 2: Authorize an API resource for an application
59+
60+
To allow an application to use an API resource with a specific authorization details type, you need to explicitly authorize the resource for that application.
61+
62+
- You need to have an application registered in {{product_name}}. If you don't already have one, [register a web app with OIDC]({{base_path}}/guides/applications/register-oidc-web-app/).
63+
- You need to set the role audience for the created application. [Set the role audience for apps]({{base_path}}/guides/authorization/api-authorization/api-authorization/#set-the-role-audience-for-apps)
64+
- You can use [Authorized APIs]({{base_path}}/apis/application-rest-api/#tag/Authorized-APIs) to authorize the previously created api resource to the application with authorization details types as shown below.
65+
66+
Sample request
67+
68+
This request associates the `payment_initiation` authorization details type with the specified application.
69+
70+
```curl
71+
curl --location 'https://<serverUrl>/api/server/v1/applications/<applicationID>/authorized-apis' \
72+
--header 'accept: application/json' \
73+
--header 'Content-Type: application/json' \
74+
--header 'Authorization: Basic YWRtaW46YWRtaW4=' \
75+
--data '{"id":"<apiResourceID>","policyIdentifier":"RBAC","authorizationDetailsTypes":["payment_initiation"]}'
76+
```
77+
78+
### Step 3: Customize authorization details validation
79+
80+
By default, {{product_name}} validates authorization details against the registered authorization details type schema.
81+
However, if additional validation is required, you can extend the `org.wso2.carbon.identity.oauth2.rar.core.AuthorizationDetailsProcessor`
82+
Java interface and provide mechanisms to validate, enrich, and identify authorization details specific to your type.
83+
To execute your custom validation, create a JAR file with your implementation and place it in `<IS_HOME>/repository/components/lib` directory and restart the server.
84+
85+
The interface contains four methods:
86+
87+
```java
88+
ValidationResult validate(AuthorizationDetailsContext authorizationDetailsContext) throws AuthorizationDetailsProcessingException, IdentityOAuth2ServerException;
89+
```
90+
`validate` method is invoked once a new Rich Authorization Request is received to ensure that the
91+
authorization details are valid and meet the required criteria. The validation logic should
92+
be specific to the type of authorization details handled by the implementing class.
93+
94+
```java
95+
String getType();
96+
```
97+
`getType` method used to retrieve the type of authorization details handled by this processor. Each implementation should return a unique type identifier that represents the kind of
98+
authorization details it processes
99+
100+
```java
101+
boolean isEqualOrSubset(AuthorizationDetail requestedAuthorizationDetail, AuthorizationDetails existingAuthorizationDetails);
102+
```
103+
`isEqualOrSubset` method Checks if the requested authorization detail is equal to or a subset of the existing authorization details. This method verifies if the provided {@code requestedAuthorizationDetail} is either exactly the same as or
104+
a subset of the existingAuthorizationDetails that have been previously accepted by the resource owner
105+
106+
```java
107+
AuthorizationDetail enrich(AuthorizationDetailsContext authorizationDetailsContext);
108+
```
109+
`enrich` method is invoked prior to presenting the consent UI to the user. Its purpose is to enhance or augment the authorization details,
110+
providing additional context or information that may be necessary for informed consent. This may include adding more descriptive
111+
information, default values, or other relevant details that are crucial for the user to understand the authorization request fully.
112+
113+
## Get tokens with authorization details
114+
115+
Once authorization details are configured, an application can request an access token containing the required details.
116+
117+
### Sample client credentials grant flow
118+
119+
This request includes the url-encoded `payment_initiation` authorization details type and the response includes an
120+
access token with the requested authorization details.
121+
122+
Sample request
123+
124+
```curl
125+
curl --location 'https://<serverUrl>/oauth2/token' \
126+
--header 'Content-Type: application/x-www-form-urlencoded' \
127+
--header 'Authorization: Basic PGNsaWVudElEPjo8Y2xpZW50U2VjcmV0Pg==' \
128+
--data-urlencode 'grant_type=client_credentials' \
129+
--data-urlencode 'authorization_details=%5B%7B%22type%22%3A%22payment_initiation%22%2C%22actions%22%3A%5B%22initiate%22%5D%2C%22locations%22%3A%5B%22https%3A%2F%2Fexample.com%2Fpayments1%22%5D%2C%22instructedAmount%22%3A%7B%22currency%22%3A%22USD%22%2C%22amount%22%3A%223000.00%22%7D%2C%22creditorName%22%3A%22Merchant%20A%22%2C%22creditorAccount%22%3A%7B%22iban%22%3A%22%22%7D%7D%5D'
130+
```
131+
132+
Sample response
133+
134+
```json
135+
{"access_token":"9d1e9829-c4f3-3f39-b02c-84298ace1710","authorization_details":[{"locations":["https://example.com/payments1"],"instructedAmount":{"currency":"USD","amount":"3000.00"},"type":"payment_initiation","creditorName":"Merchant A","actions":["initiate"],"creditorAccount":{"iban":"c6142dc9-588c-49ec-8341-1b157c441d02"}}],"token_type":"Bearer","expires_in":3600}
136+
```
137+
138+
### validate the access token
139+
140+
To verify if an access token is valid and check its associated authorization details, invoke the token introspection endpoint.
141+
If the token is active, the response will include its associated authorization details.
142+
143+
```curl
144+
curl --location 'https://<serverUrl>/oauth2/introspect' \
145+
--header 'Content-Type: application/x-www-form-urlencoded' \
146+
--header 'Authorization: Basic YWRtaW46YWRtaW4=' \
147+
--data-urlencode 'token=9d1e9829-c4f3-3f39-b02c-84298ace1710'
148+
```
149+
150+
Sample response
151+
152+
```json
153+
{"aut":"APPLICATION_USER","aud":"gSrJzfo6HGdrmWMBEXUzzy14TQQa","nbf":1737884044,"authorization_details":[{"locations":["https://example.com/payments1"],"instructedAmount":{"currency":"USD","amount":"3000.00"},"type":"payment_initiation","creditorName":"Merchant A","actions":["initiate"],"creditorAccount":{"iban":"c6142dc9-588c-49ec-8341-1b157c441d02"}}],"active":true,"token_type":"Bearer","exp":1737887644,"iat":1737884044,"client_id":"gSrJzfo6HGdrmWMBEXUzzy14TQQa"}
154+
```

0 commit comments

Comments
 (0)