API Documents

Data Types

This chapter describes the details of data types.

Application Type

The listed below are Authlete's constant values that correspond to the values of application_type property described in OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata.

  • WEB
  • NATIVE

OpenID Connect Dynamic Client Registration 1.0 imposes additional requirements on redirect URIs base on the application type. The following description about application_type is an excerpt from the specification.

OPTIONAL. Kind of the application. The default, if omitted, is web. The defined values are native or web. Web Clients using the OAuth Implicit Grant Type MUST only register URLs using the https scheme as redirect_uris; they MUST NOT use localhost as the hostname. Native Clients MUST only register redirect_uris using custom URI schemes or URLs using the http: scheme with localhost as the hostname. Authorization Servers MAY place additional constraints on Native Clients. Authorization Servers MAY reject Redirection URI values using the http scheme, other than the localhost case for Native Clients. The Authorization Server MUST verify that all the registered redirect_uris conform to these constraints. This prevents sharing a Client ID across different types of Clients.

The description above says "The default, if omitted, is web." However, Authlete allows the applicationType property of Client to be null. It is because Authlete does not think it is appropriate to force all OAuth 2.0 clients to comply with the new requirements.

Claim Type

The listed below are Authlete's constant values that correspond to the claim types described in OpenID Connect Core 1.0, 5.6. Claim Types. The supportedClaimTypes property of Service is a string array containing values listed below.

  • NORMAL
  • AGGREGATED
  • DISTRIBUTED

Note that, however, currently Authlete does not provide any API to help implementations for AGGREGATED and DISTRIBUTED.

Client

The table below lists top-level properties of the JSON object which represents a client application.

Name Type Description
number i32

The sequential number of the client application. The value of this property is assigned by Authlete. Even if the property has a value in a /client/create request or a /client/update request, it is ignored.

serviceNumber i32

The sequential number of the service of the client application. The value of this property is assigned by Authlete. Even if the property has a value in a /client/create request or a /client/update request, it is ignored.

developer string

The developer of the client application. It consists of at most 100 ASCII letters. This property must not be null.

clientId i64

The client ID. The value of this property is assigned by Authlete. Even if the property has a value in a /client/create request or a /client/update request, it is ignored.

clientSecret string

The client secret. A random 512-bit value encoded by base64url (86 letters). The value of this property is assigned by Authlete. Even if the property has a value in a /client/create request or a /client/update request, it is ignored.

Note that Authlete issues a client secret even to a "public" client application, but the client application should not use the client secret unless it changes its client type to "confidential". That is, a public client application should behave as if it had not been issued a client secret. To be specific, a token request from a public client of Authlete should not come along with a client secret although RFC 6749, 3.2.1. Client Authentication says as follows.

Confidential clients or other clients issued client credentials MUST authenticate with the authorization server as described in Section 2.3 when making requests to the token endpoint.

clientType string

The client type, either CONFIDENTIAL or PUBLIC. See RFC 6749, 2.1. Client Types for details.

If clientType in a /client/create request or a /client/update request is null, PUBLIC is used.

redirectUris URL array

Redirect URIs that the client application uses to receive a response from the authorization endpoint. Requirements for a redirect URI are as follows.

Requirements by RFC 6749
(From RFC 6749, 3.1.2. Redirection Endpoint)
  • Must be an absolute URI.
  • Must not have a fragment component.
Requirements by OpenID Connect
(From "OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata, application_type")
  • The scheme of the redirect URI used for Implicit Grant by a client application whose application type is "web" must be https. This is checked at runtime by Authlete.
  • The hostname of the redirect URI used for Implicit Grant by a client application whose application type is "web" must not be localhost. This is checked at runtime by Authlete.
  • The scheme of the redirect URI used by a client application whose application type is "native" must be either (1) a custom scheme or (2) http, which is allowed only when the hostname part is localhost. This is checked at runtime by Authlete.
Requirements by Authlete
  • Must consist of printable ASCII letters only.
  • Must not exceed 200 letters.

Note that Authlete allows the application type to be null. In other words, a client application does not have to choose "web" or "native" as its application type. If the application type is null, the requirements by OpenID Connect are not checked at runtime.

An authorization request from a client application which has not registered any redirect URI fails unless at least all the following conditions are satisfied.

  • The client type of the client application is "confidential".
  • The value of response_type request parameter is code.
  • The authorization request has the redirect_uri request parameter.
  • The value of scope request parameter does not contain openid.

RFC 6749 allows partial match of redirect URI under some conditions (see RFC 6749, 3.1.2.2. Registration Requirements for details), but OpenID Connect requires exact match.

responseTypes string array

A string array of response types which the client application declares that it will restrict itself to using. This property corresponds to response_types in OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata.

If responseTypes in a /client/create request or a /client/update request is null, an array containing just CODE is used.

grantTypes string array

A string array of grant types which the client application declares that it will restrict itself to using. This property corresponds to grant_types in OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata.

If grantTypes in a /client/create request or a /client/update request is null, an array containing just AUTHORIZATION_CODE is used.

applicationType string

The application type. WEB, NATIVE or null. The value of this property affects the validation steps for a redirect URI. See the description about redirectUris property above.

This property corresponds to application_type in OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata.

contacts string array

An array of email addresses of people responsible for the client application. Each element must consist of printable ASCII letters only and its length must not exceed 100.

This property corresponds to contacts in OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata.

clientName string

The name of the client application. At most 100 unicode letters.

If clientName in a /client/create request or a /client/update request is null, the client ID is used.

This property corresponds to client_name in OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata.

clientNames Tagged Value array

Client names with language tags. If the client application has different names for different languages, this property can be used to register the names.

logoUri URL

The URL pointing to the logo image of the client application. The URL must consist of printable ASCII letters only and its length must not exceed 200.

This property corresponds to logo_uri in OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata.

logoUris Tagged Value array

Logo image URLs with language tags. If the client application has different logo images for different languages, this property can be used to register URLs of the images.

clientUri URL

The URL pointing to the home page of the client application. The URL must consist of printable ASCII letters only and its length must not exceed 200.

This property corresponds to client_uri in OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata.

clientUris Tagged Value array

Home page URLs with language tags. If the client application has different home pages for different languages, this property can be used to register the URLs.

policyUri URL

The URL pointing to the page which describes the policy as to how end-users' profile data are used. The URL must consist of printable ASCII letters only and its length must not exceed 200.

This property corresponds to policy_uri in OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata.

policyUris Tagged Value array

URLs of policy pages with language tags. If the client application has different policy pages for different languages, this property can be used to register the URLs.

tosUri URL

The URL pointing to the "Terms Of Service" page. The URL must consist of printable ASCII letters only and its length must not exceed 200.

This property corresponds to tos_uri in OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata.

tosUris Tagged Value array

URLs of "Terms Of Service" pages with language tags. If the client application has different "Terms Of Service" pages for different languages, this property can be used to register the URLs.

jwksUri URL

The URL pointing to the JWK Set of the client application. The URL must consist of printable ASCII letters only and its length must not exceed 200. The content pointed to by the URL must be JSON which complies with the format described in "JSON Web Key (JWK), 5. JSON Web Key Set (JWK Set) Format". Of course, the JWK Set must not include private keys of the client application.

If the client application requests encryption for ID tokens (from the authorization/token/userinfo endpoints) and/or signs request objects, it must make available its JWK Set containing public keys for the encryption and/or the signature at the URL of jwksUri. The service (Authlete) fetches the JWK Set from the URL as necessary.

OpenID Connect Dynamic Client Registration 1.0 says that jwks must not be used when the client can use jwks_uri, but Authlete allows both properties to be registered at the same time. However, Authlete does not use the content of jwks when jwksUri is registered.

This property corresponds to jwks_uri in OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata.

jwks string

The content of the JWK Set of the client application. The format is described in "JSON Web Key (JWK), 5. JSON Web Key Set (JWK Set) Format". Of course, the JWK Set must not include private keys of the client application.

OpenID Connect Dynamic Client Registration 1.0 says that jwks must not be used when the client can use jwks_uri, but Authlete allows both properties to be registered at the same time. However, Authlete does not use the content of jwks when jwksUri is registered.

This property corresponds to jwks in OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata.

sectorIdentifier URL

The sector identifier which is a URL starting with https. The URL must consist of printable ASCII letters only and its length must not exceed 200.This URL is used by the service to calculate pairwise subject values. See OpenID Connect Core 1.0, 8.1. Pairwise Identifier Algorithm. Note that, however, Authlete does not support pairwise yet.

This property corresponds to sector_identifier_uri in OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata.

subjectType string

The subject type that the client application requests. Either PUBLIC or PAIRWISE. the default value is PUBLIC. Details about the subject type are described in OpenID Connect Core 1.0, 8. Subjct Identifier Types.

Because Authlete's implementation for PAIRWISE is not finished yet, even if subjectType configuration parameter of the client application is PAIRWISE, Authlete behaves as if it were PUBLIC.

This property corresponds to subject_type in OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata.

idTokenSignAlg string

The value of alg header parameter of JWS that the client application requires the service to use for signing an ID token. One of the values listed in JWS Algorithm. The default value is RS256.

NONE may be specified, but in that case, the client application cannot obtain an ID token from the service. That is, an authorization request requesting an ID token fails.

This property corresponds to id_token_signed_response_alg in OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata.

idTokenEncryptionAlg string

The value of alg header parameter of JWE that the client application requires the service to use for encrypting an ID token. One of the supported values listed in JWE Algorithm. The default value is null, meaning that an ID token is not encrypted. When idTokenEncryptionEnc is not null, this property must not be null.

If the value of this property indicates an asymmetric encryption algorithm, the client application must make available its JWK Set which contains a public key for encryption at the URL referred to by its jwksUri configuration property.

This property corresponds to id_token_encrypted_response_alg in OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata.

idTokenEncryptionEnc string

The value of enc header parameter of JWE that the client application requires the service to use for encrypting an ID token. One of the values listed in JWE Encryption Algorithm. The default value is (1) A128CBC_HS256 when idTokenEncryptionAlg is not null, or (2) null when idTokenEncryptionAlg is null.

This property corresponds to id_token_encrypted_response_enc in OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata.

userInfoSignAlg string

The value of alg header parameter of JWS that the client application requires the service to use for signing the JWT returned from the user info endpoint. One of the values listed in JWS Algorithm. The default value is null, meaning that the data from the user info endpoint is not signed.

If both userInfoSignAlg and userInfoEncryptionAlg are null, the format of the response from the user info endpoint is a plain JSON (not JWT). Note that null and NONE are different for this property.

This property corresponds to userinfo_signed_response_alg in OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata.

userInfoEncryptionAlg string

The value of alg header parameter of JWE that the client application requires the service to use for encrypting the JWT returned from the user info endpoint. One of the supported values listed in JWE Algorithm. The default value is null, meaning that the data from the user info endpoint is not encrypted. When userInfoEncryptionEnc is not null, this property must not be null.

If the value of this property indicates an asymmetric encryption algorithm, the client application must make available its JWK Set which contains a public key for encryption at the URL referred to by its jwksUri configuration property.

If both userInfoSignAlg and userInfoEncryptionAlg are null, the format of the response from the user info endpoint is a plain JSON (not JWT).

This property corresponds to userinfo_encrypted_response_alg in OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata.

userInfoEncryptionEnc string

The value of enc header parameter of JWE that the client application requires the service to use for encrypting the JWT returned from the user info endpoint. One of the values listed in JWE Encryption Algorithm. The default value is (1) A128CBC_HS256 when userInfoEncryptionAlg is not null, or (2) null when userInfoEncryptionAlg is null.

This property corresponds to userinfo_encrypted_response_enc in OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata.

requestSignAlg string

The value of alg header parameter of JWS that the client application uses for signing a request object. One of the values listed in JWS Algorithm. The default value is null, meaning that the client application may use any algorithm (among those supported by the service) to sign a request object (including none).

If the value of this property is not null, request objects sent from the client application must be signed using the algorithm. Request objects signed by other algorithms are rejected. Note that null and NONE are different for this property.

If the value of this property indicates an asymmetric signing algorithm, the client application must make available its JWK Set which contains a public key for the service to verify the signature of the request object at the URL referred to by its jwksUri configuration property.

This property corresponds to request_object_signing_alg in OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata.

requestEncryptionAlg string

The value of alg header parameter of JWE that the client application uses for encrypting a request object. One of the supported values listed in JWE Algorithm. The default value is null. When requestEncryptionEnc is not null, this property must not be null.

Regardless of whether the value of this property is null or not, the client application may and may not encrypt a request object. Furthermore, the client application may use other supported encryption algorithms.

This property corresponds to request_object_encryption_alg in OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata.

requestEncryptionEnc string

The value of enc header parameter of JWE that the client application uses for encrypting a request object. One of the values listed in JWE Encryption Algorithm. The default value is (1) A128CBC_HS256 when requestEncryptionAlg is not null, or (2) null when requestEncryptionAlg is null.

This property corresponds to request_object_encryption_enc in OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata.

tokenAuthMethod string

The client authentication method that the client application declares that it uses at the token endpoint. One of the values listed in Client Authentication Method. The default value is CLIENT_SECRET_BASIC.

This property corresponds to token_endpoint_auth_method in OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata.

tokenAuthSignAlg string

The value of alg header parameter of JWS which is used for client authentication at the token endpoint. One of the values listed in JWS Algorithm except NONE. The default value is null, meaning that the client may sign using any algorithm which is supported by the service. If the value of this property is not null, the client application must use the algorithm.

This property is used only for the two JWT-based client authentication, namely, PRIVATE_KEY_JWT and CLIENT_SECRET_JWT (see Cient Authentication Method). Note that, however, currently Authlete does not provide any API to help implementations for PRIVATE_KEY_JWT and CLIENT_SECRET_JWT.

This property corresponds to token_endpoint_auth_signing_alg in OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata.

defaultMaxAge i32

The default maximum authentication age in seconds. This value is used when an authorization request from the client application does not have max_age request parameter.

This property corresponds to default_max_age in OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata.

defaultAcrs string array

The default ACRs (Authentication Context Class References). This value is used when an authorization request from the client application has neither acr_values request parameter nor acr claim in claims request parameter.

Each element must consist of printable ASCII letters only and its length must not exceed 200.

authTimeRequired boolean

true if the client application requires the auth_time claim to be in an ID token. Regardless of the value of this property, Authlete embeds the auth_time claim when authTime parameter in the /auth/authorization/issue request is not 0 and does not do it when authTime is 0.

This property corresponds to require_auth_time in OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata.

loginUri URL

The URL which a third party can use to initiate a login by the client application. The URL must start with https and consist of ASCII letters only. Its length must not exceed 200.

This property corresponds to initiate_login_uri in OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata.

requestUris URL array

An array of URLs each of which points to a request object. Each URL must consist of printable ASCII letters only and its length must not exceed 200.

Authlete requires that URLs used as values for request_uri request parameter be pre-registered. This requestUris property is used for the pre-registration. See OpenID Connect Core 1.0, 6.2. Passing a Request Object by Reference for details.

description string

The description about the client application. At most 200 letters in unicode.

descriptions Tagged Value array

Descriptions about the client application with language tags. If the client application has different descriptions for different languages, this property can be used to register the descriptions.

createdAt long

The time at which this client was created. The value is represented as milliseconds since the UNIX epoch (1970-01-01).

modifiedAt long

The time at which this client was last modified. The value is represented as milliseconds since the UNIX epoch (1970-01-01).

Client Authentication Method

The table below lists Authlete's constant values that correspond to the client authentication methods at the token endpoint described in OpenID Connect Core 1.0, 9. Client Authentication.

Value Description
NONE

This value corresponds to "none" described in OpenID Connect Core 1.0, 9. Client Authentication.

CLIENT_SECRET_BASIC

This value corresponds to "client_secret_basic" described in OpenID Connect Core 1.0, 9. Client Authentication. This is the Basic Authentication based method described in RFC 6749, 2.3. Client Authentication, which authorization servers must support.

CLIENT_SECRET_POST

This value corresponds to "client_secret_post" described in OpenID Connect Core 1.0, 9. Client Authentication. This is the method using the request body, which is described in RFC 6749, 2.3. Client Authentication.

CLIENT_SECRET_JWT

This value corresponds to "client_secret_jwt" described in OpenID Connect Core 1.0, 9. Client Authentication.

PRIVATE_KEY_JWT

This value corresponds to "private_key_jwt" described in OpenID Connect Core 1.0, 9. Client Authentication.

RFC 6749, 2.3. Client Authentication mentions two means for client authentication. One is Basic Authentication where client credentials are encoded in Authorization header. The other is a means to embed client credentials in the request body in application/x-www-form-urlencoded format. OpenID Connect Core 1.0 adds two JWT-based client authentication methods, namely, client_secret_jwt and private_key_jwt.

The supportedTokenAuthMethods property of Service is a string array containing values listed above. Note that, however, currently Authlete does not provide any API to help implementations for CLIENT_SECRET_JWT and PRIVATE_KEY_JWT.

Client Type

The listed below are Authlete's constant values that correspond to the client types described in RFC 6749, 2.1. Client Types. The clientType property of Client has either of the values listed below.

  • CONFIDENTIAL
  • PUBLIC

Display

The listed below are Authlete's constant values that correspond to the display values described in "OpenID Connect Core 1.0, 3.1.2.1. Authentication Request, display". The supportedDisplays property of Service is a string array containing values listed below.

  • PAGE
  • POPUP
  • TOUCH
  • WAP

Grant Type

The table below lists Authlete's constant values that correspond to the values of grant_type request parameter for OAuth 2.0 token endpoint. Among the values listed here, however, implicit cannot be used as a value for grant_type request parameter. It exists only as a value of supportedGrantTypes property of Service and grantTypes property of Client.

Value Description
AUTHORIZATION_CODE

This corresponds to "authorization_code" defined in RFC 6749, 4.1.3. Access Token Request for Authorization Code Grant.

IMPLICIT

This corresponds to "implicit" defined in OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata for Implicit Grant.

PASSWORD

This corresponds to "password" defined in RFC 6749, 4.3.2. Access Token Request for Resource Owner Password Credentials Grant.

CLIENT_CREDENTIALS

This corresponds to "client_credentials" defined in RFC 6749, 4.4.2. Access Token Request for Client Credentials Grant.

REFRESH_TOKEN

This corresponds to "refresh_token" defined in RFC 6749, 6. Refreshing an Access Token.

JWE Algorithm

The listed below are Authlete's constant values that correspond to the values of "alg" header parameter of JSON Web Encryption (JWE), which are described in JSON Web Algorithms (JWA), 4.1. "alg" (Algorithm) Header Parameter Values for JWE.

  • RSA1_5
  • RSA_OAEP
  • RSA_OAEP_256
  • A128KW
  • A192KW
  • A256KW
  • DIR
  • ECDH_ES
  • ECDH_ES_A128KW
  • ECDH_ES_A192KW
  • ECDH_ES_A256KW
  • A128GCMKW
  • A192GCMKW
  • A256GCMKW
  • PBES2_HS256_A128KW
  • PBES2_HS384_A192KW
  • PBES2_HS512_A256KW

Currently, Authlete supports RSA1_5, RSA_OAEP, RSA_OAEP_256 and DIR only.

JWE Encryption Algorithm

The listed below are Authlete's constant values that correspond to the values of "enc" header parameter of JSON Web Encryption (JWE), which are described in JSON Web Algorithms (JWA), 5.1. "enc" (Encryption Algorithm) Header Parameter Values for JWE.

  • A128CBC_HS256
  • A192CBC_HS384
  • A256CBC_HS512
  • A128GCM
  • A192GCM
  • A256GCM

JWS Algorithm

The listed below are Authlete's constant values that correspond to the values of "alg" header parameter of JSON Web Signature (JWS), which are described in JSON Web Algorithms (JWA), 3.1. "alg" (Algorithm) Header Parameter Values for JWS.

  • NONE
  • HS256
  • HS384
  • HS512
  • RS256
  • RS384
  • RS512
  • ES256
  • ES384
  • ES512
  • PS256
  • PS384
  • PS512

Response Type

The table below lists Authlete's valid constant values that correspond to response_type request parameter for OAuth 2.0 authorization endpoint. RFC 6749 defines two values, "code" and "token". Other values listed here are added by OAuth 2.0 Multiple Response Type Encding Practices, which is a part of Open ID Connect specification.

The supportedResponseTypes property of Service and the responseTypes property of Client are a string array containing values listed below.

Value Description
NONE

This corresponds to "none" defined in OAuth 2.0 Multiple Response Type Encoding Practices, 4. None Response Type.

CODE

This corresponds to "code" defined in RFC 6749, 4.1.1. Authorization Request for Authorization Code Grant.

TOKEN

This corresponds to "token" defined in RFC 6749, 4.2.1. Authorization Request for Implicit Grant.

ID_TOKEN

This corresponds to "id_token" defined in OAuth 2.0 Multiple Response Type Encoding Practices, 3. ID Token Response Type.

CODE_TOKEN

This corresponds to "code token" defined in OAuth 2.0 Multiple Response Type Encoding Practices, 5. Definitions of Multiple-Valued Response Type Combinations.

CODE_ID_TOKEN

This corresponds to "code id_token" defined in OAuth 2.0 Multiple Response Type Encoding Practices, 5. Definitions of Multiple-Valued Response Type Combinations.

ID_TOKEN_TOKEN

This corresponds to "id_token token" defined in OAuth 2.0 Multiple Response Type Encoding Practices, 5. Definitions of Multiple-Valued Response Type Combinations.

CODE_ID_TOKEN_TOKEN

This corresponds to "code id_token token" defined in OAuth 2.0 Multiple Response Type Encoding Practices, 5. Definitions of Multiple-Valued Response Type Combinations.

Scope

This is a data structure for a scope which is described in RFC 6749, Access Token Scope. The data structure has properties listed in the following table.

Name Type Description
name string

The name of the scope. Letters that can be used for a scope name are %x21, %x23-5B and %x5D-7E. Put simply, they are printable ASCII letters excluding "space (%x20)", "double quotation mark (%x22)" and "backslash (%x5C)". Its length must not exceed 200.

defaultEntry boolean

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 string

OPTIONAL. The description of the scope. It is a unicode string. Its length must not exceed 200.

Service

The table below lists top-level properties of the JSON object which represents a service.

Name Type Description
number i32

The sequential number of the service. The value of this property is assigned by Authlete. Even if the property has a value in a /service/create request or a /service/update request, it is ignored.

serviceOwnerNumber i32

The sequential number of the service owner of the service. The value of this property is assigned by Authlete. Even if the property has a value in a /service/create request or a /service/update request, it is ignored.

serviceName string

The name of the service. It consists of at most 100 unicode letters. This property must not be null.

apiKey i64

The API key. The value of this property is assigned by Authlete. Even if the property has a value in a /service/create request or a /service/update request, it is ignored.

apiSecret string

The API secret. A random 256-bit value encoded by base64url (43 letters). The value of this property is assigned by Authlete. Even if the property has a value in a /service/create request or a /service/update request, it is ignored.

issuer URL

The issuer identifier of the service. A URL that starts with https:// and has no query or fragment component. For example, https://example.com. Authlete requires that the URL consist of only ASCII letters and its length not exceed 200. This property must not be null.

The value of this property is used as iss claim in an ID token and issuer property in the OpenID Provider Metadata.

authorizationEndpoint URL

The authorization endpoint of the service. A URL that starts with https:// and has no fragment component. For example, https://example.com/auth/authorization. Authlete requires that the URL consist of only ASCII letters and its length not exceed 200. This property must not be null.

The value of this property is used as authorization_endpoint property in the OpenID Provider Metadata.

tokenEndpoint URL

The token endpoint of the service. A URL that starts with https:// and has not fragment component. For example, https://example.com/auth/token. Authlete requires that the URL consist of only ASCII letters and its length not exceed 200. This property may be null if and only if the service supports only Implicit Grant (= supports response_type=token only).

The value of this property is used as token_endpoint property in the OpenID Provider Metadata.

revocationEndpoint URL

The revocation endpoint of the service. A URL that starts with https://. For example, https://example.com/auth/revocation. Authlete requires that the URL consist of only ASCII letters and its length not exceed 200. This property may be null if the service does not support the revocation endpoint.

userInfoEndpoint URL

The user info endpoint of the service. A URL that starts with https://. For example, https://example.com/auth/userinfo. Authlete requires that the URL consist of only ASCII letters and its length not exceed 200. This property may be null if the service does not support the user info endpoint.

The value of this property is used as userinfo_endpoint property in the OpenID Provider Metadata.

jwksUri URL

The URL of the service's JSON Web Key Set document. For example, http://example.com/auth/jwks. Authlete requires that the URL consist of only ASCII letters and its length not exceed 200. This property may be null if and only if the service does not support asymmetric signatures for ID tokens and asymmetric encryption for request objects.

Client applications accesses this URL (1) to get the public key of the service to validate the signature of an ID token issued by the service and (2) to get the public key of the service to encrypt an request object of the client application. See OpenID Connect Core 1.0, 10. Signatures and Encryption for details.

The value of this property is used as jwks_uri property in the OpenID Provider Metadata.

jwks string

The content of the service's JSON Web Key Set document. If this property is not null in a /service/create request or a /service/update, Authlete hosts the content in the database. This property must not be null and must contain pairs of public/private keys if the service wants to support asymmetric signatures for ID tokens and asymmetric encryption for request objects. See OpenID Connect Core 1.0, 10. Signatures and Encryption for details.

registrationEndpoint URL

The registration endpoint of the service. A URL that starts with https://. For example, https://example.com/auth/registration. Authlete requires that the URL consist of only ASCII letters and its length not exceed 200.

The value of this property is used as registration_endpoint property in the OpenID Provider Metadata.

supportedScopes Scope array

Scopes supported by the service. Authlete strongly recommends that the service register at least the following scopes.

Name Description
openid

A permission to get an ID token of an end-user.

The openid scope appears in "OpenID Connect Core 1.0, 3.1.2.1. Authentication Request, scope". Without this scope, Authlete does not allow response_type request parameter to have values other than code and token.

profile

A permission to get information about name, family_name, given_name, middle_name, nickname, preferred_username, profile, picture, website, gender birthdate, zoneinfo, locale and updated_at from the user info endpoint.

See OpenID Connect Core 1.0, 5.4. Requesting Claims using Scope Values for details.

email

A permission to get information about email and email_verified from the user info endpoint.

See OpenID Connect Core 1.0, 5.4. Requesting Claims using Scope Values for details.

address

A permission to get information about address from the user info endpoint.

See OpenID Connect Core 1.0, 5.4. Requesting Claims using Scope Values and 5.1.1. Address Claim for details.

phone

A permission to get information about phone_number and phone_number_verified from the user info endpoint.

See OpenID Connect Core 1.0, 5.4. Requesting Claims using Scope Values for details.

offline_access

A permission to get information from the user info endpoint even when the end-user is not present.

See OpenID Connect Core 1.0, 11. Offline Access for details.

The value of this property is used as scopes_supported property in the OpenID Provider Metadata.

supportedResponseTypes string array

Values of response_type request parameter that the service supports. Valid values are listed in Response Type.

The value of this property is used as response_types_supported property in the OpenID Provider Metadata.

supportedGrantTypes string array

Values of grant_type request parameter that the service supports. Valid values are listed in Grant Type.

The value of this property is used as grant_types_supported property in the OpenID Provider Metadata.

supportedAcrs string array

Values of Authentication Context Class References that the service supports.

The value of this property is used as acr_values_supported property in the OpenID Provider Metadata.

supportedTokenAuthMethods string array

Client authentication methods supported by the token endpoint of the service. Valid values are listed in Client Authentication Method. Note that, however, currently Authlete does not provide any API to help implementations for CLIENT_SECRET_JWT and PRIVATE_KEY_JWT.

The value of this property is used as token_endpoint_auth_methods_supports property in the OpenID Provider Metadata.

supportedDisplays string array

Values of display request parameter that service supports. Valid values are listed in Display.

The value of this property is used as display_values_supported property in the OpenID Provider Metadata.

supportedClaimTypes string array

Claim types supported by the service. Valid values are listed in Claim Type. Note that, however, currently Authlete does not provide any API to help implementations for AGGREGATED and DISTRIBUTED.

The value of this property is used as claim_types_supported property in the OpenID Provider Metadata.

supportedClaims string array

Claim names that the service supports. The standard claim names listed in OpenID Connect Core 1.0, 5.1. Standard Claim should be supported. The following is the list of standard claims.

  1. sub
  2. name
  3. given_name
  4. family_name
  5. middle_name
  6. nickname
  7. preferred_username
  8. profile
  9. picture
  10. website
  11. email
  12. email_verified
  13. gender
  14. birthdate
  15. zoneinfo
  16. locale
  17. phone_number
  18. phone_number_verified
  19. address
  20. updated_at

The value of this property is used as claims_supported property in the OpenID Provider Metadata.

The service may support its original claim names. See OpenID Connect Core 1.0, 5.1.2. Additional Claims. Note that Authlete requires that original claim names consist of only ASCII letters and its length not exceed 200.

serviceDocumentation URL

The URL of a page where documents for developers can be found.

The value of this property is used as service_documentation property in the OpenID Provider Metadata.

supportedClaimLocales string array

Claim locales that the service supports. Each element is a language tag defined in RFC 5646. For example, "en-US" and "ja-JP". Authlete requires that each language tag consist of only ASCII letters and its length not exceed 30. See OpenID Connect Core 1.0, 5.2. Languages and Scripts for details.

The value of this property is used as claims_locales_supported property in the OpenID Provider Metadata.

supportedUiLocales string array

UI locales that the service supports. Each element is a language tag defined in RFC 5646. For example, "en-US" and "ja-JP". Authlete requires that each language tag consist of only ASCII letters and its length not exceed 30.

The value of this property is used as ui_locales_supported property in the OpenID Provider Metadata.

policyUri URL

The URL of the "Policy" of the service. Authlete requires that the URL consist of only ASCII letters and its length not exceed 200.

The value of this property is used as op_policy_uri property in the OpenID Provider Metadata.

tosUri URL

The URL of the "Terms Of Service" of the service. Authlete requires that the URL consist of only ASCII letters and its length not exceed 200.

The value of this property is used as op_tos_uri property in the OpenID Provider Metadata.

authenticationCallbackEndpoint URL

A Web API endpoint for user authentication which is to be prepared on the service side. It must consist of only ASCII characters and its length must not exceed 200.

The endpoint must be implemented if you do not implement the UI at the authorization endpoint but use the one provided by Authlete. The user authentication at the authorization endpoint provided by Authlete is performed by making a POST request to this endpoint.

See 'Authentication Callback' for details.

authenticationCallbackApiKey string

API key for Basic authentication at the authentication callback endpoint. It must consist of only ASCII characters and its length must not exceed 100.

If the value is not empty, Authlete generates Authorization header for Basic authentication when making a request to the authentication callback endpoint.

authenticationCallbackApiSecret string

API secret for Basic authentication at the authentication callback endpoint. It must consist of only ASCII characters and its length must not exceed 100.

supportedSnses string

SNSes you want to support 'social login' in the UI at the authorization endpoint provided by Authlete. You need to register a client application in each SNS that is set to this parameter and set Authlete server's /api/sns/redirection as the redirection endpoint of the client application.

snsCredentials string

SNS credentials which Authlete uses to make requests to SNSes. The format is JSON.

createdAt i64

The time at which this service was created. The value is represented as milliseconds since the UNIX epoch (1970-01-01).

modifiedAt i64

The time at which this service was last modified. The value is represented as milliseconds since the UNIX epoch (1970-01-01).

developerAuthenticationCallbackEndpoint URL

A Web API endpoint for developer authentication which is to be prepared on the server side. It must consist of only ASCII characters and its length must not exceed 200.

The endpoint must be implemented if you use Developer Console. The developer authentication at the login page of Developer Console is performed by making a POST request to this endpoint.

See 'Developer Authentication Callback' for details.

developerAuthenticationCallbackApiKey string

API key for Basic authentication at the developer authentication callback endpoint. It must consist of only ASCII characters and its length must not exceed 100.

If the value is not empty, Authlete generates Authorization header for Basic authentication when making a request to the developer authentication callback endpoint.

developerAuthenticationCallbackApiSecret string

API secret for Basic authentication at the developer authentication callback endpoint. It must consist of only ASCII characters and its length must not exceed 100.

supportedDeveloperSnses string

SNSes you want to support 'social login' in the login page of Developer Console provided by Authlete. You need to register a client application in each SNS checked here and set Authlete server's /api/developer/sns/redirection as the redirection endpoint of the client application.

developerSnsCredentials string

SNS credentials which Authlete uses to make requests to SNSes. The format is JSON.

clientsPerDeveloper i32

The maximum number of client applications that a developer is allowed to create. 0 means no limit.

directAuthorizationEndpointEnabled boolean

The flag to indicate whether the direct authorization endpoint is enabled or not.

If true, the default implementation of the authorization endpoint of this service works. The URL of the endpoint is https://api.authlete.com/api/auth/authorization/direct/service-api-key.

If false, the endpoint returns 404 Not Found. In this case, you have to implement the authorization endpoint by yourself using Authlete's Web APIs such as /api/auth/authorization, /api/auth/authorization/issue and /api/auth/authorization/fail.

directTokenEndpointEnabled boolean

The flag to indicate whether the direct token endpoint is enabled or not.

If true, the default implementation of the token endpoint of this service works. The URL of the endpoint is https://api.authlete.com/api/auth/token/direct/service-api-key.

If false, the endpoint returns 404 Not Found. In this case, you have to implement the token endpoint by yourself using Authlete's Web APIs such as /api/auth/token, /api/auth/token/issue and /api/auth/token/fail.

directRevocationEndpointEnabled boolean

The flag to indicate whether the direct revocation endpoint is enabled or not.

If true, the default implementation of the revocation endpoint (RFC 7009) of this service works. The URL of the endpoint is https://api.authlete.com/api/auth/revocation/direct/service-api-key.

If false, the endpoint returns 404 Not Found. In this case, if you want to provide a revocation endpoint to client applications, you have to implement the endpoint by yourself using Authlete's /api/auth/revocation API.

directUserInfoEndpointEnabled boolean

The flag to indicate whether the direct userinfo endpoint is enabled or not.

If true, the default implementation of the userinfo endpoint of this service works. The URL of the endpoint is https://api.authlete.com/api/auth/userinfo/direct/service-api-key.

If false, the endpoint returns 404 Not Found. In this case, if you want to provide a userinfo endpoint to client applications, you have to implement the endpoint by yourself using Authlete's /api/auth/userinfo API.

This feature is not implemented yet.

directJwksEndpointEnabled boolean

The flag to indicate whether the direct jwks endpoint is enabled or not.

If true, the default implementation of the JWK Set endpoint of this service works. The URL of the endpoint is https://api.authlete.com/api/service/jwks/get/direct/service-api-key.

If false, the endpoint returns 404 Not Found. In this case, if you want to provide a JWK Set endpoint to client applications, you have to implement the endpoint by yourself using Authlete's /api/service/jwks/get API.

singleAccessTokenPerSubject boolean

The flag to indicate whether the number of access tokens per subject (and per client) is at most one or can be more.

If true, an attempt to issue a new access token invalidates existing access tokens that are associated with the same subject and the same client.

Note that, however, attempts by Client Credentials Flow do not invalidate existing access tokens because access tokens issued by Client Credentials Flow are not associated with any end-user's subject. Also note that an attempt by Refresh Token Flow invalidates the coupled access token only and this invalidation is always performed regardless of whether the value of this setting item is true or false.

pkceRequired boolean

The flag to indicate whether the use of Proof Key for Code Exchange (PKCE) is always required for authorization requests by Authorization Code Flow.

If true, code_challenge request parameter is always required for authorization requests using Authorization Code Flow.

See RFC 7636 (Proof Key for Code Exchange by OAuth Public Clients) for details about code_challenge request parameter.

refreshTokenKept boolean

The flag to indicate whether a refresh token remains unchanged or gets renewed after its use.

If true, a refresh token used to get a new access token remains valid after its use. Otherwise, if false, a refresh token is invalidated after its use and a new refresh token is issued.

See RFC 6749 6. Refreshing an Access Token, as to how to get a new access token using a refresh token.

description string

The description about the service. It consists of at most 200 unicode letters.

accessTokenType string

The access token type. This value is used as the value of token_type property in access token responses. If this service complies with RFC 6750, the value of this property should be Bearer.

See RFC 6749 (OAuth 2.0), 7.1. Access Token Types for details.

accessTokenDuration i32

The duration of access tokens in seconds. This value is used as the value of expires_in property in access token responses. expires_in is defined RFC 6749, 5.1. Successful Response.

refreshTokenDuration i32

The duration of refresh tokens in seconds. The related specifications have no requirements on refresh token duration, but Authlete sets expiration for refresh tokens.

idTokenDuration i32

The duration of ID tokens in seconds. This value is used to calculate the value of exp claim in an ID token.

properties Array of string[2]

The extra properties associated with the service. The content of the returned array depends on contexts. The type is an array of string[2]. string[0] is a key and string[1] is its value. null may be returned. The predefined service properties are show below.

Key Description
clientCount

The number of client applications which belong to this service.

Subject Type

The listed below are Authlete's constant values that correspond to the subject identifier types described in OpenID Connect Core 1.0, 8. Subject Identifier Types.

  • PUBLIC
  • PAIRWISE

Note that currently Authlete's implementation for PAIRWISE is not finished, so PAIRWISE behaves in the same way as PUBLIC.

Tagged Value

TaggedValue is a generic-purpose data structure to describe a pair of a language tag and a string. This data structure has two members, tag and value as described in the table below.

Name Type Description
tag string

The language tag part. It must consist of only ASCII letters. Its length must not exceed 30.

value string

The value part. It is a unicode string, but some client properties put more restrictive limitations such as "ASCII only". Its length must not exceed 200.

Some properties of Client such as clientNames and logoUris are represented in this data structure. See OpenID Connect Core 1.0, 5.2. Claims Languages and Scripts for the usage of language tags in OpenID Connect.

Property

Property that consists of a string key and a string value.

This data type is used mainly to represent an extra property that is associated with an access token. Some Authlete APIs (such as /api/auth/token API) accept an array of properties via properties request parameter and associate the properties with an access token.

Name Type Description
key string

The key part.

value string

The value part.

hidden string

The flag to indicate whether this property hidden from or visible to client applications.

If true, this property is hidden from client applications. Otherwise, this property is visible to client applications.

See Extra Properties for details.