Skip to main content

Token Structures

Authentication with STS mode involves two distinct token types, each serving a different purpose in the authentication flow.

  • IAM tokens: issued by your organization's identity provider (such as Auth0, Okta, or Keycloak) when users or technical users authenticate. These tokens prove the user's identity and contain their organizational roles. The STS validates and exchanges these tokens for application-specific tokens.
  • STS tokens: issued by the Secure Token Service after validating an IAM token. These application tokens contain platform-specific permissions, tenant context, and user identity. When the Core is running in STS mode it validates these tokens on every request to enforce authorization and tenant isolation.

Understanding both token types is essential for:

  • Integrating your IAM provider with Procivis One services
  • Implementing custom token issuance if bypassing the STS
  • Troubleshooting authentication issues
  • Configuring services to validate tokens correctly

The following sections provide detailed specifications for each token type, including required claims, validation rules, and example payloads.

IAM token structure​

The following provides guidance on the authorization token structure expected by the STS when exchanging IAM tokens for application tokens. This is useful if you're integrating your own IAM provider (such as Keycloak, Auth0, Okta, etc.) with our platform.

JWT header​

{
  "kid": "2024-09-ed25519-iam-01",
  "alg": "EdDSA"
}

The STS validates the token signature using public keys retrieved from your IAM provider's JWKS endpoint.

Required:

  • kid (Key identifier): Identifies the public key at the JWKS endpoint
  • ald (Algorithm): Only EdDSA is supported

JWT payload​

{
  "sub": "user@example.com",
  "aud": "procivis-one-platform",
  "iss": "https://iam.example.com",
  "exp": 1760090352,
  "iat": 1759226378,
  "roles": [
    "organization_admin",
    "credential_issuer"
  ]
},
  • sub (Subject): Identifies the user or technical user. This value is used as the user's identity in the STS and subsequent application tokens.
  • aud (Audience): The intended audience for this token. This value must match the STS configuration for your IAM provider.
  • iss (Issuer): The IAM provider that issued the token. Must match the STS configuration for your IAM provider.
  • exp (Expiration): Unix timestamp indicating when the token expires. Must be in the future.
  • iat (Issued at): Unix timestamp indicating when the token was issued. Should be in the past.
  • User roles: A string array containing the user's roles within your IAM system. The location of this array within the token payload is configurable via JSONPath, for example $.roles. The STS uses these roles to map to platform permissions when issuing application tokens.

JWKS endpoint​

Your IAM provider must expose a JWKS endpoint (typically at /.well-known/jwks.json) that hosts the public keys used to verify token signatures. The STS will retrieve and cache these keys according to the configured TTL.

Flexible configuration​

The STS is designed to work with various IAM providers. The audience, issuer, roles JSONPath, and JWKS endpoint are all configurable, allowing you to integrate with your existing identity infrastructure without modification.

STS token structure​

The following provides guidance on the token structure expected by services running in STS authentication mode. This is useful if you're implementing your own token issuance infrastructure compatible with our platform.

JWT header​

Example:

{
  "kid": "2024-09-ed25519-prod-01",
  "alg": "EdDSA"
}

Required:

  • kid (Key identifier): Identifies the public key at the JWKS endpoint
  • alg (Algorithm): Only EdDSA is supported

JWT payload​

Example:

{
  "sub": "c0c17604-a370-49a5-8aa0-ee3d2a3a34a4",
  "aud": [
    "one-core",
    "one-bridge"
  ],
  "organisationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "permissions": [
    "STS_ORGANISATION_EDIT",
    "STS_ORGANISATION_CREATE",
    "STS_ORGANISATION_DETAIL",
    "STS_ORGANISATION_LIST",
    "STS_ORGANISATION_DELETE"
  ],
  "iss": "https://your-client.com",
  "exp": 1760090352,
  "iat": 1759226378
}

Required claims:

  • sub (Subject): Identifies the user or technical user. Must be less than 255 bytes. This value is logged in request history entries for audit purposes.
  • aud (Audience): Array of service identifiers that should accept this token. Must match the service's configured app.auth.stsTokenValidation.aud value.
  • organisationId: The tenant ID. Tokens are scoped to a single tenant – all requests using this token will be validated against this tenant context.
  • permissions: Array of permission strings granted to the token holder. The list is extensible; any permission unknown to the validating service will be ignored. See Permissions for guidance.
  • iss (Issuer): The authority that issued the token. Must match the service's configured auth.stsTokenValidation.iss value.
  • exp (Expiration): Unix timestamp indicating when the token expires. Must be in the future.
  • iat (Issued at): Unix timestamp indicating when the token was issued. Should be in the past.

Additional claims:

  • You may include additional custom claims in the payload, but they will be ignored by the service. Be mindful of token size, as the token is transmitted with every request.
  • If you include a jti (JWT ID) it must be unique per token.

Permissions​

The permissions array contains the platform-specific permissions granted to the token holder. For detailed information on available permissions, permission naming conventions, and how to retrieve the current permission list, see Permissions.