Identity Validation

How to validate a user's identity in your web api

If you have enabled Include Delegated Auth Token in the Blueprint HTTP nodes, each request sent will contain a small JWT in the Authorization header.

This JWT is very short-lived (expiry ~5 minutes) and is designed to prove the identity of the caller as having come from the MSquared platform.

The token has the following payload:

{
  "scopes": [],
  "user_id": "<userid>",
  "iat": 1717077960,
  "iss": "<issuer>:auth",
  "exp": 1717078260,
  "aud": [
    "<aud>"
  ]
}

The JWT token header will contain a key id claim (kid) which can be used to validate the token using the JWKS published at https://admin.m2worlds.io/.well-known/jwks.json

The token can be validated using any JWT validation library, for example jose for JavaScript/Typescript users.

The current issuer in use is scarcely-calm-lark:auth and the audience is scarcely-calm-lark

import * as jose from 'jose'

const JWKS = jose.createRemoteJWKSet(new URL('https://admin.m2worlds.io/.well-known/jwks.json'))
const { payload, protectedHeader } = await jose.jwtVerify(jwt, JWKS, {
  issuer: 'scarcely-calm-lark:auth',
  audience: 'scarcely-calm-lark',
})

If the token validates successfully, you can use the user_id claim to identify the user in the MSquared platform.

if you specified a scope in the request, then your token will contain additional claims depending on the scope. For example, if you requested world scope:

{
  "scopes": [],
  "user_id": "<userid>",
  "organization_id": "<orgid>",
  "project_id": "<projectid>",
  "world_id": "<worldid>",
  "iat": 1717077960,
  "iss": "<issuer>:auth",
  "exp": 1717078260,
  "aud": [
    "<aud>"
  ]
}

It is recommended that you verify the tokens contain the organization, project and world claims you expect.