Complete Backchannel Authentication - Authlete Documentation

Typescript (SDK)

import { Authlete } from "@authlete/typescript-sdk";

const authlete = new Authlete({
  bearer: process.env["AUTHLETE_BEARER"] ?? "",
});

async function run() {
  const result = await authlete.ciba.complete({
    serviceId: "<id>",
    backchannelAuthenticationCompleteRequest: {
      ticket: "NFIHGx_btVrWmtAD093D-87JxvT4DAtuijEkLVHbS4Q",
      result: "AUTHORIZED",
      subject: "john",
    },
  });

  console.log(result);
}

run();

require 'authlete_ruby_sdk'

Models = ::Authlete::Models
s = ::Authlete::Client.new(
  bearer: '<YOUR_BEARER_TOKEN_HERE>'
)
res = s.ciba.complete_request(service_id: '<id>', backchannel_authentication_complete_request: Models::Components::BackchannelAuthenticationCompleteRequest.new(
  ticket: 'NFIHGx_btVrWmtAD093D-87JxvT4DAtuijEkLVHbS4Q',
  result: Models::Components::BackchannelAuthenticationCompleteRequestResult::AUTHORIZED,
  subject: 'john'
))

unless res.backchannel_authentication_complete_response.nil?
  # handle response
end

package main

import(
	"context"
	"os"
	authlete "github.com/authlete/authlete-go-sdk"
	"github.com/authlete/authlete-go-sdk/models/components"
	"log"
)

func main() {
    ctx := context.Background()

    s := authlete.New(
        authlete.WithSecurity(os.Getenv("AUTHLETE_BEARER")),
    )

    res, err := s.Ciba.Complete(ctx, "<id>", components.BackchannelAuthenticationCompleteRequest{
        Ticket: "NFIHGx_btVrWmtAD093D-87JxvT4DAtuijEkLVHbS4Q",
        Result: components.BackchannelAuthenticationCompleteRequestResultAuthorized,
        Subject: "john",
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.BackchannelAuthenticationCompleteResponse != nil {
        // handle response
    }
}

curl --request POST \
  --url https://us.authlete.com/api/{serviceId}/backchannel/authentication/complete \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "ticket": "<string>",
  "subject": "<string>",
  "sub": "<string>",
  "authTime": 123,
  "acr": "<string>",
  "claims": "<string>",
  "properties": [
    {
      "key": "<string>",
      "value": "<string>",
      "hidden": true
    }
  ],
  "scopes": [
    "<string>"
  ],
  "idtHeaderParams": "<string>",
  "errorDescription": "<string>",
  "errorUri": "<string>",
  "consentedClaims": [
    "<string>"
  ],
  "jwtAtClaims": "<string>",
  "accessToken": "<string>",
  "accessTokenDuration": 123,
  "refreshTokenDuration": 123,
  "idTokenAudType": "<string>"
}
'

{
  "resultCode": "A198001",
  "resultMessage": "[A198001] Successfully updated the database so that the token endpoint can generate tokens (mode = poll, result = AUTHORIZED).",
  "accessTokenDuration": 0,
  "action": "NO_ACTION",
  "authReqId": "_mzc-ZQdAhSPuMxTlO-MC_oqaOqYCrdNQ39PVxisaiE",
  "clientId": 26862190133482,
  "clientIdAliasUsed": false,
  "clientName": "My CIBA Client",
  "deliveryMode": "POLL",
  "idTokenDuration": 0,
  "refreshTokenDuration": 0,
  "serviceAttributes": [
    {
      "key": "attribute1-key",
      "value": "attribute1-value"
    },
    {
      "key": "attribute2-key",
      "value": "attribute2-value"
    }
  ]
}

{
  "resultCode": "A001201",
  "resultMessage": "[A001201] /auth/authorization, TLS must be used."
}

{
  "resultCode": "A001202",
  "resultMessage": "[A001202] /auth/authorization, Authorization header is missing."
}

{
  "resultCode": "A001215",
  "resultMessage": "[A001215] /auth/authorization, The client (ID = 26837717140341) is locked."
}

{
  "resultCode": "A001311",
  "resultMessage": "[A001311] /auth/authorization,  Too many requests, retry after 1 seconds. (Entity: 23769878923/87122303)"
}

{
  "resultCode": "A001101",
  "resultMessage": "[A001101] /auth/authorization, Authlete Server error."
}

POST

api

{serviceId}

backchannel

authentication

complete

Typescript (SDK)

import { Authlete } from "@authlete/typescript-sdk";

const authlete = new Authlete({
  bearer: process.env["AUTHLETE_BEARER"] ?? "",
});

async function run() {
  const result = await authlete.ciba.complete({
    serviceId: "<id>",
    backchannelAuthenticationCompleteRequest: {
      ticket: "NFIHGx_btVrWmtAD093D-87JxvT4DAtuijEkLVHbS4Q",
      result: "AUTHORIZED",
      subject: "john",
    },
  });

  console.log(result);
}

run();

require 'authlete_ruby_sdk'

Models = ::Authlete::Models
s = ::Authlete::Client.new(
  bearer: '<YOUR_BEARER_TOKEN_HERE>'
)
res = s.ciba.complete_request(service_id: '<id>', backchannel_authentication_complete_request: Models::Components::BackchannelAuthenticationCompleteRequest.new(
  ticket: 'NFIHGx_btVrWmtAD093D-87JxvT4DAtuijEkLVHbS4Q',
  result: Models::Components::BackchannelAuthenticationCompleteRequestResult::AUTHORIZED,
  subject: 'john'
))

unless res.backchannel_authentication_complete_response.nil?
  # handle response
end

package main

import(
	"context"
	"os"
	authlete "github.com/authlete/authlete-go-sdk"
	"github.com/authlete/authlete-go-sdk/models/components"
	"log"
)

func main() {
    ctx := context.Background()

    s := authlete.New(
        authlete.WithSecurity(os.Getenv("AUTHLETE_BEARER")),
    )

    res, err := s.Ciba.Complete(ctx, "<id>", components.BackchannelAuthenticationCompleteRequest{
        Ticket: "NFIHGx_btVrWmtAD093D-87JxvT4DAtuijEkLVHbS4Q",
        Result: components.BackchannelAuthenticationCompleteRequestResultAuthorized,
        Subject: "john",
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.BackchannelAuthenticationCompleteResponse != nil {
        // handle response
    }
}

curl --request POST \
  --url https://us.authlete.com/api/{serviceId}/backchannel/authentication/complete \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "ticket": "<string>",
  "subject": "<string>",
  "sub": "<string>",
  "authTime": 123,
  "acr": "<string>",
  "claims": "<string>",
  "properties": [
    {
      "key": "<string>",
      "value": "<string>",
      "hidden": true
    }
  ],
  "scopes": [
    "<string>"
  ],
  "idtHeaderParams": "<string>",
  "errorDescription": "<string>",
  "errorUri": "<string>",
  "consentedClaims": [
    "<string>"
  ],
  "jwtAtClaims": "<string>",
  "accessToken": "<string>",
  "accessTokenDuration": 123,
  "refreshTokenDuration": 123,
  "idTokenAudType": "<string>"
}
'

{
  "resultCode": "A198001",
  "resultMessage": "[A198001] Successfully updated the database so that the token endpoint can generate tokens (mode = poll, result = AUTHORIZED).",
  "accessTokenDuration": 0,
  "action": "NO_ACTION",
  "authReqId": "_mzc-ZQdAhSPuMxTlO-MC_oqaOqYCrdNQ39PVxisaiE",
  "clientId": 26862190133482,
  "clientIdAliasUsed": false,
  "clientName": "My CIBA Client",
  "deliveryMode": "POLL",
  "idTokenDuration": 0,
  "refreshTokenDuration": 0,
  "serviceAttributes": [
    {
      "key": "attribute1-key",
      "value": "attribute1-value"
    },
    {
      "key": "attribute2-key",
      "value": "attribute2-value"
    }
  ]
}

{
  "resultCode": "A001201",
  "resultMessage": "[A001201] /auth/authorization, TLS must be used."
}

{
  "resultCode": "A001202",
  "resultMessage": "[A001202] /auth/authorization, Authorization header is missing."
}

{
  "resultCode": "A001215",
  "resultMessage": "[A001215] /auth/authorization, The client (ID = 26837717140341) is locked."
}

{
  "resultCode": "A001311",
  "resultMessage": "[A001311] /auth/authorization,  Too many requests, retry after 1 seconds. (Entity: 23769878923/87122303)"
}

{
  "resultCode": "A001101",
  "resultMessage": "[A001101] /auth/authorization, Authlete Server error."
}

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

ticket

string

required

The ticket issued by Authlete's /backchannel/authentication API.

result

enum<string>

required

The result of the end-user authentication and authorization. One of the following. Details are described in the description.

Available options:

TRANSACTION_FAILED,

ACCESS_DENIED,

AUTHORIZED

subject

string

required

The subject (= unique identifier) of the end-user.

sub

string

The value of the sub claim that should be used in the ID token.

authTime

integer<int64>

The time at which the end-user was authenticated. Its value is the number of seconds from 1970-01-01.

acr

string

The reference of the authentication context class which the end-user authentication satisfied.

claims

string

Additional claims which will be embedded in the ID token.

properties

object[]

The extra properties associated with the access token.

Show child attributes

scopes

string[]

Scopes to replace the scopes specified in the original backchannel authentication request with. When nothing is specified for this parameter, replacement is not performed.

idtHeaderParams

string

JSON that represents additional JWS header parameters for ID tokens.

errorDescription

string

The description of the error. If this optional request parameter is given, its value is used as the value of the error_description property, but it is used only when the result is not AUTHORIZED. To comply with the specification strictly, the description must not include characters outside the set %x20-21 / %x23-5B / %x5D-7E.

errorUri

string

The URI of a document which describes the error in detail. This corresponds to the error_uri property in the response to the client.

consentedClaims

string[]

the claims that the user has consented for the client application to know.

jwtAtClaims

string

Additional claims that are added to the payload part of the JWT access token.

accessToken

string

The representation of an access token that may be issued as a result of the Authlete API call.

accessTokenDuration

integer<int64>

The duration (in seconds) of the access token that may be issued as a result of the Authlete API call.

When this request parameter holds a positive integer, it is used as the duration of the access token in. In other cases, this request parameter is ignored.

refreshTokenDuration

integer<int64>

The duration (in seconds) of the refresh token that may be issued as a result of the Authlete API call.

When this request parameter holds a positive integer, it is used as the duration of the refresh token in. In other cases, this request parameter is ignored.

idTokenAudType

string

The type of the aud claim of the ID token being issued. Valid values are as follows.

Value	Description
"array"	The type of the aud claim is always an array of strings.
"string"	The type of the aud claim is always a single string.
null	The type of the aud claim remains the same as before.

This request parameter takes precedence over the idTokenAudType property of the service.

Response

Backchannel authentication completed successfully

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:

SERVER_ERROR,

NO_ACTION,

NOTIFICATION

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 backchannel authentication request.

clientIdAlias

string

The client ID alias of the client application that has made the backchannel authentication request.

clientIdAliasUsed

boolean

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

string

The name of the client application which has made the backchannel authentication request.

deliveryMode

enum<string>

Available options:

PING,

POLL,

PUSH

clientNotificationEndpoint

string

The client notification endpoint to which a notification needs to be sent. This corresponds to the client_notification_endpoint metadata of the client application.

clientNotificationToken

string

The client notification token which needs to be embedded as a Bearer token in the Authorization header in the notification. This is the value of the client_notification_token request parameter included in the backchannel authentication request.

authReqId

string

The newly issued authentication request ID.

accessToken

string

The issued access token.

refreshToken

string

The issued refresh token.

idToken

string

The issued ID token.

accessTokenDuration

integer<int64>

The duration of the access token in seconds.

refreshTokenDuration

integer<int64>

The duration of the refresh token in seconds.

idTokenDuration

integer<int64>

The duration of the ID token in seconds.

jwtAccessToken

string

The issued access token in JWT format.

resources

string[]

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

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

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.

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.

consentedClaims

string[]

the claims that the user has consented for the client application to know.