Skip to main content

Authentication and Authorization

Procivis One supports three authentication modes across all components. In production, STS mode is expected. The simpler modes exist to reduce friction during development and testing.

For configuration details, see Core service configuration.

Authentication modes overview​

No authentication​

All requests are accepted without credentials. The service performs no access control and logs no user attribution.

Security Warning

This mode provides no built-in access control or audit trails. Do not use in production.

Core app.auth.mode BFF, Bridge, WRPR core.api.authentication UNSAFE_NONE, UNSAFE_STATIC, STS

Static token​

A single shared bearer token authenticates all clients. There is no tenant separation or user attribution.

Security Warning

This mode provides only basic authentication with no tenant isolation. Do not use in production.

Secure Token Service​

The recommended mode for production. The Secure Token Service integrates with your organization's OpenID Connect IAM provider and issues application tokens that carry user identity, permissions, and tenant context. Core and other components validate these tokens on every request, enforcing authorization and tenant isolation.

STS mode provides:

  • Fine-grained, role-based permissions
  • Strict tenant isolation; every token is scoped to a single tenant
  • Full audit trails with user attribution
  • Zero-trust request validation

The remainder of this page covers STS mode.

How STS mode works​

STS mode separates user authentication (handled by your IAM provider) from application authorization (enforced by Procivis One services).

There are two authentication actors:

  • Users authenticate with your IAM provider and receive an authorization token. When a user calls the Enterprise Backend, it validates the IAM token, then exchanges it for an STS application token before forwarding requests to Core.
  • Services authenticate as technical users, also via IAM, obtaining their own STS application tokens for actions they take autonomously. For example, the Bridge authenticates as a technical user when making proof requests to Core.

In both cases, Core validates the STS application token on every request. It checks the token signature, verifies claims, enforces the token's tenant context, and confirms the caller has the required permissions before processing anything.

Token exchange​

The token exchange pattern works as follows:

  1. The user or service authenticates with your IAM provider and receives an IAM authorization token containing their identity and roles.

  2. The client presents the IAM token to the STS, which validates it and issues an application token containing user identity, a single tenant context, and platform-specific permissions mapped from IAM roles.

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

  4. Core validates the application token and processes the request.

Tenant scope​

Each application token is scoped to a single tenant. To access resources in a different tenant, a new token must be obtained for that tenant context. This ensures strict tenant isolation at the token level.

Obtaining STS tokens​

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

Through the Enterprise Backend​

When integrating with the full Procivis One stack via the Enterprise Backend, token exchange is handled automatically. You authenticate with your IAM provider and call Enterprise Backend endpoints with your IAM token. The Enterprise Backend calls the STS internally and forwards requests to Core with the appropriate application token.

You do not obtain or manage application tokens directly in this pattern. See Integration patterns for architecture details.

Direct STS endpoint access​

If you are integrating directly with Core and want to use the STS for token exchange without the Enterprise Backend's management endpoints, call /api/sts/token/v1 directly. Configure the Enterprise Backend with management endpoints disabled:

sts:
  enableManagementEndpoints: false
  enableTokenEndpoint: true

Implement your own token service​

For advanced integrations, you can implement a token issuance service that produces tokens Procivis One services can validate directly, bypassing the STS entirely. Your service must issue JWTs conforming to the STS token structure.

See Token structures and Integration patterns for implementation guidance.

Token structuresJWT specifications for IAM and STS tokens; useful for custom integrations and troubleshooting
Integration patternsArchitectural options for connecting your application to Procivis One
Technical users and delegationSetting up non-Core components and custom services as technical users
Integrate OktaReference configuration for Okta as your IAM provider
Integrate KeycloakReference configuration for Keycloak as your IAM provider