Authentication and authorisation

Introduction

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 may 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 the IdCloud.

In the case where no Identity Provider is available, then the following section describes how to generate a key pair that can be used to issue and verify JWT tokens.

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 in order 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.

Currently supported JWT header signature algorithms

Authorisation

Every resource of the API is protected. In order to gain access to it, a valid JWT has to be sent along with the HTTP request in the Authorisation 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

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

Payload

The Payload can contain the following fields:

```json json_schema { "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 IFP 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\nWARNING: ISS is used to look up the enrolled Public Key in IdCloud.", "type": "string" }, "sub": { "description": "By default this field is used for identifying the authorised entity and will be used for internal audits.", "type": "string" } }, "required": [ "iss", "sub", "exp", "roles" ], "type": "object" }

<!-- theme: info -->
>### JWT Expiration Notes
> The exp value is checked against configurable maximum expiration period. The maximum expiration period is by default 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, please contact your Thales representative.
 >

### Payload example

<!--
title: ""
lineNumbers: true
-->
```json
{
    "iss": "your_tenant_name",
    "sub": "your_user_for_audit",
    "jti": "27ae069f-05ce-4f85-a083-dfcc19794029",
    "roles": ["tenant-oper"],
    "exp": "1545222654"
}

JWT signature

A cryptographic hash of both the header and the payload.

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

How to generate JWT

You may use the openssh tool to generate an ECDSA key pair or ssh tool to generate 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 Public Key that MUST be configured in IdCloud.

> 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 IdCloud.

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

The generated private key will be used to sign the JWTs on the client side and the generated public key will be provisioned into the back-end to verify the signature of those JWTs (will be provided to Thales via Tenant Onboarding form). * There are many tools available to help with JWT generation. * Here is an example of how to generate it using 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