Documentation Index
Fetch the complete documentation index at: https://developers.authlete.com/llms.txt
Use this file to discover all available pages before exploring further.
Preface
This article explains Authlete’s support for RAR and how to use this feature to handle fine-grained permissions. For detailed specifications, please refer to the Overview of the RAR Specification
.
Configuration
To utilize Authlete’s RAR support, you must configure the type of authorization details (authorization_details) for both the service and the client.
- Service: Add the supported authorization details types
- Client: Specify the available authorization details types
Service Level Configuration
To configure a list of supported authorization types at the service level:
- Open the Service Settings in the Management Console.
- Navigate to Endpoints > Tokens and Claims > Advanced and to Scope.
- Under Supported Authorization Details Types, add the required
type values (e.g., payment_information, customer_information).
Clients can request types from this list, but none are granted by default.
List of supported authorization types by a service
Client Level Configuration
In the Management Console, you can configure the set of requestable authorization types for individual clients:
- Open Client Settings for the specific client.
- Navigate to Endpoints > Advanced and to Scope.
- Under Authorization Details Types, add the
type values that the client is allowed to request (e.g., customer_information).
- Click Add to include more types as needed.
These settings control which authorization_details types the client can declare in its requests.
List of authorization types that a client can request
Examples
Authorization request
You can use RAR regardless of whether or not the request is pushed, or a request object mechanism is used. There are constraints in place for those mechanisms: if the RAR request is very large, it will require clients to use PAR, if you need to make tamper evident, the request object (or JAR) should be used.
Request
For instance, if an RAR is URL-encoded and sent in an authorization request by a client, a request from an AS (that receives the authorization request) to Authlete’s /auth/authorization API would be like this:
curl --request POST 'https://us.authlete.com/api/{YOU_SERVICE_ID}/auth/authorization' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer gLmkGuAYT7V6LqH********kaWsk-QMvquoi1E' \
--data '{
"parameters": "client_id=4025660683512920&
scope=openid&
response_type=code&
redirect_uri=https%3A%2F%2Fmobile.example.com%2Fcb&
code_challenge=NcCW6zMwKWy5Mya8jopzE1SVeTBJBAHH1jU7TPpYK9A&
code_challenge_method=S256&
authorization\_details=%5B%7B%22type%22%3A%20%22customer\_information%22%2C%22locations%22%3A%20%5B%22https%3A%2F%2Fexample.com%2Fcustomers%22%2C%5D%2C%22actions%22%3A%5B%22read%22%2C%22write%22%5D%2C%22datatypes%22%3A%5B%22contacts%22%2C%22photos%22%5D%7D%5D"
}'
curl --request POST 'https://us.authlete.com/api/{YOU_SERVICE_ID}/auth/authorization' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer gLmkGuAYT7V6LqH********kaWsk-QMvquoi1E' \
--data-raw '{ "parameters": "client_id=4025658857453025&request=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6InNpZzEifQ.eyJpc3MiOiI0MDI1NjU4ODU3NDUzMDI1IiwiYXVkIjoiaHR0cHM6Ly9hdXRobGV0ZS5jb20iLCJyZXNwb25zZV90eXBlIjoiY29kZSIsImNsaWVudF9pZCI6IjQwMjU2NTg4NTc0NTMwMjUiLCJyZWRpcmVjdF91cmkiOiJodHRwczovL21vYmlsZS5leGFtcGxlLmNvbS9jYiIsInNjb3BlIjoib3BlbmlkIiwic3RhdGUiOiJhZjBpZmpzbGRraiIsImNvZGVfY2hhbGxlbmdlIjoiQW9OM29NcVFvUVF1RGhoQmc2VTF2Y0ljbXRtQ19QWm9UMGNoVEVSVktFZyIsImNvZGVfY2hhbGxlbmdlX21ldGhvZCI6IlMyNTYiLCJhdXRob3JpemF0aW9uX2RldGFpbHMiOlt7InR5cGUiOiJjdXN0b21lcl9pbmZvcm1hdGlvbiIsImxvY2F0aW9ucyI6WyJodHRwczovL2V4YW1wbGUuY29tL2N1c3RvbWVycyJdLCJhY3Rpb25zIjpbInJlYWQiLCJ3cml0ZSJdLCJkYXRhdHlwZXMiOlsiY29udGFjdHMiLCJwaG90b3MiXX1dLCJpYXQiOjE2Mjg1MzE0NDQsIm5iZiI6MTYyODUzMTQ0NCwiZXhwIjoxNjI4NTMyMDQ5LCJqdGkiOiI4WjJEbGpCaUZVckpnTUt3bThiQ3EifQ.PIxVI2GFWi7B_frRfLg9r8AWEz7HGeopMeQo7MLYVEMGpOdoPkt5piBrLXI7PPI7ohrUmhxd-B4kZfm4WfkKH5qSub4A_mdd6pBpTWacBgfVQDIOvzE1yPrawCDEWQn2xgdYd1G-KM6pk8rDngOMEfaBbnoJ5C9krQtgYMHGbDIScgm8Y5AHf5aEF41FboZI67BlvbzXdxcJEPvB2zLGwV9twMrJ07OeRX0NVpIamhhEgfMQ87FyOsPVx9bqYUPN_VjwgB8lkKgrCdIkc9jPs2mQkpUbx0AIg8Pfmwyw0F5Vih7tgBbpb1LlwNgW36La3DPtTY9xSZ7SQGcyGxteIA" }'
Response
Authlete extracts and echoes back the authorization details to the AS so they can be used for collecting end user approval.
{
"type": "authorizationResponse",
"resultCode": "A004001",
"resultMessage": "[A004001] Authlete has successfully issued a ticket to the service (API Key = 979748525706) for the authorization request from the client (ID = 4025658857453025). [response_type=code, openid=true]",
"action": "INTERACTION",
"authorizationDetails": {
"elements": [
{
"actions": ["read", "write"],
"dataTypes": ["contacts", "photos"],
"locations": ["https://example.com/customers"],
"type": "customer_information"
}
]
}, "requestObjectPayload": "{\"iss\":\"4025658857453025\",\"aud\":\"https://authlete.com\",\"response_type\":\"code\",\"client_id\":\"4025658857453025\",\"redirect_uri\":\"https://mobile.example.com/cb\",\"scope\":\"openid\",\"state\":\"af0ifjsldkj\",\"code_challenge\":\"AoN3oMqQoQQuDhhBg6U1vcIcmtmC_PZoT0chTERVKEg\",\"code_challenge_method\":\"S256\",\"authorization_details\":[{\"type\":\"customer_information\",\"locations\":[\"https://example.com/customers\"],\"actions\":[\"read\",\"write\"],\"datatypes\":[\"contacts\",\"photos\"]}],\"iat\":1628531444,\"nbf\":1628531444,\"exp\":1628532049,\"jti\":\"8Z2DljBiFUrJgMKwm8bCq\"}",
"ticket": "xTZCagNjVJUltVS-WD7CKZr1fp0zeFTAAva86Rmzuow"
}
Token request
After the user has approved, an authorization code is generated and sent to the original client. The client will invoke the token endpoint authenticating itself (if required) to the AS, and Authlete’s /auth/token API behind the AS will generate an access token and optionally an ID token (if using openid).
Note that the authorization details are not encoded into the ID token.
Request
curl --request POST 'https://us.authlete.com/api/{YOU_SERVICE_ID}/auth/token' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer gLmkGuAYT7V6LqH********kaWsk-QMvquoi1E' \
--data '{ "parameters": "grant_type=authorization_code&code=wkPCpsu-HsMDeaNFBI78LydnmW7IyadBLloa3Mn7ZzM&redirect_uri=https%3A%2F%2Fmobile.example.com%2Fcb&code_verifier=ZhoMDipQfa7iMabyG-wSQ83ATy1GCVvE8Lh3SlDZdNo", "clientId" : "4025658857453025" }'
Response
{
"type": "tokenResponse",
"resultCode": "A050001",
"resultMessage": "[A050001] The token request (grant_type=authorization_code) was processed successfully.",
"accessToken": "Q4nS7518ZP4W0JaabMGJRBYGj919SY1IyxuDHZUw_Qc",
"action": "OK",
"authorizationDetails": {
"elements": [
{
"actions": [
"read",
"write"
],
"dataTypes": [
"contacts",
"photos"
],
"locations": [
"https://example.com/customers"
],
"type": "customer_information"
}
]
},
"idToken": "eyJraWQiOiIzIiwiYWxnIjoiUlMyNTYifQ.eyJjcGYiOiIzOTY3ODczNjY4MyIsIm5hbWUiOiJDYXNleSBQdXJkeSIsImVtYWlsIjoiQ2lhcmFfU3BvcmVyQGdtYWlsLmNvbSIsImlzcyI6Imh0dHBzOi8vYXV0aGxldGUuY29tIiwic3ViIjoiQ2lhcmFfU3BvcmVyQGdtYWlsLmNvbSIsImF1ZCI6WyI0MDI1NjU4ODU3NDUzMDI1Il0sImV4cCI6MjUzNDAyMTI4MDAwLCJpYXQiOjE2Mjg1MzIzMjAsInNfaGFzaCI6ImJPaHRYOEY3M0lNalNQZVZBcXh5VFEifQ.Vrc3BcXtnAUtrnfSOPWagTWnV_SB0DL5cEp535pt33n8S4op94GSM51waTS6OcoZ-R7YKQ0l7FrMGxFl6MGFd6Wn_FjHNyu7J2TmEH9sARZTW7ZmWQo5euWkLx6NjgMAp_9LsjDXwB8Cjr3ujkVt3DdKRg6fkETwgGYYkEIrfdtRO_yJLANunHG-wm92TzOd44xXaTBF4bBinBcZFUrpr2nCPRM0rrUmBLw...",
"responseContent": "{\"access_token\":\"Q4nS7518ZP4W0JaabMGJRBYGj919SY1IyxuDHZUw_Qc\",\"authorization_details\":[{\"type\":\"customer_information\",\"locations\":[\"https://example.com/customers\"],\"actions\":[\"read\",\"write\"],\"datatypes\":[\"contacts\",\"photos\"]}],\"scope\":\"openid\",\"id_token\":\"eyJraWQiOiIzIiwiYWxnIjoiUlMyNTYifQ.eyJjcGYiOiIzOTY3ODczNjY4MyIsIm5hbWUiOiJDYXNleSBQdXJkeSIsImVtYWlsIjoiQ2lhcmFfU3BvcmVyQGdtYWlsLmNvbSIsImlzcyI6Imh0dHBzOi8vYXV0aGxldGUuY29tIiwic3ViIjoiQ2lhcmFfU3BvcmVyQGdtYWlsLmNvbSIsImF1ZCI6WyI0MDI1NjU4ODU3NDUzMDI1Il0sImV4cCI6MjUzNDAyMTI4MDAwLCJpYXQiOjE2Mjg1MzIzMjAsInNfaGFzaCI6ImJPaHRYOEY3M0lNalNQZVZBcXh5VFEifQ.Vrc3BcXtnAUtrnfSOPWagTWnV_SB0DL5cEp535pt33n8S4op94GSM51waTS6OcoZ-R7YKQ0l7FrMGxFl6MGFd6Wn_FjHNyu7J2TmEH...
...
}
Token introspection Request
Upon receiving an API request with an access token, the resource server utilizes the introspection endpoint to check the authorization granted to that token.
Request
The following example demonstrates a resource server conducting an RFC 7662-compliant token introspection request to the authorization server, which subsequently invokes Authlete’s /auth/introspection/standard API.
curl --request POST 'https://us.authlete.com/api/{YOU_SERVICE_ID}/auth/introspection/standard' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer gLmkGuAYT7V6LqH********kaWsk-QMvquoi1E' \
--data '{ "parameters": "token=Q4nS7518ZP4W0JaabMGJRBYGj919SY1IyxuDHZUw_Qc"}'
Response
The authorization server extracts responseContent from the API response to return it to the resource server as the introspection response. This response includes the authorization details (authorization_details) tied to the access token. The resource server uses this information to determine whether to allow or deny the API request.
{
"type": "standardIntrospectionResponse",
"resultCode": "A145001",
"resultMessage": "[A145001] Introspection was performed successfully (type=access_token, active=true).",
"action": "OK",
"responseContent": "{ \"sub\":\"Ciara_Sporer@gmail.com\",
\"authorization_details\":[ {
\"type\":\"customer_information\",
\"locations\":[\"https://example.com/customers\"],
\"actions\":[\"read\",\"write\"],
\"datatypes\":[\"contacts\",\"photos\"]
}], \"scope\":\"openid\",
\"iss\":\"https://authlete.com\",
\"active\":true,
\"token_type\":\"Bearer\",
\"exp\":1628618721,
\"client_id\":\"4025658857453025\"
}"
}
