Direct authorisation

1. Overview

The Connect2id server provides a special protected web interface for obtaining ID, access and / or refresh tokens directly. The standard OAuth authorisation and token endpoints are not involved and end-user interaction is not required.

Access to the direct authorisation API is protected with a long-lived bearer token. The token must be passed with each HTTP request in the Authorization header:

Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6

Additional details are found in the authorisation configuration reference.

2. Web API overview

Resources
direct-authz/rest/v2 [POST]
Representations	Errors
Direct authorisation request Direct authorisation response	400 Bad Request 401 Unauthorized 404 Not Found 460 Invalid Client ID 461 Invalid / Expired Subject Session ID 462 Missing / Expired Client Secret 500 Internal Server Error

3. Resources

3.1 direct-authz/rest/v2

3.1.1 POST

Creates a new direct authorisation with the Connect2id server. Can optionally create a new subject session for the end-user.

Returns the requested ID, access and / or refresh token, to be passed to the authorised client.

Header parameters:

Authorization Must specify the configured bearer access token for this web API.
Content-Type Must be set to application/json.
[ Issuer ] The issuer URL when issuer aliases are configured, or the issuer URL for a tenant (in the multi-tenant Connect2id server edition). The tenant can be alternatively specified by the Tenant-ID header.
[ Tenant-ID ] The tenant ID (in the multi-tenant Connect2id server edition). The tenant can be alternatively specified by the Issuer header.

Body:

A JSON object representation of a direct authorisation request.

Success:

Code: 200
Content-Type: application/json
Body: {object} A JSON object representation of a direct authorisation response containing the ID / access / refresh token and the subject (end-user) session identifier.

Errors:

400 Bad Request
401 Unauthorized
460 Invalid Client ID
461 Invalid / Expired Subject Session ID
462 Missing / Expired Client Secret
500 Internal Server Error

Example request for an ID, access and refresh token for the subject (end-user) alice and client ID 8cc2043:

POST direct-authz/rest/v2 HTTP/1.1
Host: c2id.com
Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6
Content-Type: application/json

{
  "sub_session" : { "sub" : "alice" },
  "client_id"   : "8cc2043",
  "scope"       : [ "openid", "email", "profile", "app:admin" ],
  "claims"      : [ "name", "email", "email_verified" ]
}

Example response containing the requested tokens, also returning the identifier of the subject session (SID) that was created with the Connect2id server (sid):

HTTP/1.1 200 OK
Content-Type: application/json

{
  "access_token"  : "vJkbPNUFaK4kVIMGQlEmyA.-MAquq_5yQqtae62b8i7aw",
  "token_type"    : "Bearer",
  "expires_in"    : 3600,
  "refresh_token" : "YWxpY2U.NjU1NjRlYjAwNThk._W--XjP0UDZDiDYPkd4E_Q",
  "scope"         : "openid email profile app:admin",
  "sub_sid"       : "WYqFXK7Q4HFnJv0hiT3Fgw.-oVkvSXgalUuMQDfEsh1lw"
}

4. Representations

4.1 Direct authorisation request

Specifies a direct authorisation request for the specified subject (end-user) and client.

If a subject (end-user) is specified (with the sub parameter) and no additional session information is provided (the sub_session and sub_sid parameters are omitted) the request is for an access / refresh token only.

To obtain an OpenID Connect ID token the request must specify a new subject (end-user) session to be created (with the sub_session parameter), or to reference a valid existing subject session (with the sub_sid parameter).

The request must also at a minimum specify one or more scope values (scope). The remaining parameters are optional or have default values.

Impersonated ID, access and / or refresh tokens can also be requested.

JSON object members:

sub {string} The authorised subject (end-user). With this parameter only an access token and optionally a refresh token (see issue_refresh_token) can be obtained. Must not be used together with sub_session or sub_sid.
sub_session {object} The details of the subject (end-user) session to create. This parameter is required to obtain an ID token. Must not be used together with sub or sub_sid.
sub_sid {string} The identifier of an existing session (SID) for the subject (end-user). This parameter is required to obtain an ID token. Must not be used together with sub or sub_session.
client_id {string} The client identifier.
[ scope ] {string array} The authorised OAuth 2.0 scope values. May be omitted or empty, for example for a Rich Authorisation Request (RAR).
[ audience ] {string array} Optional parameter specifying the resource server audience for the issued access token. Should typically include the client_id(s) of the resource(s), but any other types of identifier, such as URI, is also accepted. Identifier-based tokens with a specified audience can be introspected only by resource servers whose client_id is in the audience.
[ claims ] {string array} The names of the consented OpenID claims, with optional language tags (BCP47).
[ claims_locales ] {string array} The end-user’s preferred claims locales, by order of preference, omitted if not specified.
[ claims_transport = “USERINFO” ] {“USERINFO”|“ID_TOKEN”} The preferred OpenID claims transport, defaults to USERINFO. If USERINFO the claims will be made available at the UserInfo endpoint by presenting the access token. If ID_TOKEN the claims will be included in the ID token.
[ claims_data ] {object} Optional data to be passed in the request to retrieve the consented OpenID claims from the configured source(s). The claims data will be included in a “cld” (claims data) field in the issued access token(s) and in the long-lived authorisations if the consent is persisted. If the claims data must be kept confidential from the client either an identifier access token encoding must be chosen or if a self-contained (JWT) access token is chosen it must be additionally encrypted. An AdvancedClaimsSource SPI implementation can retrieve the claims data JSON object by a call to the ClaimsSourceRequestContext.getClaimsData method. Since v14.0.
[ preset_claims ] {object} Optional JSON object specifying additional preset OpenID Connect claims to include in the ID token and / or the UserInfo response:
- [ id_token ] Preset claims to include in the ID token, omitted or empty JSON object if none.
- [ userinfo ] Preset claims to include in the UserInfo response, omitted or empty JSON object if none.
[ long_lived = true ] {true|false} Long-lived authorisation flag. If true indicates a long-lived (persisted) authorisation. If false the authorisation is transient (not remembered). Defaults to true.
[ impersonated_sub ] {string} Specifies a subject (end-user) to impersonate by means of the issued ID, access token and refresh token. May be used to enable privileged users to login into a client or access protected resources under a different identity. The actual authorised subject (the impersonator) will be indicated in the custom act.sub ID and JWT access token claim.
[ access_token ] {object} Optional access token settings, overriding the default configuration:
- [ lifetime = 0 ] {integer} The access token lifetime in seconds. If zero or omitted the default setting will apply.
- [ encoding = “SELF_CONTAINED” ] {“SELF_CONTAINED”|“IDENTIFIER”} The access token encoding. If the token authorisation is encoded in the access token, as a signed and optionally encrypted JSON Web Token (JWT). If IDENTIFIER the issued access token is a secure identifier; the token authorisation can be looked up by making an introspection call. Defaults to SELF_CONTAINED.
- [ encrypt = false ] {true|false} Encryption of the self-contained (JWT) access token after signing, to make its payload confidential from the client. The token is encrypted with the current active AES key using the configured JWE algorithm and method. The resource server(s) must be provisioned with a copy of the AES key to decrypt the token. Defaults to false, unless the client is an OpenID relying party registered for pairwise subjects in which case the token will be encrypted. The encryption can be opted out from if the access token subject is set to pairwise.
- [ sub_type = PUBLIC ] {PUBLIC|PAIRWISE} The access token subject type. If PAIRWISE the access token with be issued with a pairwise subject identifier. This requires the audience to be set (if multiple audience values are set the first in the list will used to compute the pairwise identifier). Defaults to PUBLIC.
[ id_token ] {object} Optional ID token settings, overriding the default configuration:
- [ lifetime = 0 ] {integer} The ID token lifetime in seconds. When zero or omitted the default setting will apply.
- [ allow_refresh = false ] {true|false} Allows ID token refresh at the token endpoint provided the subject (end-user) session is still present (not closed or expired). Since v14.0.
[ refresh_token ] {object} Optional refresh token settings:
- [ issue = true ] {true|false} Enables / disables refresh token issue. If true a refresh token will be issued along with the access token. If false no refresh token will be issued. Defaults to true if omitted. Note, the long_lived request parameter controls the encoding of the refresh token.
- [ lifetime ] {integer} The refresh token lifetime in seconds. Zero means no lifetime limit. When omitted the default setting will apply. If a client tries to use a refresh past its lifetime the token endpoint of the Connect2id server will return an invalid_grant error. This is a signal to the client to repeat the authorisation request.
- [ max_idle = 0 ] {integer} The refresh token maximum idle time in seconds. Zero means no idle time. If a client tries to use a refresh token invalidated due to inactivity the token endpoint of the Connect2id server will return an invalid_grant error. This is a signal to the client to repeat the authorisation request. Since v15.0.
- [ rotate ] {true|false} If true the refresh token will be rotated at each use. When omitted the default setting will apply. Since v14.0.
[ data ] {object} Optional additional information to be stored in the dat field of the authorisation record and included as dat claim in access tokens.

Example direct authorisation request to obtain an access and refresh token only:

{
  "sub"            : "alice",
  "client_id"      : "8cc2043",
  "scope"          : [ "openid", "profile", "email", "app:admin" ],
  "audience"       : [ "http://app1.example.com", "http://app2.example.com" ],
  "claims"         : [ "name", "email", "email_verified" ],
  "claims_locales" : [ "bg-BG", "en-US" ],
  "preset_claims"  : { "userinfo" : { "groups" : [ "admin", "audit" ] } },
  "long_lived"     : true,
  "refresh_token"  : { "issue" : true },
  "access_token"   : { "lifetime" : 600 }
}

Example direct authorisation request to obtain an ID, access and refresh token, referencing an existing subject (end-user) session (with sub_sid):

{
  "sub_sid"          : "WYqFXK7Q4HFnJv0hiT3Fgw.-oVkvSXgalUuMQDfEsh1lw",
  "client_id"        : "8cc2043",
  "scope"            : [ "openid", "profile", "email", "app:admin" ],
  "audience"         : [ "http://app1.example.com", "http://app2.example.com" ],
  "claims"           : [ "name", "email", "email_verified" ],
  "claims_locales"   : [ "bg-BG", "en-US" ],
  "claims_transport" : "USERINFO",
  "preset_claims"    : { "id_token" : { "login_ip"  : "185.7.248.1",
                                        "login_geo" : { "long" : "37.3956",
                                                        "lat"  : "-122.076" } },
                         "userinfo" : { "groups" : [ "admin", "audit" ] } },
  "long_lived"       : true,
  "refresh_token"    : { "issue" : true },
  "access_token"     : { "lifetime" : 600 }
}

Example direct authorisation request to obtain an ID, access and refresh token, creating a new subject (end-user) session (with sub_session):

{
  "sub_session"      : { "sub" : "alice" },
  "client_id"        : "8cc2043",
  "scope"            : [ "openid", "profile", "email", "app:admin" ],
  "audience"         : [ "http://app1.example.com", "http://app2.example.com" ],
  "claims"           : [ "name", "email", "email_verified" ],
  "claims_locales"   : [ "bg-BG", "en-US" ],
  "claims_transport" : "USERINFO",
  "preset_claims"    : { "id_token" : { "login_ip"  : "185.7.248.1",
                                        "login_geo" : { "long" : "37.3956",
                                                        "lat"  : "-122.076" } },
                         "userinfo" : { "groups" : [ "admin", "audit" ] } },
  "long_lived"       : true,
  "refresh_token"    : { "issue" : true },
  "access_token"     : { "lifetime" : 600 }
}

Example direct authorisation request to obtain an ID, access and refresh token, creating a new subject session for admin who is impersonating the identity of alice:

{
  "sub_session"      : { "sub" : "admin" },
  "client_id"        : "8cc2043",
  "scope"            : [ "openid", "email" ],
  "claims"           : [ "email", "email_verified" ],
  "long_lived"       : true,
  "impersonated_sub" : "alice",
  "refresh_token"    : { "issue" : true }
}

4.2 Direct authorisation response

Authorisation response with tokens and subject (end-user) session identifier. It can be easily converted to a standard OAuth 2.0 access token response by removing the subject session identifier (sub_sid) member, if present, from the JSON object.

JSON object members:

access_token {string} The access token.
token_type {string} The token type, always set to Bearer. See RFC 6750 for details.
expires_in {string} The access token lifetime, in seconds.
[ refresh_token ] {string} The optional refresh token.
[ id_token ] {string} The OpenID Connect ID token, if requested.
[ scope ] {string} The authorised scope.
[ sub_sid ] {string} The subject (end-user) session identifier (SID) if a new session was created. Must not be passed to the client!

Example direct authorisation response with an access token only:

{
  "access_token"  : "b15b843981cf",
  "token_type"    : "Bearer",
  "expires_in"    : 3600,
  "scope"         : "openid email profile app:write"
}

5. Errors

400 Bad Request

Invalid or malformed request.

Example:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error"             : "invalid_request",
  "error_description" : "Bad request: Invalid JSON: Unexpected token foo at position 3."
}

401 Unauthorized

The request was denied due to an invalid or missing bearer access token.

Example:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer
Content-Type: application/json

{
  "error"             : "missing_token",
  "error_description" : "Unauthorized: Missing Bearer access token"
}

460 Invalid Client ID

There is no existing client registration for the specified client_id.

Example:

HTTP/1.1 460
Content-Type: application/json

{
  "error"             : "invalid_client_id",
  "error_description" : "Invalid client ID"
}

461 Invalid / Expired Subject Session ID

There is no existing subject (end-user) session for the specified sub_sid or it has expired.

Example:

HTTP/1.1 461
Content-Type: application/json

{
  "error"             : "invalid_subject_session_id",
  "error_description" : "Invalid / expired subject session ID"
}

462 Missing / Expired Client Secret

The client secret for the specified client_id has expired or is missing.

Example:

HTTP/1.1 462
Content-Type: application/json

{
  "error"             : "expired_client_secret",
  "error_description" : "Missing / expired client secret"
}

500 Internal Server Error

An internal server error has occurred. Check the Connect2id server logs for details.

Example:

HTTP/1.1 500 Internal Server Error