Direct authorisation

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.

This can be useful in the following situations:

To federate logins from social sites like Facebook, Twitter and Google Plus. This can be implemented by a broker acting as a client application to the external Identity Provider (IdP). Upon successful login with the external IdP the broker invokes the direct authorisation API to create a local ID / access token and a SSO session with the Connect2id server.
To federate identities from partner organisations. The external identities can be conveyed by a SAML, an OpenID Connect ID token, a JWT or some other assertion.
To obtain impersonated ID, access and / or refresh tokens.

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 start a new SSO session for the end-user.

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

Header parameters:

Authorization Must specify the configured bearer access token for this web API.
Content-Type Must be set to application/json.

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 the client application with 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"       : "g6f5K6Kf6EY11zC00errCf64yLtg9lLANAcnXQk2xUE"
}

4. Representations

4.1 Direct authorisation request

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

If a subject (end-user) is specified (using 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 (using the sub_session parameter), or to reference an already 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 identifier of the client application.
scope {string array} The authorised OAuth 2.0 scope values.
[ audience ] {string array} Optional parameter specifying an explicit audience for the issued access token. The audience should be represented as one or more client identifiers.
[ claims ] {string array} The names of the consented OpenID Connect 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 Connect claims transport, defaults to USERINFO. If set to USERINFO the claims will be made available at the UserInfo endpoint by presenting the access token. If set to 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 identifies a long-lived authorisation that is persisted and may optionally allow issue of a refresh token. If false the authorisation is transient and will be deleted as soon as the access token associated with it expires. 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 omitted defaults to self-contained (JWT-encoded).
- [ encrypt = false ] {true|false} Encryption flag. Applies only to self-contained (JWT-encoded) access tokens. If true the JWT will be encrypted with a shared AES key after signing for confidentiality.
[ id_token ] {object} Optional ID token settings, overriding the default configuration:
- [ lifetime = 0 ] {integer} The ID token lifetime in seconds. If zero or omitted defaults to the configured ID token lifetime.
- [ ~~impersonated_sub~~ ] {string} Deprecated, use the top-level impersonated_sub parameter instead.
[ refresh_token ] {object} Optional refresh token settings:
- [ issue = true ] {true|false} Enables / disable refresh token issue. Applies only to long-lived (persisted) authorisations. If true a refresh token will be issued along with the access token. If false no access token will be issued. Defaults to true if omitted.
- [ lifetime = 0 ] {integer} The refresh token lifetime in seconds. If zero or omitted defaults to permanent (no expiration). If a client tries to refresh an access token and the refresh token has expired, 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 authentication 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 for client application 8cc2043 and for the subject (end-user) with the specified session identifier (sub_sid):

{
  "sub_sid"          : "g6f5K6Kf6EY11zC00errCf64yLtg9lLANAcnXQk2xUE",
  "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 for client application 8cc2043 and for subject (end-user) alice (creating a new SSO session for her):

{
  "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 for client application 8cc2043 where the subject admin impersonates the identity of alice (while creating a new SSO session for admin):

{
  "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 application!

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"
}