JWT Authentication

Introduction

oe-Cloud can use JWT(json web token) token to authenticate an user or a trusted application.

How to configure

To enable JWT authentication in oe-cloud or in applications built on oe-cloud, set the JWT_FOR_ACCESS_TOKEN environment variable to true

export JWT_FOR_ACCESS_TOKEN=true

User authentication

To use user JWT authentication, set environment variable JWT_CONFIG before starting the application

{
    "issuer": "mycompany.com",
    "audience": "mycompany.net",
    "secretOrKey": "secret"
}

where

issuer is principal that issued the token

audiance is the principal that is going to consume (recipients) the token

secretOrKey is the client secret or public key. However this would be overridden if following secret key environment variable is set SECRET_OR_KEY

NOTE: SECRET_OR_KEY environment variable overrides secretOrKey value passed as part of JWT_CONFIG

Trusted application

To use trusted application authentication, set environment variable JWT_CONFIG as

{
    "issuer": "mycompany.com",
    "audience": "mycompany.net",
    "secretOrKey": "secret",
    "keyToVerify": "client_id"
}

where

issuer is principal that issued the token (can be blank if issued token does not contain this key)

audiance is the principal that is going to consume (recipients) the token (can be blank if issued token does not contain this key)

secretOrKey is the client secret or public key

keyToVerify is the application identifiable key in jwt token (in this example the jwt token should contain client_id field).

If JWT token does not contain this key, the regular JWT user authentication would be tried as fall back mechanism, and if user is found request would run under that user’s identity; otherwise the request would be passed without any modification to next authentication strategy(if any).

NOTE: SECRET_OR_KEY environment variable overrides secretOrKey value passed as part of JWT_CONFIG

Setting up env variable

Note following suggestions are for development team only

Following are some suggestions to set up environment variable

  1. Boot file to set process.env.JWT_CONFIG and/or process.env.SECRET_OR_KEY
  2. In docker compose, one can set environment variable as part of yml file
  3. Set up a model after save observer to set environment variable SECRET_OR_KEY in run time (further JWT authentication would use new secret

Authentication

Application’s requirement

For user authentication, a corresponding user should be already present in oe-cloud BaseUser model. If not, the request would be unauthenticated.

Trusted application with 3rd party JWT token

For Trusted application authentication, external application should register itself with TrustedApp model with following details

{
   "appId": "the id of the application that would be passed in the jwt token. string type; mandatory field"
   "appName": "name of the application. string type",
   "supportedRoles":"array of roles, the authenticated application can be assigned. Entries should match the ids of BaseRole added in oe-cloud/application. array of string; mandatory field"
}

Trusted app with framework generated token

External application would register as usual with above setting with one additional property

{
   "appId": "the id of the application that would be passed in the jwt token. string type; mandatory field"
   "appName": "name of the application. string type",
   "username": "a username which is created in the app and associated to this trusted app to behave as service account"
   "supportedRoles":"array of roles, the authenticated application can be assigned. Entries should match the ids of BaseRole added in oe-cloud/application. array of string; mandatory field"
}

Make the request

While making the request to any oe-cloud API endpoint, following headers should be set for a successful jwt authentication

User authentication

For user authentication, add x-jwt-assertion in request header and the value would be the JWT signed with secret configured already.

Trusted application authentication 3rd party token

Add x-jwt-assertion in request header and the value would be the JWT signed with secret or public key configured already. Additionally, following headers are mandatory

username : username for user identity to be used

email : email for the user identity to be used

roles : string array of roles, would be used by oe-cloud ACL. Please note: these roles should be matched with id in oe-cloud/application BaseRole ids

Trusted application authentication with framework token

In this case framework is going to generate token for trusted application. Trusted application first call /api/TrustedApps/authenticate API to get a valid token. To call this API, following payload to be passed

{
 "username": "trusted app's associated service account username",
 "password": "corresponding password of service account",
 "appId": "appId of the trusted app"
}

This will return a valid JWT token to the external application to use. Use the token as intended and shown in previous section

How it works

When request comes to framework, auth-session model would figure out the type of authentication is needs to do. If JWT is enabled, user or trusted application JWT authentication would be initiated. Using secretOrKey jwt token would be decoded and application would verify whether user/application is registered with oe-cloud. In case of user, the authenticated request would be assigned an access token and acl would be effected based on the user identity (roles). For trusted application, if successfully verified, an user Identity would be created and supported roles (if matched) would be assigned and based on these information ACL would be applied.

If user/application cannot be verified with the data available in BaseUser/TrustedApp model, the request would not be authenticated and possibly 401 Authorization required error would be thrown. But any API not protected with ACL or has access to $unauthenticated would still be served.