> ## 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.
# Process Backchannel Authentication Request
> This API parses request parameters of a [backchannel authentication request](https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html#auth_request) and returns necessary data for the authorization server implementation to process the backchannel authentication request further.
This API is supposed to be called from within the implementation of the [backchannel authentication
endpoint](https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html#auth_backchannel_endpoint)
of the service. The endpoint implementation must extract the request parameters from the
backchannel authentication request from the client application and pass them as the value of parameters
request parameter for Authlete's `/backchannel/authentication` API.
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.
The following code snippet is an example in JAX-RS showing how to extract request parameters from
the backchannel authentication request.
```java
@POST
@Consumes(MediaType.APPLICATION_FORM_URLENCODED)
public Response post(String parameters)
{
// 'parameters' is the entity body of the backchannel authentication request.
......
}
```
The endpoint implementation does not have to parse the request parameters from the client application
because Authlete's `/backchannel/authentication` API does it.
The response from `/backchannel/authentication` API has various parameters. Among them, it is `action`
parameter that the authorization server implementation should check first because it denotes the
next action that the authorization server implementation should take. According to the value of
`action`, the service implementation must take the steps described below.
## INTERNAL\_SERVER\_ERROR
When the value of `action` is `INTERNAL_SERVER_ERROR`, it means that the request from the authorization
server implementation was wrong or that an error occurred in Authlete.
In either case, from the viewpoint of the client application, it is an error on the server side.
Therefore, the service implementation should generate a response to the client application with
HTTP status of "500 Internal Server Error" 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 500 Internal Server Error
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache
{responseContent}
```
## BAD\_REQUEST
When the value of `action` is `BAD_REQUEST`, it means that the request from the client application
is invalid.
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
{responseContent}
```
## UNAUTHORIZED
When the value of `action` is `UNAUTHORIZED`, it means that client authentication of the backchannel
authentication request failed. Note that client authentication is always required at the backchannel
authentication endpoint. This implies that public clients are not allowed to use the backchannel
authentication endpoint.
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
{responseContent}
```
## USER\_IDENTIFICATION
When the value of `action` is `USER_IDENTIFICATION`, it means that the backchannel authentication
request from the client application is valid. The authorization server implementation has to follow
the steps below.
**\[1] END-USER IDENTIFICATION**
The first step is to determine the subject (= unique identifier) of the end-user from whom the
client application wants to get authorization.
According to the CIBA specification, a backchannel authentication request contains one (and only
one) of the `login_hint_token`, `id_token_hint` and `login_hint` request parameters as a hint
by which the authorization server identifies the subject of an end-user.
The authorization server implementation can know which hint is included in the backchannel authentication
request by the `hintType` parameter. For example, when the value of the parameter `LOGIN_HINT`,
it means that the backchannel authentication request contains the `login_hint` request parameter
as a hint.
The value of the `hint` parameter is the value of the hint. For example, when the value of the
`hintType` parameter is `LOGIN_HINT`, The value of the `hint` parameter is the value of the `login_hint`
request parameter.
It is up to the authorization server implementation how to determine the subject of the end-user
from the hint. Only when the `id_token_hint` request parameter is used, authorization server
implementation can use the sub response parameter, which holds the value of the sub claim in the
`id_token_hint` request parameter.
**\[2] END-USER IDENTIFICATION ERROR**
There are some cases where the authorization server implementation encounters an error during
the user identification process. In any error case, the service implementation has to return an
HTTP response with the error response parameter to the client application. The following is an
example of such error responses.
```
HTTP/1.1 400 Bad Request
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache
{ "error":"unknown_user_id" }
```
Authlete provides `/backchannel/authentication/fail` API that builds the response body (JSON)
of an error response. However, because it is easy to build an error response manually, you may
choose not to call the API. One good thing in using the API is that the API call can trigger
deletion of the ticket which has been issued from Authlete's `/backchannel/authentication` API.
If you don't call `/backchannel/authentication/fail` API, the ticket will continue to exist in
the database until it is cleaned up by the batch program after the ticket expires.
Possible error cases that the authorization server implementation itself has to handle are as
follows. Other error cases have already been covered by `/backchannel/authentication` API.
* `expired_login_hint_token`
The authorization server implementation detected that the hint presented by the `login_hint_token`
request parameter has expired.
Note that the format of `login_hint_token` is not described in the CIBA Core spec at all and
so there is no consensus on how to detect expiration of `login_hint_token`. Interpretation
of `login_hint_token` is left to each authorization server implementation.
* `unknown_user_id`
The authorization server implementation could not determine the subject of the end-user by
the presented hint.
* `unauthorized_client`
The authorization server implementation has custom rules to reject backchannel authentication
requests from some particular clients and found that the client which has made the backchannel
authentication request is one of the particular clients.
Note that `/backchannel/authentication` API does not return `action=USER_IDENTIFICATION` in
cases where the client does not exist or client authentication has failed. Therefore, the
authorization server implementation will never have to use the error code `unauthorized_client`
unless the server has intentionally implemented custom rules to reject backchannel authentication
requests based on clients.
* `missing_user_code`
The authorization server implementation has custom rules to require that a backchannel authentication
request include a user code for some particular users and found that the user identified by
the hint is one of the particular users.
Note that `/backchannel/authentication` API does not return `action=USER_IDENTIFICATION` when
both the `backchannel_user_code_parameter_supported` metadata of the server and the
`backchannel_user_code_parameter` metadata of the client are true and the backchannel authentication
request does not include the user\_code request parameter. In this case, `/backchannel/authentication`
API returns action=BAD\_REQUEST with JSON containing `"error":"missing_user_code"`. Therefore,
the authorization server implementation will never have to use the error code `missing_user_code`
unless the server has intentionally implemented custom rules to require a user code based
on users even in the case where the `backchannel_user_code_parameter` metadata of the client
which has made the backchannel authentication request is `false`.
* `invalid_user_code`
The authorization server implementation detected that the presented user code is invalid.
Note that the format of user\_code is not described in the CIBA Core spec at all and so there
is no consensus on how to judge whether a user code is valid or not. It is up to each authorization
server implementation how to handle user codes.
* `invalid_binding_message`
The authorization server implementation detected that the presented binding message is invalid.
Note that the format of binding\_message is not described in the CIBA Core spec at all and
so there is no consensus on how to judge whether a binding message is valid or not. It is
up to each authorization server implementation how to handle binding messages.
* `invalid_target`
The authorization server implementation rejects the requested target resources.
The error code invalid\_target is from "Resource Indicators for OAuth 2.0". The specification
defines the resource request parameter. By using the parameter, client applications can request
target resources that should be bound to the access token being issued. If the authorization
server wants to reject the request, call `/backchannel/authentication/fail` API with `INVALID_TARGET`.
* `access_denined`
The authorization server implementation has custom rules to reject backchannel authentication
requests without asking the end-user and respond to the client as if the end-user had rejected
the request in some particular cases and found that the backchannel authentication request
is one of the particular cases.
The authorization server implementation will never have to use the error code `access_denied`
at this timing unless the server has intentionally implemented custom rules to reject backchannel
authentication requests without asking the end-user and respond to the client as if the end-user
had rejected the request.
**\[3] AUTH\_REQ\_ID ISSUE**
If the authorization server implementation has successfully determined the subject of the end-user,
the next action is to return an HTTP response to the client application which contains `auth_req_id`.
Authlete provides `/backchannel/authentication/issue` API which generates a JSON containing `auth_req_id`,
so, your next action is (1) call the API, (2) receive the response from the API, (3) build a response
to the client application using the content of the API response, and (4) return the response to
the client application. See the description of `/backchannel/authentication/issue` API for details.
**\[4] END-USER AUTHENTICATION AND AUTHORIZATION**
After sending a JSON containing `auth_req_id` back to the client application, the service implementation
starts to communicate with an authentication device of the end-user. It is assumed that end-user
authentication is performed on the authentication device and the end-user confirms the content of
the backchannel authentication request and grants authorization to the client application if everything
is okay. The authorization server implementation must be able to receive the result of the end-user
authentication and authorization from the authentication device.
How to communicate with an authentication device and achieve end-user authentication and authorization
is up to each authorization server implementation, but the following request parameters of the backchannel
authentication request should be taken into consideration in any implementation.
* `acr_values`
A backchannel authentication request may contain an array of ACRs (Authentication Context Class
References) in preference order. If multiple authentication devices are registered for the end-user,
the authorization server implementation should take the ACRs into consideration when selecting
the best authentication device.
* `scope`
A backchannel authentication request always contains a list of scopes. At least, `openid` is
included in the list (otherwise `/backchannel/authentication` API returns `action=BAD_REQUEST`).
It would be better to show the requested scopes to the end-user on the authentication device
or somewhere appropriate.
If the scope request parameter contains `address`, `email`, `phone` and/or `profile`, they are
interpreted as defined in "5.4. Requesting Claims using Scope Values of OpenID Connect Core 1.0".
That is, they are expanded into a list of claim names. The claimNames parameter returns the expanded
result.
* `binding_message`
A backchannel authentication request may contain a binding message. It is a human readable identifier
or message intended to be displayed on both the consumption device (client application) and the
authentication device.
* `user_code`
A backchannel authentication request may contain a user code. It is a secret code, such as password
or pin, known only to the end-user but verifiable by the authorization server. The user code should
be used to authorize sending a request to the authentication device.
**\[5] END-USER AUTHENTICATION AND AUTHORIZATION COMPLETION**
After receiving the result of end-user authentication and authorization, the authorization server
implementation must call Authlete's `/backchannel/authentication/complete` API to tell Authlete
the result and pass necessary data so that Authlete can generate an ID token, an access token and
optionally a refresh token. See the description of the API for details.
**\[6] CLIENT NOTIFICATION**
When the backchannel token delivery mode is either `ping` or `push`, the authorization server implementation
must send a notification to the pre-registered notification endpoint of the client after the end-user
authentication and authorization. In this case, the `action` parameter in a response from `/backchannel/authentication/complete`
API is `NOTIFICATION`. See the description of `/backchannel/authentication/complete` API for details.
**\[7] TOKEN REQUEST**
When the backchannel token delivery mode is either `ping` or `poll`, the client application will make
a token request to the token endpoint to get an ID token, an access token and optionally a refresh
token.
A token request that corresponds to a backchannel authentication request uses `urn:openid:params:grant-type:ciba`
as the value of the `grant_type` request parameter. Authlete's `/auth/token` API recognizes the
grant type automatically and behaves properly, so the existing token endpoint implementation does
not have to be changed to support CIBA.
## OpenAPI
````yaml https://spec.speakeasy.com/authlete/sdk-workspace/authlete-api-explorer-with-code-samples post /api/{serviceId}/backchannel/authentication
openapi: 3.0.3
info:
title: Authlete API
description: ''
version: 3.0.16
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
- description: πΊπΈ US Cluster
url: https://us.authlete.com
- description: π―π΅ Japan Cluster
url: https://jp.authlete.com
- description: πͺπΊ Europe Cluster
url: https://eu.authlete.com
- description: π§π· Brazil Cluster
url: https://br.authlete.com
security:
- bearer: []
tags:
- name: Service Management
description: >-
API endpoints for managing services, including creation, update, and
deletion of services.
x-tag-expanded: false
- name: Client Management
description: >-
API endpoints for managing OAuth clients, including creation, update, and
deletion of clients.
x-tag-expanded: false
- name: Authorization Endpoint
description: API endpoints for implementing OAuth 2.0 Authorization Endpoint.
x-tag-expanded: false
- name: Pushed Authorization Endpoint
description: >-
API endpoints for implementing OAuth 2.0 Pushed Authorization Requests
(PAR).
x-tag-expanded: false
- name: Token Endpoint
description: API endpoints for implementing OAuth 2.0 Token Endpoint.
x-tag-expanded: false
- name: Token Operations
description: >-
API endpoints for various token related operations, including creating,
revoking and deleting access_tokens with specified scopes.
x-tag-expanded: false
- name: Introspection Endpoint
description: API endpoints for implementing OAuth 2.0 Introspection Endpoint.
x-tag-expanded: false
- name: Revocation Endpoint
description: API endpoint for implementing OAuth 2.0 Revocation Endpoint.
x-tag-expanded: false
- name: UserInfo Endpoint
description: API endpoints for implementing OpenID Connect UserInfo Endpoint.
x-tag-expanded: false
- name: JWK Set Endpoint
description: API endpoints for to generate JSON Web Key Set (JWKS) for a service.
x-tag-expanded: false
- name: Discovery Endpoint
description: API endpoints for implementing OpenID Connect Discovery.
x-tag-expanded: false
- name: Configuration Endpoint
description: API endpoint for accessing configuration settings for a service.
x-tag-expanded: false
- name: Dynamic Client Registration
description: API endpoints for implementing OAuth 2.0 Dynamic Client Registration.
x-tag-expanded: false
- name: CIBA
description: >-
API endpoints for implementing Client-Initiated Backchannel Authentication
(CIBA).
x-tag-expanded: false
- name: Grant Management Endpoint
description: >-
API endpoint for implementing OAuth 2.0 grants, including grant management
actions like updating and revoking grants.
x-tag-expanded: false
- name: Jose Object
description: API endpoints for JOSE objects.
x-tag-expanded: false
- name: Device Flow
description: API endpoints for implementing OAuth 2.0 Device Flow
x-tag-expanded: false
- name: Federation Endpoint
description: API endpoints for implementing OpenID Federation using Authlete.
x-tag-expanded: false
- name: Verifiable Credential Issuer
description: >-
API endpoints for implementing and running a Verifiable Credential Issuer
(VCI).
x-tag-expanded: false
- name: Hardware Security Key
description: API endpoints for managing hardware security keys (HSK).
x-tag-expanded: false
- name: Utility Endpoints
description: API endpoints for various utility operations.
x-tag-expanded: false
- name: Native SSO
description: API endpoints for Native SSO
x-tag-expanded: false
paths:
/api/{serviceId}/backchannel/authentication:
post:
tags:
- CIBA
summary: Process Backchannel Authentication Request
description: >
This API parses request parameters of a [backchannel authentication
request](https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html#auth_request)
and returns necessary data for the authorization server implementation
to process the backchannel
authentication request further.
operationId: backchannel_authentication_api
parameters:
- in: path
name: serviceId
description: A service ID.
schema:
type: string
required: true
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/backchannel_authentication_request'
example:
parameters: >-
login_hint=john&scope=openid&client_notification_token=my-client-notification-token&user_code=my-user-code
clientId: '26862190133482'
clientSecret: >-
8J9pAEX6IQw7lYtYGsc_s9N4jlEz_DfkoCHIswJjFjfgKZX-nC4EvKtaHXcP9mHBfS7IU4jytjSZZpaK9UJ77A
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/backchannel_authentication_request'
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/backchannel_authentication_response'
example:
resultCode: A179001
resultMessage: >-
[A179001] The backchannel authentication request was processed
successfully.
action: USER_IDENTIFICATION
clientId: 26862190133482
clientIdAliasUsed: false
clientName: My CIBA Client
clientNotificationToken: my-client-notification-token
deliveryMode: POLL
hint: john
hintType: LOGIN_HINT
requestedExpiry: 0
scopes:
- defaultEntry: false
name: openid
serviceAttributes:
- key: attribute1-key
value: attribute1-value
- key: attribute2-key
value: attribute2-value
ticket: Y1qeCf0A-JUz6caceaBfd2AaBYNZ-X-WGTP5Qv47cQI
userCode: my-user-code
userCodeRequired: false
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'500':
$ref: '#/components/responses/500'
x-codeSamples:
- lang: typescript
label: Typescript (SDK)
source: |-
import { Authlete } from "@authlete/typescript-sdk";
const authlete = new Authlete({
bearer: process.env["AUTHLETE_BEARER"] ?? "",
});
async function run() {
const result = await authlete.ciba.processAuthentication({
serviceId: "",
backchannelAuthenticationRequest: {
parameters: "login_hint=john&scope=openid&client_notification_token=my-client-notification-token&user_code=my-user-code",
clientId: "26862190133482",
clientSecret: "8J9pAEX6IQw7lYtYGsc_s9N4jlEz_DfkoCHIswJjFjfgKZX-nC4EvKtaHXcP9mHBfS7IU4jytjSZZpaK9UJ77A",
},
});
console.log(result);
}
run();
- lang: ruby
label: Ruby (SDK)
source: >-
require 'authlete_ruby_sdk'
Models = ::Authlete::Models
s = ::Authlete::Client.new(
bearer: ''
)
res = s.ciba.process_authentication(service_id: '',
backchannel_authentication_request:
Models::Components::BackchannelAuthenticationRequest.new(
parameters: 'login_hint=john&scope=openid&client_notification_token=my-client-notification-token&user_code=my-user-code',
client_id: '26862190133482',
client_secret: '8J9pAEX6IQw7lYtYGsc_s9N4jlEz_DfkoCHIswJjFjfgKZX-nC4EvKtaHXcP9mHBfS7IU4jytjSZZpaK9UJ77A'
))
unless res.backchannel_authentication_response.nil?
# handle response
end
- lang: go
label: Go (SDK)
source: "package main\n\nimport(\n\t\"context\"\n\t\"os\"\n\tauthlete \"github.com/authlete/authlete-go-sdk\"\n\t\"github.com/authlete/authlete-go-sdk/models/components\"\n\t\"log\"\n)\n\nfunc main() {\n ctx := context.Background()\n\n s := authlete.New(\n authlete.WithSecurity(os.Getenv(\"AUTHLETE_BEARER\")),\n )\n\n res, err := s.Ciba.ProcessAuthentication(ctx, \"\", components.BackchannelAuthenticationRequest{\n Parameters: \"login_hint=john&scope=openid&client_notification_token=my-client-notification-token&user_code=my-user-code\",\n ClientID: authlete.Pointer(\"26862190133482\"),\n ClientSecret: authlete.Pointer(\"8J9pAEX6IQw7lYtYGsc_s9N4jlEz_DfkoCHIswJjFjfgKZX-nC4EvKtaHXcP9mHBfS7IU4jytjSZZpaK9UJ77A\"),\n })\n if err != nil {\n log.Fatal(err)\n }\n if res.BackchannelAuthenticationResponse != nil {\n // handle response\n }\n}"
x-code-samples:
- lang: shell
label: curl
source: >
curl -v -X POST
https://us.authlete.com/api/21653835348762/backchannel/authentication
\
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer
V5a40R6dWvw2gMkCOBFdZcM95q4HC0Z-T0YKD9-nR6F' \
-d '{ "parameters":
"login_hint=john&scope=openid&client_notification_token=my-client-notification-token&user_code=my-user-code",
"clientId": "26862190133482",
"clientSecret":"8J9pAEX6IQw7lYtYGsc_s9N4jlEz_DfkoCHIswJjFjfgKZX-nC4EvKtaHXcP9mHBfS7IU4jytjSZZpaK9UJ77A"
}'
- lang: java
label: java
source: >
AuthleteConfiguration conf = ...;
AuthleteApi api = AuthleteApiFactory.create(conf);
BackchannelAuthenticationRequest req = new
BackchannelAuthenticationRequest();
req.setParameters(...);
req.setClientId("26862190133482");
req.setClientSecret("8J9pAEX6IQw7lYtYGsc_s9N4jlEz_DfkoCHIswJjFjfgKZX-nC4EvKtaHXcP9mHBfS7IU4jytjSZZpaK9UJ77A");
api.backchannelAuthentication(req);
- lang: python
source: >
conf = ...
api = AuthleteApiImpl(conf)
req = BackchannelAuthenticationRequest()
req.parameters = ...
req.clientId = '26862190133482'
req.clientSecret =
'8J9pAEX6IQw7lYtYGsc_s9N4jlEz_DfkoCHIswJjFjfgKZX-nC4EvKtaHXcP9mHBfS7IU4jytjSZZpaK9UJ77A'
api.backchannelAuthentication(req)
components:
schemas:
backchannel_authentication_request:
type: object
required:
- parameters
properties:
parameters:
type: string
description: >
Parameters of a backchannel authentication request which are the
request parameters that the
backchannel authentication endpoint of the OpenID provider
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:
type: string
description: >
The client ID extracted from Authorization header of the backchannel
authentication request from
the client application.
If the backchannel authentication endpoint of the OpenID provider
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:
type: string
description: >
The client secret extracted from Authorization header of the
backchannel authentication request
from the client application.
If the backchannel authentication endpoint of the OpenID provider
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:
type: string
description: >
The client certification used in the TLS connection between the
client application and the
backchannel authentication endpoint of the OpenID provider.
clientCertificatePath:
type: array
items:
type: string
description: >
The client certificate path presented by the client during client
authentication. Each element
is a string in PEM format.
oauthClientAttestation:
type: string
description: >
The value of the `OAuth-Client-Attestation` HTTP header, which is
defined in the specification
of [OAuth 2.0 Attestation-Based Client
Authentication](https://datatracker.ietf.org/doc/draft-ietf-oauth-attestation-based-client-auth/).
oauthClientAttestationPop:
type: string
description: >
The value of the `OAuth-Client-Attestation-PoP` HTTP header, which
is defined in the specification
of [OAuth 2.0 Attestation-Based Client
Authentication](https://datatracker.ietf.org/doc/draft-ietf-oauth-attestation-based-client-auth/).
cimdOptions:
$ref: '#/components/schemas/cimd_options'
description: >
Options for [OAuth Client ID Metadata
Document](https://datatracker.ietf.org/doc/draft-ietf-oauth-client-id-metadata-document/)
(CIMD).
These options allow per-request control over CIMD behavior, taking
precedence over service-level configuration when provided.
backchannel_authentication_response:
type: object
properties:
resultCode:
type: string
description: The code which represents the result of the API call.
resultMessage:
type: string
description: A short message which explains the result of the API call.
action:
type: string
enum:
- INTERNAL_SERVER_ERROR
- BAD_REQUEST
- UNAUTHORIZED
- USER_IDENTIFICATION
description: >-
The next action that the authorization server implementation should
take.
responseContent:
type: string
description: >
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:
type: integer
format: int64
description: >
The client ID of the client application that has made the
backchannel authentication
request.
clientIdAlias:
type: string
description: >
The client ID alias of the client application that has made the
backchannel authentication
request.
clientIdAliasUsed:
type: boolean
description: >
`true` if the value of the client_id request parameter included in
the backchannel
authentication request is the client ID alias. `false` if the value
is the original
numeric client ID.
clientName:
type: string
description: >
The name of the client application which has made the backchannel
authentication request.
scopes:
type: array
items:
$ref: '#/components/schemas/scope'
description: |
The scopes requested by the backchannel authentication request.
x-mint:
metadata:
description: The scopes requested by the backchannel authentication request.
content: >
Basically, this property holds the value of the `scope` request
parameter in the backchannel
authentication request. However, because unregistered scopes are
dropped on Authlete side,
if the `scope` request parameter contains unknown scopes, the list
returned by this
property becomes different from the value of the `scope` request
parameter.
Note that `description` property and `descriptions` property of
each `scope` object
in the array contained in this property is always null even if
descriptions of the scopes
are registered.
claimNames:
type: array
items:
type: string
description: >
The names of the claims which were requested indirectly via some
special scopes.
See [5.4. Requesting Claims using Scope
Values](https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims)
in OpenID Connect Core 1.0 for details.
clientNotificationToken:
type: string
description: >
The client notification token included in the backchannel
authentication request.
acrs:
type: array
items:
type: string
description: >
The list of ACR values requested by the backchannel authentication
request.
Basically, this property holds the value of the `acr_values` request
parameter in the
backchannel authentication 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.
hintType:
type: string
description: >
The type of the hint for end-user identification which was included
in the backchannel authentication request.
hint:
type: string
description: |
The value of the hint for end-user identification.
sub:
type: string
description: >
The value of the `sub` claim contained in the ID token hint included
in the backchannel authentication request.
bindingMessage:
type: string
description: >
The binding message included in the backchannel authentication
request.
userCode:
type: string
description: >
The binding message included in the backchannel authentication
request.
userCodeRequired:
type: boolean
description: >
The flag which indicates whether a user code is required.
`true` when both the `backchannel_user_code_parameter` metadata of
the client (= Client's
`bcUserCodeRequired` property) and the
`backchannel_user_code_parameter_supported`
metadata of the service (= Service's
`backchannelUserCodeParameterSupported` property)
are `true`.
requestedExpiry:
type: integer
format: int32
description: >
The requested expiry for the authentication request ID
(`auth_req_id`).
requestContext:
type: string
description: >
The request context of the backchannel authentication request.
It is the value of the request_context claim in the signed
authentication request and
its format is JSON. request_context is a new claim added by the
FAPI-CIBA profile.
warnings:
type: array
items:
type: string
description: >
The warnings raised during processing the backchannel authentication
request.
ticket:
type: string
description: >
The ticket which is necessary to call Authlete's `/auth/token/fail`
API or `/auth/token/issue` API.
This parameter has a value only if the value of `grant_type` request
parameter is `password` and the token request is valid.
resources:
type: array
items:
type: string
description: >
The resources specified by the `resource` request parameters or by
the `resource` property
in the request object. If both are given, the values in the request
object should be
set. See "Resource Indicators for OAuth 2.0" for details.
authorizationDetails:
$ref: '#/components/schemas/authz_details'
serviceAttributes:
type: array
items:
$ref: '#/components/schemas/pair'
description: >
The attributes of this service that the client application belongs
to.
clientAttributes:
type: array
items:
$ref: '#/components/schemas/pair'
description: |
The attributes of the client.
dynamicScopes:
type: array
items:
$ref: '#/components/schemas/dynamic_scope'
description: >
The dynamic scopes which the client application requested by the
scope request parameter.
deliveryMode:
$ref: '#/components/schemas/delivery_mode'
clientAuthMethod:
type: string
description: |
The client authentication method that was performed.
gmAction:
$ref: '#/components/schemas/grant_management_action'
grantId:
type: string
description: >
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](https://openid.net/specs/fapi-grant-management.html)
, which is supported by Authlete 2.3 and newer versions.
grant:
$ref: '#/components/schemas/grant'
grantSubject:
type: string
description: >
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](https://openid.net/specs/fapi-grant-management.html).
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:
type: string
description: |
The entity ID of the client.
clientEntityIdUsed:
type: boolean
description: >
Flag which indicates whether the entity ID of the client was used
when the request for the access token was made.
metadataDocumentLocation:
type: string
format: uri
description: >
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](https://datatracker.ietf.org/doc/draft-ietf-oauth-client-id-metadata-document/)
(CIMD) mechanism.
metadataDocumentUsed:
type: boolean
description: >
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.
cimd_options:
type: object
description: >
Options for [OAuth Client ID Metadata
Document](https://datatracker.ietf.org/doc/draft-ietf-oauth-client-id-metadata-document/)
(CIMD).
These options allow per-request control over CIMD behavior, taking
precedence over service-level configuration when provided.
properties:
alwaysRetrieved:
type: boolean
description: >
Whether to always retrieve client metadata in the CIMD context
regardless of the cache's validity.
Under normal circumstances, client metadata retrieved from the
location referenced by the client ID is stored in the database with
an expiration time calculated using HTTP caching mechanisms (see
[RFC 9111 HTTP
Caching](https://www.rfc-editor.org/rfc/rfc9111.html)). Until that
expiration time is reached, Authlete does not attempt to retrieve
the client metadata again.
When this flag is set to `true`, Authlete retrieves the client
metadata regardless of the cache's validity.
If this flag is included in an Authlete API call and its value is
`true`, it takes precedence over the corresponding service
configuration (see `Service.cimdAlwaysRetrieved`).
This flag is effective only when the service supports CIMD (see
`Service.clientIdMetadataDocumentSupported`) and CIMD is actually
used to resolve client metadata. For example, if the client ID in a
request does not appear to be a valid URI, CIMD will not be used
even if the service is configured to support it. In such cases, this
flag has no effect.
Client metadata retrieval is performed only in the initiating
request of an authorization flow, and not in any subsequent
requests. For example, in the authorization code flow, metadata may
be retrieved during the authorization request, but not during the
subsequent token request. In contrast, in the client credentials
flow, metadata retrieval may occur because the token request itself
is the initiating request in the flow.
httpPermitted:
type: boolean
description: >
Whether to allow the `http` scheme in client IDs in the CIMD
context.
The specification requires the `https` scheme, but if this flag is
set to `true`, Authlete also allows the `http` scheme. The main
purpose of this option is to make development easier for developers
who run CIMD-enabled servers and a web server publishing client
metadata on their local machines without TLS.
Given this purpose, it is not recommended to enable this option in
production environments unless an allowlist is used (see
`Service.cimdAllowlistEnabled`).
If this flag is included in an Authlete API call and its value is
`true`, it takes precedence over the corresponding service
configuration (see `Service.cimdHttpPermitted`).
queryPermitted:
type: boolean
description: >
Whether to allow a query component in client IDs in the CIMD
context.
Although the specification states that a client ID "SHOULD NOT
include a query string component," it does technically allow it.
However, query components are prone to misuse. Therefore, Authlete
does not allow them by default. Setting this flag to `true` relaxes
that restriction.
If this flag is included in an Authlete API call and its value is
`true`, it takes precedence over the corresponding service
configuration (see `Service.cimdQueryPermitted`).
scope:
type: object
properties:
name:
type: string
description: The name of the scope.
defaultEntry:
type: boolean
description: >-
`true` to mark the scope as default. Scopes marked as default are
regarded as requested when an authorization request from a client
application does not contain scope request parameter.
description:
type: string
description: The description about the scope.
descriptions:
type: array
description: The descriptions about this scope in multiple languages.
items:
$ref: '#/components/schemas/tagged_value'
attributes:
type: array
description: The attributes of the scope.
items:
$ref: '#/components/schemas/pair'
authz_details:
type: object
description: >
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".
properties:
elements:
type: array
items:
$ref: '#/components/schemas/authorization_details_element'
description: |
Elements of this authorization details.
pair:
type: object
properties:
key:
type: string
description: The key part.
value:
type: string
description: The value part.
dynamic_scope:
type: object
properties:
name:
type: string
description: The scope name.
value:
type: string
description: The scope value.
delivery_mode:
type: string
enum:
- PING
- POLL
- PUSH
grant_management_action:
type: string
description: >
The grant management action of the device authorization request.
The `grant_management_action` request parameter is defined in
[Grant Management for OAuth
2.0](https://openid.net/specs/fapi-grant-management.html).
enum:
- CREATE
- QUERY
- REPLACE
- REVOKE
- MERGE
grant:
type: object
properties:
scopes:
type: array
items:
$ref: '#/components/schemas/grant_scope'
claims:
type: array
items:
type: string
description: |
The claims associated with the Grant.
authorizationDetails:
$ref: '#/components/schemas/authz_details'
result:
type: object
properties:
resultCode:
type: string
description: The code which represents the result of the API call.
resultMessage:
type: string
description: A short message which explains the result of the API call.
tagged_value:
type: object
properties:
tag:
type: string
description: The language tag part.
value:
type: string
description: The value part.
authorization_details_element:
type: object
required:
- type
properties:
type:
type: string
description: >
The type of this element.
From _"OAuth 2.0 Rich Authorization Requests"_: _"The type of
authorization data as a string.
This field MAY define which other elements are allowed in the
request. This element is REQUIRED."_
This property is always NOT `null`.
locations:
type: array
items:
type: string
description: >
The resources and/or resource servers. This property may be `null`.
From _"OAuth 2.0 Rich Authorization Requests"_: _"An array of
strings representing the location of
the resource or resource server. This is typically composed of
URIs."_
This property may be `null`.
actions:
type: array
items:
type: string
description: >
The actions.
From _"OAuth 2.0 Rich Authorization Requests"_: _"An array of
strings representing the kinds of actions
to be taken at the resource. The values of the strings are
determined by the API being protected."_
This property may be `null`.
dataTypes:
type: array
items:
type: string
description: >
From _"OAuth 2.0 Rich Authorization Requests"_: _"An array of
strings representing the kinds of data being requested
from the resource."_
This property may be `null`.
identifier:
type: string
description: >
The identifier of a specific resource.
From _"OAuth 2.0 Rich Authorization Requests"_: _"A string
identifier indicating a specific resource available at the API."_
This property may be `null`.
privileges:
type: array
items:
type: string
description: >
The types or levels of privilege.
From "OAuth 2.0 Rich Authorization Requests": _"An array of strings
representing the types or
levels of privilege being requested at the resource."_
This property may be `null`.
otherFields:
type: string
description: >
The RAR request in the JSON format excluding the pre-defined
attributes such as `type` and `locations`.
The content and semantics are specific to the deployment and the use
case implemented.
grant_scope:
type: object
properties:
scope:
type: string
description: |
Space-delimited scopes.
resource:
type: array
items:
type: string
description: |
List of resource indicators.
responses:
'400':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/result'
example:
resultCode: A001201
resultMessage: '[A001201] /auth/authorization, TLS must be used.'
'401':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/result'
example:
resultCode: A001202
resultMessage: '[A001202] /auth/authorization, Authorization header is missing.'
'403':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/result'
example:
resultCode: A001215
resultMessage: >-
[A001215] /auth/authorization, The client (ID = 26837717140341) is
locked.
'500':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/result'
example:
resultCode: A001101
resultMessage: '[A001101] /auth/authorization, Authlete Server error.'
securitySchemes:
bearer:
type: http
scheme: bearer
bearerFormat: JWT
description: >
Authenticate every request with a **Service Access Token** or
**Organization Token**.
Set the token value in the `Authorization: Bearer ` 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.
````