Authentication and authorization

Procivis One supports multiple authentication and authorization modes to accommodate different deployment scenarios and security requirements. This guide explains how authentication works across services, with a focus on the Secure Token Service (STS) – the recommended mode for production deployments.

For step-by-step configuration instructions, see Core service configuration.

Authentication modes overview

Procivis One can be configured with three authentication modes:

• No authentication
• Static token
• STS

No authentication

Disables all authentication checks. The service accepts requests without validating credentials, checking permissions, or logging user attribution.

Security Warning

This mode provides no built-in access control or user attributions for auditing. Most production deployments should not use this configuration.

See Core service configuration for configuration details and API clients integrating with Core for security considerations when disabling authentication.

Static token

Uses a single shared bearer token for authentication. All clients share the same token and permissions, with no tenant separation or user attribution.

Security Warning

While this mode provides basic authentication, most productive deployments should not use this configuration.

See Core service configuration for configuration details and usage guidance.

Secure Token Service

Recommended for production deployments: Integrates with your organization's IAM provider to provide:

• User and technical user authentication
• Fine-grained authorization with role-based permissions
• Tenant isolation and multi-tenancy support
• Audit trails with user attribution
• Token-based access control with signature verification

The remainder of this guide focuses on STS mode architecture, integration patterns, and implementation details.

STS mode

The STS provides enterprise-grade authentication and authorization for Procivis One services. It acts as a bridge between your organization's IAM provider and the platform, exchanging IAM authorization tokens for application-specific tokens that carry user identity, permissions, and tenant context.

Purpose and benefits

• Secure multi-tenancy: When you enable STS mode on a service, that service enforces tenant isolation on every request by requiring and validating STS-issued tokens. Each token contains a single tenant context and the caller's permissions within that tenant.
• Zero trust architecture: STS implements a zero trust security model where no request is inherently trusted. Each API call undergoes full authentication and authorization checks. The service validates the token signature, verifies claims, checks permissions, and enforces tenant boundaries before processing any request.
• Flexible deployment: STS is designed to integrate with diverse infrastructure patterns and security requirements:
  • IAM integration: Connect with your existing identify provider (Keycloak, Auth0, Okta, etc.) through configurable settings
  • Service-level configuration: Configure authentication independently for each service based on your architecture
  • Infrastructure compatibility: Deploy alongside authentication layers such as API gateways, service meshes, or reverse proxies that handle authentication at the infrastructure level
  • Multi-environment support: Adapt authentication strategies across development, staging, and production environments to balance security requirements with operational needs

How it works

STS mode implements a token exchange pattern that separates user authentication (handled by your IAM provider) from application authorization (enforced by Procivis One services).

Token exchange flow:

1. User authentication: Users or technical users authenticate with your IAM provider and receive an authorization token containing their identity and roles.

2. Token exchange: The client presents the IAM authorization token to the STS, which validates it and issues an application token. This application token contains:

• User identity
• A single tenant context
• Platform-specific permissions mapped from IAM roles
• Standard JWT claims

3. Request authorization: The client includes the application token with each request to Procivis One services.

4. Validation and enforcement: the Core service in STS mode:

• Validates token signatures using keys published on the configured JWKS endpoint
• Verifies token claims
• Checks that the user has the required permissions for the requested action
• Ensures all resources accessed belong to the token's tenant
• Stores the subject in system history for any action taken

Token scope

Each application token is scoped to a single tenant. When users need to access resources in a different tenant, they must obtain a new token for that tenant context. This ensures strict tenant isolation.

Technical users

In addition to end users, technical users (services like the BFF, Bridge, or your own applications) can authenticate with the STS using the same flow. Technical users receive tokens with service-specific permissions, enabling secure service-to-service communication while limiting services to their intended functions.

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 Retrieving available permissions for how to query system permissions.
• 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.

Retrieving available permissions

To retrieve available system permissions, call:

GET on `/api/config/v1`

The response includes a permissions object structured by resource type:

"permissions": {
    "CACHE": [
      "CACHE_DELETE"
    ],
    "CREDENTIAL": [
      "CREDENTIAL_DELETE",
      "CREDENTIAL_DETAIL",
      "CREDENTIAL_EDIT",
      "CREDENTIAL_ISSUE",
      "CREDENTIAL_LIST",
      "CREDENTIAL_REACTIVATE",
      "CREDENTIAL_REVOKE",
      "CREDENTIAL_SHARE",
      "CREDENTIAL_SUSPEND",
      "HOLDER_CREDENTIAL_LIST"
    ],
    "CREDENTIAL_SCHEMA": [
      "CREDENTIAL_SCHEMA_CREATE",
      "CREDENTIAL_SCHEMA_DELETE",
      "CREDENTIAL_SCHEMA_DETAIL",
      "CREDENTIAL_SCHEMA_LIST",
      "CREDENTIAL_SCHEMA_SHARE"
    ],
}

Permission naming convention

Each permission corresponds to a specific API action. Permissions follow the pattern RESOURCE_ACTION, for example, CREDENTIAL_ISSUE gives a user permission to issue a credential.

Service-specific permissions

Some permissions are only checked by specific services:

• OPENID_PROVIDER_* permissions: Checked by Bridge for managing OIDC provider configurations. Other services ignore these permissions.
• STS_ROLE_* and STS_IAM_ROLE_* permissions: Checked only by the BFF for configuring roles and permissions. Other services ignore these permissions.
  • STS_ORGANISATION_* permissions are checked by Core for admin management of tenants.

When constructing tokens for technical users, include only the permissions relevant to the target service and the actions that users need to perform.

Obtaining STS tokens

There are three ways to obtain STS application tokens, depending on your integration architecture:

1. Through the BFF

When using the full Procivis One stack, the BFF handles token exchange automatically. The IAM token is sent to BFF endpoints and the BFF internally calls the STS to exchange it for an application token before forwarding requests to Core or other services.

You do not directly obtain or manage application tokens in this pattern.

See API clients integrating with the BFF for architecture.

2. Direct STS endpoint access

If you are integrating directly with Core (bypassing the BFF's API endpoints), you can use the STS token endpoint /api/sts/token/v1 for token exchange while disabling other BFF functionality.

Configuration:

sts:
  enableManagementEndpoints: false
  enableTokenEndpoint: true

3. Implement your own token service

For advanced integrations, you can implement your own token issuance service that produces tokens compatible with Procivis One services.

Requirements:

• Your service must issue JWTs conforming to the STS token structure
• Configure Core services with your token issuer and JWKS endpoint
• Implement comprehensive token security measures - consult JWT and OAuth 2.0 security best practices for production deployments

See API clients integrating with Core and STS token structure for implementation guidance.

Integration patterns

This section describes common patterns for integrating applications and services with Procivis One's authentication infrastructure. Each pattern addresses different use cases and architectural requirements.

The patterns range from using the full stack (including the BFF and the Desk) to direct integration with Core services. Understanding these patterns will help you choose the right approach for your deployment.

Procivis One Desk authentication

This workflow shows how authenticated users interact with platform services through the web application (Desk).

Authentication and authorization checks

• At the gateway: If no valid session cookie is present, the gateway redirects the user to the IAM provider to authenticate and obtain a new token
• At the BFF: The BFF validates the authorization token and checks the user's permissions before routing requests or exchanging tokens
• At the Core (and other services in STS mode): The Core validates the application token and enforces both permissions and tenant context. It verifies the requested resources belong to the tenant specified in the token and that the user has the necessary permissions within that tenant.

Technical user authentication

Technical users are non-human actors such as the Bridge service, the BFF, or your own custom services that need to interact with the Core programmatically. These services authenticate with the IAM provider as technical users, then exchange their authorization token with the STS to receive an application token scoped to their specific permissions.

How technical users access the Core

Once a technical user obtains an application token, it can call the Core service with the respective permissions that have been granted to that technical user.

Within our platform, this flow enables service-to-service communication:

• Bridge to Core: Bridge authenticates as a technical user to create proof requests for login purposes. The Bridge service receives an app token with only the permissions necessary to manage proof requests within its tenant.
• BFF to Core: The BFF authenticates as a technical user to create login credentials. It receives an app token scoped to credential management permissions.

Permission isolation

In both cases, the service must present an app token that expresses its permissions as a technical user — not the permissions of end users. Administrators configure role and permission mappings so each technical user has only the permissions it requires within its own tenant. For example, you wouldn't want the BFF or another service to have permissions to issue credentials in a tenant shared with normal user credentials.

This architecture keeps your IAM provider external and decoupled from application-specific permission details. The permission logic remains within the platform services rather than leaking into your IAM configuration.

API clients integrating with BFF

An API client can integrate with the BFF. In this case, the IAM token is used with the BFF and the BFF makes calls to the Core and Bridge with app tokens. For configuring your IAM to produce authorization tokens the BFF can validate, see IAM token structure.

API clients integrating with Core

You can also integrate directly with the Core. There are three primary pathways:

1. Disable STS authentication and implement alternative security controls.

Security Warning

Disabling STS authentication removes the Core's built-in authorization checks, tenant separation, and request attribution. This configuration should only be used when:

• You understand the associated risks
• Authentication and authorization are enforced by infrastructure components
• The network perimeter is tightly controlled and monitored
• You have implemented compensating security controls

In INSECURE_NONE mode the Core uses no authentication.

In STATIC mode the Core enforces no tenant separation and does not log user attribution.

Most deployments should not use these configurations.

2. Use the /sts endpoint but bypass all other BFF endpoints. In this case follow the technical user authentication workflow. You will setup the BFF service but disable the /api endpoints, only calling for token exchange.

3. Create the STS token using your own service. In this case you will setup your client to produce tokens the Core can validate. Use the STS token structure for guidance.

Specialized workflows

Login with verifiable credentials

The Bridge and Core can be used to consume verifiable credentials as part of the OAuth 2.0/Authorization Code Flow:

Click to expand

You can see the flow in action in our trial environment where users can login to the Procivis One Desk using a credential issued from the Desk.

note

Login with credential does not require STS authentication mode.

BFF-issued login credential

The BFF can issue a login credential that can be used for subsequent logins.

You can see the flow in action in our trial environment, where Desk users can request a login credential from their profile page.

Two authorization scopes

This workflow demonstrates how different authorization scopes work together:

• User scope (1. Desk to BFF)
  • The user requests a login credential through Desk. The BFF validates that the user has permission to request a login credential, but the user does not need permission to issue credentials.
• Technical user scope (2. & 3. BFF to Core)
  • The BFF calls the Core as a technical user with its own app token. The Core validates that the BFF technical user has permission to create and share credentials of the specific type requested, within the designated tenant and issuer configuration. The Core does not check the end user's permissions - only the BFF's.

Permission isolation and tenant segmentation

This separation of scopes enables important security boundaries:

• Users can request credentials without issuing privileges: End users do not need broad credential issuance permissions. The BFF mediates the request and ensures the credential contains the correct user information.
• BFF operates in its own tenant: The BFF technical user is scoped to a dedicated tenant used exclusively for login credential issuance. This prevents the BFF from issuing credentials that belong to regular user workflows or other tenant contexts.
• Principle of least privilege: Each actor (user, BFF) has only the minimum permissions necessary for its role, limiting the radius of any potential compromise.