API authentication and authorization

This REST API is secured with JSON Web Token (JWT) authentication RFC7519. It is assumed that the clients of this API are capable of issuing valid JWT tokens.

JWT tokens can be obtained by requesting them from an Identity Provider (such as Keycloak) or created manually. In both cases, the public key to be used for the signature verification has to be provisioned in Risk Management.

If no Identity Provider is available, then the following section describes how to generate a key pair that you can use to issue and verify JWT tokens.

API authentication

Only the JWTs signed with algorithms "ES256" or "PS256" are supported. See JSON Web Algorithms (JWA) RFC7518.

The JWT security is limited to asymmetric cryptography algorithms, to avoid storing shared secrets in the back-end server. As a result, the back end only stores the public keys used to verify the signature of the tokens.

JWT header signature algorithms

The following are the supported JWT header signature algorithms:

API authorization

Every resource of the API is protected. To gain access to it, a valid JWT must be sent along with the HTTP request in the authorization header using the bearer schema:

Authorization: Bearer <Base64_Encoded_JWT>

A JWT consists of three parts separated by dots (.):

• Header
• Payload
• Signature

Therefore, a JWT typically looks like the following: hhhhhhh.pppppppp.ssssssssss

JWT header

The header part contains the algorithm to use and the type of token to generate.

'KID' could be used to determine the correct key among multiple public keys from the same issuer.

Header example

{
 "alg": "ES256",
 "typ": "JWT",
 "kid" : "your_tenant_key"
}

JWT payload

The payload can contain the following fields:

{
    "properties": {
        "exp": {
            "description": "The token expiration time in number of seconds since Jan 1, 1970 (Epoch Time). **Maximum value** is current date/time +15 minutes.",
            "type": "string"
        },
        "roles": {
            "description": "The name of the role required to access Risk Management is 'tenant-oper'.
            "items": {
                "type": "string"
            },
            "type": "array"
        },
        "jti": {
            "description": "Part of audit if provided",
            "type": "string"
        },
        "iss": {
            "description": "Issuer of the key\n\nThis identifies the principal who issues the JWT.\n\n**WARNING**: ISS is used to look up the enrolled Public Key in Risk Management.",
            "type": "string"
        },
        "sub": {
            "description": "By default this field is used for identifying the authorized entity and will be used for internal audits.",
            "type": "string"
        }
    },
    "required": [
        "iss",
        "sub",
        "exp",
        "roles"
    ],
    "type": "object"
}

JWT expiration notes

The exp value is checked against the configurable maximum expiration period. By default, the maximum expiration period is set to 15 minutes for every tenant and represents the maximum expiration time accepted by the solution. If the JWT exp value exceeds the maximum expiration period, the JWT is automatically considered invalid and the request becomes unauthenticated.

The expiration value can be extended for testing purposes. For more information, contact your Thales representative.

Payload example

{
    "iss": "your_tenant_name",
    "sub": "your_user_for_audit",
    "jti": "27ae069f-05ce-4f85-a083-dfcc19794029",
    "roles": ["tenant-oper"],
    "exp": "1545222654"
}

JWT signature

The JWT signature is a cryptographic hash of both the header and the payload.

These parts are Base64URL encoded and concatenated, separated by single dots ('.').

How to generate a JWT

You can use the openssh tool to generate an ECDSA key pair, or an ssh tool to generate an RSA key pair.

Example for ES256 signatures

• Generate the private key that MUST be securely protected in your environment.

  > openssl ecparam -name prime256v1 -genkey -noout -out key
  

• Generate the public key that MUST be configured in Risk Management.

  > openssl ec -in key -pubout -out key.pem
  

Example for RS256 signatures

• Generate the private key that MUST be securely protected in your environment.

  > ssh-keygen -f key -m PEM -t rsa -b 2048
  

• Generate Public Key that MUST be configured in Risk Management.

  > ssh-keygen -f key.pub -e -m >> pkcs8.pub
  

The generated private key is used to sign the JWTs on the client side, and the generated public key is provisioned into the back end to verify the signature of those JWTs (provided to Thales via the Tenant Onboarding form).

There are many tools available to help with JWT generation.

Here is an example of how to generate it using the tiny NodeJS library:

// include the lib in your project
const jwt = require('jsonwebtoken');


// TODO: Use your own private Key
const privateKey = `-----BEGIN EC PRIVATE KEY-----
MHcCAQEEIAdzUULxYnLKmzLcB4iIdW0613oQU9dfmALDUErBSLw2oAoGCCqGSM49
AwEHoUQDQgAEVYr3+kEECZIymybUzRqPE+p5lApcFbjZazUzQI+fW5qHW6YvZXXN
DU4RDQqpckGUQcKOtSu40ogem1QxomJVLw==
-----END EC PRIVATE KEY-----
`;

// prepare the payload, with your tenantID and the appropriate role
const payload = {
 jti: "27ae069f-05ce-4f85-a083-dfcc19794029",
 roles: ["tenant-oper"]
};

// set some options, containing the reserved claims, the algorithm to use…
const options = {
 algorithm: 'ES256',
 issuer: "your_tenant_name",
 expiresIn:  "5 min",
 subject:  "your_user_for_audit",
};

// and let sign… in one line your token is generated
const token = jwt.sign(payload, privateKey, options);
console.info(token);

Example output

eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImRldnBvcnRhbCJ9.eyJqdGkiOiIyN2FlMDY5Zi0wNWNlLTRmODUtYTA4My1kZmNjMTk3OTQwMjkxNjM0MTEzOTI2MDY3Iiwicm9sZXMiOlsic2NzOmV4ZWN1dGVTY2VuYXJpbyJdLCJpYXQiOjE2MzQxMTM5MjYsImV4cCI6MTYzNDExNDIyNiwiaXNzIjoieW91cl90ZW5hbnRfbmFtZSIsInN1YiI6InlvdXJfdXNlcl9mb3JfYXVkaXQifQ.MlUZ18rYcQnRUe2mSNW_J7O6ETzGgDClvQ7VJhjKdTNC9qO5MoKz6McfZw14aTFOZFvFtGYide2MA6vXkjltjQ