Rich Authorization Requests (RAR)

For Authlete 2.x documentation, see 2.x version.

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. Screen_Shot_2021-08-09_at_14

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. Screen_Shot_2021-08-09_at_14

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

URL-encoded

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"
     }'

JAR-wrapped

The same RAR content can be wrapped on a JAR as the sample below.

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\"
    }"
}

Endpoints

Tokens and Claims

Key Management

Metadata

Error Handling & Debugging

Security

Client Management

Service Settings

Preface

Configuration

Service Level Configuration

Client Level Configuration

Examples

Authorization request

Request

Response

Token request

Request

Response

Token introspection Request

Request

Response

​Preface

​Configuration

​Service Level Configuration

​Client Level Configuration

​Examples

​Authorization request

​Request

​Response

​Token request

​Request

​Response

​Token introspection Request

​Request

​Response

Preface

Configuration

Service Level Configuration

Client Level Configuration

Examples

Authorization request

Request

Response

Token request

Request

Response

Token introspection Request

Request

Response