Authentication

The Core API relies on a third-party Identity Service Provider (IDP) in order to authenticate and authorize. The IDP must support:

• OpenID-Connect for authentication
• OAuth2.0 for authorization

The API uses JSON Web Tokens (JWT) to provide stateless identification.

The Core API can also be run in an 'anonymous' mode, disabling all forms of authentication and authorization. This can be useful for fully on-premise operation or for local test and evaluation.

To use the Core API, a JWT must first be requested from the IDP, which will then be used for every subsequent request.

A POST request is sent to the IDP with the relevant realm (as defined in the IDP), containing the client or user credentials (depending on whether the request is made from a real user or a client account).

POST https://my-idp.domain.com/auth/realms/eurovox/protocol/openid-connect/token`

With the request header parameter:

Content-Type:application/x-www-form-urlencoded 

And the request body for a client account:

client_id:my-client-to-access-core-layer
client_secret:secret-1234-5678
grant_type:client_credentials
scope:CoreLayer.Access

or for a user account:

username:user_1@domain.com
password:strong-password
grant_type:password
scope:CoreLayer.Access

The IDP will then send the JWT in the response

{
    "access_token": "eyJhbGciOiJS...RWUA",
    "expires_in": 300,
    "refresh_expires_in": 1800,
    "refresh_token": "eyJhbGci...16YPk",
    "token_type": "bearer",
    "scope": "CoreLayer.Access"
}

Indicating the expiration of the token, and also a refresh_token which can be used to refresh the token just before it expires.

The token itself is then used in all subsequent requests to the Core API, by including it in the request header

Authorization:Bearer eyJhbGciOiJS...RWUA