Tokens

Endpoints for retrieving State Backed authorization tokens

All calls to State Backed must include a JWT signed by one of your State Backed keys in the authorization header.

The token should include an act claim that contains claims about your end user, which will be passed into your machine authorization functions (allowRead and allowWrite) as authContext. This allows you to, for instance, ensure that users can only send events to their own machine instances or instances that your application logic permits.

These tokens are easily created by the @statebacked/token library.

However, the signing keys to create these tokens must always be kept secret and cannot be included in client-side applications.

To allow you to use any authentication provider you want and to use State Backed without any server-side code, you can use our token exchange endpoints to securely exchange a JWT from your authentication provider for a State Backed JWT with the appropriate user claims.

After configuring trusted identity providers and token providers, you will be able to exchange a JWT from any of your trusted identity providers for a token with claims and a signature generated by any of your token providers by posting to the /tokens endpoint.

First, configure your trusted identity providers by posting to /idps. You will have to specify the audience and/or issuer that identifies a token from this IDP as well as the JWKS url where State Backed can retrieve the appropriate verification keys or the secret key that State Backed can use to verify the token (keys are stored encrypted in the State Backed vault). You will also provide a mapping, which extracts claims from the identity provider token to make them available to token providers.

Then, configure your token providers by posting to /token-providers. You will give your token provider a service name to identify it (you might want a different service for each app you build, for instance) and a mapping that specifies the claims that should be included in any token generated by that token provider.

After that, you have completely secure, end-to-end authenticated user sessions available in your State Backed backend without any server-side presence.

Mappings

Mappings are JSON objects whose structure matches the desired output of the mapping and whose values can refer to items from the input.

A mapping of:

{
  "sub.$": "$.sub",
  "email.$": "$.email",
  "service": "my-service",
  "special": {
    "role.$": "$.role.id"
  }
}

With input of:

{
  "sub": "my-user-id",
  "email": "my-email@statebacked.dev",
  "role": {
    "id": "my-role"
  }
}

Will produce a result of:

{
  "sub": "my-user-id", // mapping keys that end in ".$" treat values as JSONPath expressions into the input
  "email": "my-email@statebacked.dev",
  "service": "my-service", // mapping keys that don't end in ".$" treat values as constants (unless the value is a mapping)
  "special": {
    "role": "my-role" // mappings are resolved recursively
  }
}