Authentication

ActivID CMS implements a subset of the OAuth 2.0 protocol.

For more information on OAuth 2.0, see https://oauth.net/2/

Access Token Request

The REST URL to get a new authentication token is: /aims/rs/authn/token.

Reference: RFC 6749

The client requests an access token with a JSON Web Token (JWT) bearer grant type:

  • grant_type: urn:ietf:params:oauth:grant-type:jwt-bearer

  • assertion: the JWT, signed with the operator’s private key

  • scope: openid

    • openid tells the server this is an OpenID request, thus it should respond with an id_token

The JWT is signed with the private key corresponding to the certificate enrolled for the operator. Please refer to RFC 7515 for details on the JSON Web Signature (JWS). See also the JWT header field kid described below.

The signed JWT is crafted by the client. Please refer to RFC 7519 for details about the JSON Web Token (JWT).

Example:

Copy 
POST /aims/rs/authn/token HTTP/1.1
Host: cms.mycompany.com
Content-Type: application/x-www-form-urlencoded
 
grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer
&assertion=eyJhbGciOiJFUzI1NiIsImtpZCI6IjE2In0.
eyJpc3Mi[...omitted for brevity...].
J9l-ZhwP[...omitted for brevity...]
&scope=openid

The signed JWT must have the following claims:

  • iss: unique identifier of the entity that issued the JWT (client specific)

  • sub: the operator username

  • aud: the authorization server URL; that is, the ActivID CMS server URL

  • exp: expiry date of the JWT (currently unbounded)

    Note: ActivID CMS does not enforce any expiration policy but it is recommended to keep the validity window short (less than 5 minutes).

  • nbf: date after which the JWT can be used (optional; by default, “now”)

    Note: ActivID CMS honors nbf if it is set; if the authentication time is before the time set by nbf, the authentication is refused.

  • jti: unique identifier of the token; decimal representation of a random 32-bit integer used as nonce to prevent replay attacks

Any other claim is ignored.

Example:

Copy 
{
  "iss":"https://cmsclient.mycompany.com",
  "sub":"operator1",
  "aud":"https://cms.mycompany.com",
  "nbf":1300818380,
  "exp":1300819380,
  "jti":"840258026"
}

The JWT header has a field to identify the key and the signature algorithm of the signed JWT:

  • alg: the signature algorithm. It depends on the key type (RSA or ECC) and must be one of the following algorithms:

  • ES256 (ECDSA using P-256 and SHA-256)

  • ES384 (ECDSA using P-384 and SHA-384)

  • ES512 (ECDSA using P-512 and SHA-512)

  • PS256 (RSASSA-PSS using SHA-256 and MGF1 with SHA-256)

  • PS384 (RSASSA-PSS using SHA-384 and MGF1 with SHA-384)

  • PS512 (RSASSA-PSS using SHA-512 and MGF1 with SHA-512)

Example:

Copy 
{"alg":"ES256"}

If the authentication process succeeds, the returned response has the status 200 and contains the access token with the following data:

  • access_token: the token that must be sent to subsequent queries (for example, the Operator API) for authorization

  • expires_in: the validity period (in seconds)

  • token_type: the token type, always Bearer

Example:

Copy 
{
  "access_token":"45ghiukldjahdnhzdauz",
  "expires_in":600,
  "token_type":"Bearer"
}

Subsequent REST Representational State Transfer queries using that token must have the following HTTP header:

Copy 
Authorization: Bearer 45ghiukldjahdnhzdauz

If the authentication process fails, then the HTTP status code is 400 (see https://tools.ietf.org/html/rfc6749#section-5.2) and the payload is a JSON document with the following parameters:

  • error: one of the following error codes:

    • invalid_request: The request is missing a required parameter, includes an unsupported parameter value (other than grant type), repeats a parameter, includes multiple credentials, utilizes more than one mechanism for authenticating the client, or is otherwise malformed.

    • invalid_scope: The requested scope is invalid, unknown, or malformed.

    • invalid_grant: The provided authorization grant (for example, authorization code, resource owner credentials) or refresh token is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client.

    • unsupported_grant_type: The authorization grant type is not supported by the authorization server.

  • error_description: a human-readable description of the error code

Example:

Copy 
HTTP/1.1 400
{"error_description":"Invalid grant","error":"invalid_grant"}

Revoke Token Request

The REST URL to revoke an authentication token is: /aims/rs/authn/revoke.

Reference: RFC 7009

The client provides the access token that they want to be revoked.

Example:

Copy 
POST /aims/rs/authn/revoke HTTP/1.1
Host: cms.mycompany.com
Content-Type: application/x-www-form-urlencoded
token=45ghiukldjahdnhzdauz

The entry point invalidates the JWT access token.

The returned HTTP status is always 204 and the page is blank.