Direct authorisation API

1. Introduction

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
Representations Errors

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 identifier of the tenant. The tenant can be alternatively specified by the Tenant-ID header. Applies to the multitenant edition of the Connect2id server.

  • [Tenant-ID] The tenant ID. The tenant can be alternatively specified by the Issuer header. Applies to the multitenant edition of the Connect2id server.

Body:

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:

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"  : "b15b843981cf",
  "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.

  • [ 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.

  • [ 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 = false ] {true|false} Long-lived authorisation flag. If true indicates a long-lived (persisted) authorisation. If false the authorisation is transient (not remembered). Defaults to false if not specified.

  • [ 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 defaults to the configured access token lifetime.

    • [ 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} Applies additional encryption to the issued access token (if self-contained / JWT) using JWE direct encryption ("dir") with an AES key. In order to decrypt the access token the AES key must be shared with the intended resource server(s). If the client is registered for pairwise subject identifiers the JWT will always be encrypted.

  • [ id_token ] {object} Optional ID token settings, overriding the default configuration:

  • [ 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.

    • [ lifetime ] {integer} The refresh token lifetime in seconds. Zero means permanent (no expiration). If omitted defaults to the configured refresh token lifetime. If a client tries to use an expired refresh token the token endpoint of the Connect2id server will return an invalid_grant error. This can serve as a signal to the client to repeat the authorisation request.

  • [ data ] {object} Optional additional information to be stored in the dat field of the authorisation record and self-contained (JWT-encoded) 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
Content-Type: application/json

{
  "error"             : "server_error",
  "error_description" : "Internal server error: Something bad happened",
  "stack"             : "Exception in thread...",
  "note"              : "See the server logs for additional details"
}