Process Device Authorization Request - Authlete Documentation

Full description

This API is supposed to be called from the within the implementation of the device authorization endpoint of the service. The service implementation should retrieve the value of action from the response and take the following steps according to the value.

INTERNAL_SERVER_ERROR

When the value of action is INTERNAL_SERVER_ERROR, it means that the API call from the authorization server implementation was wrong or that an error occurred in Authlete. In either case, from a viewpoint of the client application, it is an error on the server side. Therefore, the authorization server implementation should generate a response to the client application with “500 Internal Server Error”s and application/json. The value of responseContent is a JSON string which describes t he error, so it can be used as the entity body of the response.

The following illustrates the response which the authorization server implementation should generate and return to the client application.

HTTP/1.1 500 Internal Server Error
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache
&#123;responseContent&#125;

BAD_REQUEST

When the value of action is BAD_REQUEST, it means that the request from the client application is wrong. The authorization server implementation should generate a response to the client application with “400 Bad Request” and application/json. The value of responseContent is a JSON string which describes the error, so it can be used as the entity body of the response.

The following illustrates the response which the service implementation should generate and return to the client application.

HTTP/1.1 400 Bad Request
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache
&#123;responseContent&#125;

UNAUTHORIZED

When the value of action is UNAUTHORIZED, it means that client authentication of the device authorization request failed. The authorization server implementation should generate a response to the client application with “401 Unauthorized” and application/json. The value of responseContent is a JSON string which describes the error, so it can be used as the entity body of the response.

The following illustrates the response which the service implementation must generate and return to the client application.

HTTP/1.1 401 Unauthorized
WWW-Authenticate: (challenge)
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache
&#123;responseContent&#125;

OK

When the value of action is OK, it means that the device authorization request from the client application is valid. The authorization server implementation should generate a response to the client application with “200 OK” and application/json. The responseContent is a JSON string which can be used as the entity body of the response.

The following illustrates the response which the authorization server implementation should generate and return to the client application.

Authorizations

Authorization

string

header

required

Authenticate every request with a Service Access Token or Organization Token. Set the token value in the Authorization: Bearer <token> header.

Service Access Token: Scoped to a single service. Use when automating service-level configuration or runtime flows.

Organization Token: Scoped to the organization; inherits permissions across services. Use for org-wide automation or when managing multiple services programmatically.

Both token types are issued by the Authlete console or provisioning APIs.

Path Parameters

serviceId

string

required

A service ID.

Body

parameters

string

required

Parameters of a device authorization request which are the request parameters that the device authorization endpoint of the authorization server implementation received from the client application.

The value of parameters is the entire entity body (which is formatted in application/x-www-form-urlencoded) of the request from the client application.

clientId

string

The client ID extracted from Authorization header of the device authorization request from the client application.

If the device authorization endpoint of the authorization server implementation supports Basic Authentication as a means of client authentication, and the request from the client application contained its client ID in Authorization header, the value should be extracted and set to this parameter.

clientSecret

string

The client secret extracted from Authorization header of the device authorization request from the client application.

If the device authorization endpoint of the authorization server implementation supports Basic Authentication as a means of client authentication, and the request from the client application contained its client secret in Authorization header, the value should be extracted and set to this parameter.

clientCertificate

string

The client certificate used in the TLS connection between the client application and the device authorization endpoint of the authorization server.

clientCertificatePath

string[]

The client certificate path presented by the client during client authentication. Each element is a string in PEM format.

oauthClientAttestation

string

The value of the OAuth-Client-Attestation HTTP header, which is defined in the specification of OAuth 2.0 Attestation-Based Client Authentication.

oauthClientAttestationPop

string

The value of the OAuth-Client-Attestation-PoP HTTP header, which is defined in the specification of OAuth 2.0 Attestation-Based Client Authentication.

cimdOptions

object

Options for OAuth Client ID Metadata Document (CIMD).

These options allow per-request control over CIMD behavior, taking precedence over service-level configuration when provided.

Show child attributes

Response

resultCode

string

The code which represents the result of the API call.

resultMessage

string

A short message which explains the result of the API call.

action

enum<string>

The next action that the authorization server implementation should take.

Available options:

INTERNAL_SERVER_ERROR,

BAD_REQUEST,

UNAUTHORIZED,

OK

responseContent

string

The content that the authorization server implementation is to return to the client application. Its format varies depending on the value of action parameter.

clientId

integer<int64>

The client ID of the client application that has made the device authorization request.

clientIdAlias

string

The client ID alias of the client application that has made the device authorization request.

clientIdAliasUsed

boolean

true if the value of the client_id request parameter included in the device authorization request is the client ID alias. false if the value is the original numeric client ID.

clientName

string

The name of the client application which has made the device authorization request.

clientAuthMethod

string

The client authentication method that should be performed at the device authorization endpoint.

scopes

object[]

The scopes requested by the device authorization request.

Show child attributes

claimNames

string[]

The names of the claims which were requested indirectly via some special scopes. See 5.4. Requesting Claims using Scope Values in OpenID Connect Core 1.0 for details.

acrs

string[]

The list of ACR values requested by the device authorization request.

Basically, this property holds the value of the acr_values request parameter in the device authorization request. However, because unsupported ACR values are dropped on Authlete side, if the acr_values request parameter contains unrecognized ACR values, the list returned by this property becomes different from the value of the acr_values request parameter.

deviceCode

string

The device verification code. This corresponds to the device_code property in the response to the client.

userCode

string

The end-user verification code. This corresponds to the user_code property in the response to the client.

verificationUri

string

The end-user verification URI. This corresponds to the verification_uri property in the response to the client.

verificationUriComplete

string

The end-user verification URI that includes the end-user verification code. This corresponds to the verification_uri_complete property in the response to the client.

expiresIn

integer<int32>

The duration of the device verification code in seconds. This corresponds to the expires_in property in the response to the client.

interval

integer<int32>

The minimum amount of time in seconds that the client must wait for between polling requests to the token endpoint. This corresponds to the interval property in the response to the client.

warnings

string[]

The warnings raised during processing the backchannel authentication request.

resources

string[]

The resources specified by the resource request parameters. See "Resource Indicators for OAuth 2.0" for details.

authorizationDetails

object

The authorization details. This represents the value of the authorization_details request parameter in the preceding device authorization request which is defined in "OAuth 2.0 Rich Authorization Requests".

Show child attributes

serviceAttributes

object[]

The attributes of this service that the client application belongs to.

Show child attributes

clientAttributes

object[]

The attributes of the client.

Show child attributes

dynamicScopes

object[]

The dynamic scopes which the client application requested by the scope request parameter.

Show child attributes

gmAction

enum<string>

The grant management action of the device authorization request.

The grant_management_action request parameter is defined in Grant Management for OAuth 2.0.

Available options:

CREATE,

QUERY,

REPLACE,

REVOKE,

MERGE

grantId

string

the value of the grant_id request parameter of the device authorization request.

The grant_id request parameter is defined in Grant Management for OAuth 2.0 , which is supported by Authlete 2.3 and newer versions.

grant

object

Show child attributes

grantSubject

string

The subject identifying the user who has given the grant identified by the grant_id request parameter of the device authorization request. Authlete 2.3 and newer versions support Grant Management for OAuth 2.0. An authorization request may contain a grant_id request parameter which is defined in the specification. If the value of the request parameter is valid, {@link #getGrantSubject()} will return the subject of the user who has given the grant to the client application. Authorization server implementations may use the value returned from {@link #getGrantSubject()} in order to determine the user to authenticate. The user your system will authenticate during the authorization process (or has already authenticated) may be different from the user of the grant. The first implementer's draft of "Grant Management for OAuth 2.0" does not mention anything about the case, so the behavior in the case is left to implementations. Authlete will not perform the grant management action when the subject passed to Authlete does not match the user of the grant.

clientEntityId

string

The entity ID of the client.

clientEntityIdUsed

boolean

Flag which indicates whether the entity ID of the client was used when the request for the access token was made.

metadataDocumentLocation

string<uri>

The location of the client's metadata document that was used to resolve client metadata.

This property is set when client metadata was retrieved via the OAuth Client ID Metadata Document (CIMD) mechanism.

metadataDocumentUsed

boolean

Flag indicating whether a metadata document was used to resolve client metadata for this request.

When true, the client metadata was retrieved via the CIMD mechanism rather than from the Authlete database.

Authlete

​INTERNAL_SERVER_ERROR

​BAD_REQUEST

​UNAUTHORIZED

​OK

Authorizations

Path Parameters

Body

Response

INTERNAL_SERVER_ERROR

BAD_REQUEST

UNAUTHORIZED

OK