JWT

The JWT request adapter is similar to the default adapter in that it lets you pull a JWT token from either a named header or a cookie.

JWT stands for JSON Web Token. JSON Web Tokens are an open, industry standard RFC 7519 method for representing claims securely between two parties.

You can read more about them at the official JWT web site.

Configuration

Here are all of the properties that may be configured:

{
    "adapters": {
        "{adapterId}": {
            "type": "jwt",
            "config": {
                "header": "{headerName}",
                "cookie": "{cookieName}",
                "trusted": false,
                "secret": "{secret}",
                "field": "{userIdField}"
            }
        }
    }
}

The value {adapterId} can be any unique ID across the adapters. This is the ID that you reference from within your strategy configuration.

The following configuration properties are supported:

• header - the name of the HTTP header whose value is the JWT payload
• cookie - the name of the HTTP cookie whose value is the JWT payload
• trusted - whether the identifying information is trusted
• secret - a secret key used to decrypt the JWT payload
• field - a dot-delimited field within the JWT payload that serves as the user identifier

Usage

The difference here is that the value received from either the header or the cookie consists of encoded (and optionally encrypted) JSON information that includes the profile.

If the value is encrypted, it is considered secure since the only way to decrypt it is to the know the shared secret that was used to encrypt it. This provides strong reassurance against a man-in-the-middle attack. However, if the value isn't encrypted and is simply encoded, then it might be useful but only if we validate it first.

In all cases, JWT tokens have a signature computed for them which provides some further assurance against a man-in-the-middle attack. However, the JWT Request Adapter will assume the token to be untrusted unless it is encrypted. If you wish, you can change this assumption using the trusted property.

The secret property lets you provide your shared secret so that any JWT encrypted tokens can be unencrypted and utilized by the framework.

Once the user profile is acquired, you should tell the request adapter which dot-delimited field to pick off inside of your user profile to serve as a primary key for your user. You can do this using the field property.

For example, suppose the user profile came through in a cryptographically signed JWT using the header JWT. It was signed with the secret abc123 and has a primary field which we identify as user.name.

The profile might look like:

{
    "id": "1234567890",
    "_json": {
        ... some stuff
    },
    "user": {
        "name": "jsmith",
        "firstName": "Joe",
        "lastName": "Smith"
    },
    "foo": {
        "bar": 42
    }
}

And the request adapter config could look like:

{
    "adapters": {
        "foo": {
            "type": "jwt",
            "config": {
                "header": "JWT",
                "secret": "abc123",
                "field": "user.name"
            }
        }
    }
}

This adapter will automatically be switched to trusted mode since the JWT value was encrypted. The user field is picked off and any backend user synchronization will utilize this information going forward.