Purpose and requirements

1. Access tokens generation in JWT format is implemented to reduce load of mithril service, that exists on any call to eHealth API that uses Authorization header with access token.

2. Only access tokens that are used to obtain access to eHealth endpoints (i.e. Create/Update Person Request, Create Declaration Request, Get Person Verification Details etc) can be used in JWT format. Any other tokens that are used in OAuth flow (i.e. authorization_code, refresh_token, session_token) are still generated in existing format.

3. Access token generation format is controlled by a configuration parameter - ACCESS_TOKEN_JWT.

4. Existing access token generation format validation must be active and operational.

5. Access token in JWT format contains only user and client related data, broker data is still validated with api-key validation through Mithril service using existing process, described here MIS authorization

6. Access tokens in JWT format are not saved to mithril database, as they are only validated on Kong service side.

Implementation

Access token in JWT format generation

Following methods that are used to generate access token for user:

Exchange oAuth Code Grant to Access Token

https://e-health-ua.atlassian.net/wiki/spaces/PCAB/pages/17415667759

https://e-health-ua.atlassian.net/wiki/spaces/PCAB/pages/17415798881

https://e-health-ua.atlassian.net/wiki/spaces/PCAB/pages/17415340883

https://e-health-ua.atlassian.net/wiki/spaces/PCAB/pages/17416060933

Methods check value of ACCESS_TOKEN_JWT configuration parameter:

• true - access tokens for users are generated in JWT format;

• false - access tokens for users are generated in opaque format (hashed string of record from mithril database, tokens table).

Methods responses for generated token are not changed, token is still returned in value field.

JWT structure

Access token in JWT format consist of three base64 encoded strings that are separated by dot symbol:

• Header

• Payload

• Signature

Header

JWT header contains following fields:

Mithril service uses RS512 JWT signature algorithm with JWT token type.

Payload

JWT payload contains following fields:

Mithril service forms payload field based on data that is used for token generation (user_id, client_id, requested scope list, session token, etc).

Signature

JWT signature contains signature of token content using algorithm described in alg field from header.

Mithril service uses asymmetric signature algorithm – token content is signed using private key stored in JWT_PRIVATE_KEY parameter.

Access tokens in JWT format validation

Access token in JWT format must be submitted to the same Authorization header for any method that required access token.

Access tokens in JWT format are validated only by Kong service, if all token validations are passed – scope list from scope field is used to validate access to requested endpoint.

JWT is validated by following steps:

1. Validate Authorization header format

   1. in case token parses as JWT – validate it as JWT

   2. else – validate it using existing token format validation (by token verify mithril method)

2. Verify JWT signature with public key stored in JWT_PUBLIC_KEY and JWT_PUBLIC_KEY_OLD parameters

   1. in case JWT signature is not verified by stored public key - return 401 ('access_denied')

3. Check token expiry date from exp field is greater then now()

   1. in case exp field does not exist or expiry date is in the past - return 401 ('access_denied')

4. Check token issuer from iss field equals to ‘EHeath’ value

   1. in case iss field does not exist or contains any other data - return 401 ('access_denied')

5. Check token audience from aud field equals to ‘EHealth’ value

   1. in case aud field does not exist or contains any other data - return 401 ('access_denied')

6. Check token is not blacklisted in Redis cache database by values of fields from payload (jti, sub, client_id):

   1. check key blacklist_jti_<<jti>> does not exist (for example, blacklist_jti_481aa86b-7bfa-462c-8bcb-1a9e9edff192);

   2. check key blacklist_user_id_<<sub>> does not exist (for example, blacklist_user_id_481aa86b-7bfa-462c-8bcb-1a9e9edff192);

   3. check key blacklist_client_id_<<client_id>> does not exist (for example, blacklist_client_id_8a99ffdf-314e-4419-931d-a76f41f8c456);

   4. check key blacklist_user_id_client_id_<<sub>>_<<client_id>> does not exist (for example, blacklist_user_id_client_id_481aa86b-7bfa-462c-8bcb-1a9e9edff192_8a99ffdf-314e-4419-931d-a76f41f8c456);

   5. check key blacklist_app_id_<<app_id>> does not exist (for example, blacklist_app_id_ce21628e-317b-4edb-bda6-0de661f24666);

      1. in case any of the keys exist in Redis cache database - return 401 ('access_denied')