Rich authorization requests in your tenant

Defining types

In Flow Policy, Authorization details types lists the types your APIs understand. Each has a Type value that clients send, such as photo_album, a name people see on the consent page, and 1 to 20 fields:

[{"name": "locations", "kind": "strings"},
 {"name": "actions", "kind": "strings", "required": true, "values": ["album.view", "album.upload"]},
 {"name": "identifier", "kind": "string", "required": true, "max_length": 40}]

A field is a string, a list of strings or a number, may be required, and may list the only values allowed. A request may carry only the fields its type lists, so the common fields (locations, actions, datatypes, identifier, privileges) are listed like any other. A type can be limited to some clients, can require that requests using it are pushed to /oauth/par, and can be turned off. Discovery lists enabled types in authorization_details_types_supported. Changing a type's fields, clients or pushed requirement, turning it off or removing it ends requests in progress and tokens that carry it; a new name or description does not. Managing types needs the tenant.oauth.authorization_details permissions, which Tenant Admin holds.

Asking for details

Send authorization_details with the authorization request, as a JSON array of up to 10 entries, each with its type. It can travel in a pushed request or inside a request object too. A malformed entry, an unknown or disabled type, a field the type does not list, a missing required field, a value outside the allowed values or a type the client may not use returns invalid_authorization_details. The consent page lists each entry with its fields. Details describe one request, so a person is asked every time, even when the client remembers consent for its scopes. A client set to skip consent is trusted by the tenant itself, so it receives approved details without the page.

Details in tokens

The code carries the approved details. The token response returns them in authorization_details, JWT access tokens carry the same claim, and introspection reports it. A token request may name some of the approved entries, each exactly as approved, to get a token for less; anything else is invalid_authorization_details. Refresh tokens keep every approved entry. A client using the client credentials grant may send authorization_details at the token endpoint directly. The device and token exchange grants do not carry details.

The sample photo API

When a token carries entries whose locations include the sample photo API's identifier, the API allows only what they name: an album operation needs an entry whose actions include the operation's action, such as album.view, and whose identifier, when it has one, is the album, such as album:4410. Anything else is refused with authorization_details_mismatch before the authorization engine is asked. Tokens without such entries are checked as before.

History and limits

Audit records refused requests with invalid_authorization_details, unknown_authorization_details_type, authorization_details_not_allowed or authorization_details_not_granted, and changes to types under tenant.oauth.authorization_details. A tenant can define up to 20 types, shown on its Usage view. A point-in-time restore turns off a type that was turned off, removed or changed after the restore point.