Features

Implementation Scenarios

Solution Design

A lot of applications lack of a good authentication concept and implementation. Often, there is only a limited form of authentication options and those are often highly coupled into the application which makes it hard to maintain and easily adopt to customer requirements. There should be a clear distinction between application logic and authentication implementation and data. Furthermore often applications do not make use of a shared identity provides which makes it easy to impersonate calls between different services.

Modern applications or microservice architecture should rely on a trusted identity provider which decouples the authentication implementation from the services or applications. There should be a single trust from the application, so new federated identity providers or customer specific configurations do not affect the implementation or deployment of the services and applications.

Motivation

Dedicated Authentication Service – Single Point of Trust

• Reduction of dependencies, and maintainability costs
• Single point of trust – no changes in application if Identity Providers will be extended
• Separation of Concerns

Modern Authentication Protocols

• OpenID Connect, OAuth 2.0
• Federation with a great variety of providers
• Custom Identity Provider Module interface
• Enterprise ADFS Integration (OAuth)

Focus on SaaS Companies

• Management of Identity Providers on Tenant basis (tenants won’t see each others identity providers)
• Configuration at runtime with management API and UI
• Tenant specific Layout and Pages
• Self-Management for Tenants (i.e. Integration in Active Directory)

Sample Authentication Flow

Protocols

• ProAuth is based on OpenID Connect / OAuth protocols
• The application can use any OpenID Connect library to integrate with ProAuth
• Identity Provider Modules can implement any protocol. Also custom solutions may be added to the security pipeline.

Separation of Concerns

• Single trust from application to ProAuth
• No re-testing / re-validation of application if identity providers are changed / added
• Identity Provider Management at runtime

Different Identity Providers

• A large variety of identity providers are supported
• The different providers are federated by ProAuth
• Security Tokens are normalized for application by claim rule engine
  • Convert Claims
  • Add Claims
  • Remove Claims
• Module interface for custom providers
• Management during runtime

Multi-Tenancy

• Identity Providers from multiple tenants can be integrated
• Higher security since the authentication is managed by the tenant (i.e. Active Directory)
• Single Sign-On with domain credentials
• Filtering of Identity Providers by tenant
  • A tenant cannot see other tenant’s identity providers
  • Login-Pages can be customized per Tenant

Management

ProAuth is developed in an API-first approach which means that every functionality is available by API and therefore can be managed and automated from any application. In addition to the API, a Management UI is provided.

For scenarios where no federation to another identity provider is possible, ProAuth offers a user store where user, groups and memberships can be managed. This also follows the API-first development approach and offers an administration UI as well.

OpenID Connect Basics

This chapter covers the OpenID Connect functionality which is implemented in ProAuth. The goal of this chapter is to achieve a better understanding in different integration scenarios into your applications.

The secure baseline for new OIDC integrations in 2026 is the authorization code flow with PKCE, exact redirect URI matching, issuer validation, and refresh-token replay protection. ProAuth still supports some legacy response types for compatibility, but new applications should avoid implicit and hybrid response types that return tokens through the browser front channel. ProAuth does not implement the resource owner password credentials grant.

ProAuth includes the authorization server issuer identifier (iss) in authorization endpoint responses, including successful and error responses. Clients should compare this value with the issuer value from the discovery document. This follows RFC 9207 and helps clients that work with multiple identity providers prevent OAuth mix-up attacks.

Secure OIDC Baseline

New client applications should start with this baseline:

• Use authorization code flow with PKCE (response_type=code, code_challenge_method=S256).
• Register exact redirect URIs and avoid wildcard-style redirect behavior.
• Validate the discovery issuer and the authorization response iss value.
• Use refresh tokens only when long-lived sessions are required.
• Rely on ProAuth refresh-token replay protection when refresh tokens are used.
• Avoid implicit flow and front-channel access tokens.
• Do not use password grant. ProAuth does not implement it.

From that baseline, ProAuth v3 can harden the integration further with PAR, JAR, strong client authentication, sender-constrained tokens, FAPI 2.0 policy enforcement, pairwise subjects, token encryption, and JWT introspection responses.

OpenID Connect Flows Overview

Primary OIDC Flows

• Authorization Code with PKCE [response_type=code]
  • Recommended flow for web applications, SPAs, native apps, and mobile apps.
  • After successful authentication, the response contains an authorization code. The client exchanges the code at the token endpoint for an access token and, when openid is requested, an ID token.
  • Confidential clients authenticate at the token endpoint. Public clients must use PKCE.
  • This flow supports long-lived sessions through refresh tokens when offline_access is requested and allowed.
• Implicit [response_type=id_token token]
  • Supported only for legacy compatibility.
  • Not recommended for new applications because tokens are returned through the browser front channel.
  • Modern SPAs, mobile apps, and native clients should use authorization code with PKCE instead.
• Hybrid [response_type=code id_token]
  • Supported for compatibility and specialized legacy OIDC integrations.
  • New applications should prefer authorization code with PKCE unless a specific protocol profile requires hybrid behavior.

Other OIDC Flows

• Client Credentials Flow
  • Used for machine-to-machine authentication
  • Instead of username and password client id and client secret are used to authenticate the backend service
  • The access token is issued in the name of the client application (i.e. API) and therefore the call is identified as from another machine (i.e. API)
• Device Authorization Grant
  • Used for input-constrained devices and tools such as CLIs, smart TVs, kiosks, and IoT devices.
  • The device receives a user code and verification URL, while the user authenticates on another device with a full browser.
• Resource Owner Password Credentials
  • Not implemented in ProAuth.
  • Not recommended for modern applications because it asks users to give their password directly to the client application.

Response Types

Available Response Types

• code
• token
• id_token
• none

Valid combinations

• code
• token
• id_token
• id_token token
• code id_token
• code token
• code id_token token
• none

These response types describe protocol compatibility. For new applications, use code with PKCE unless a specific legacy integration or protocol profile requires a different response type.

OpenID Connect Flows Details

The following flows are implemented in ProAuth. Each flow is illustrated to show the different messages and tokens being exchanged between the client application and ProAuth.

Authorization Token Flow with OpenID

Request:

Auth Request Field	Value
Response Type	response_type=code
Scopes	openid

Issued Tokens:

Endpoint	Authorization Code	Access Token	ID Token
Authorization Endpoint	issued	-	-
Token Endpoint	-	issued	issued

Authorization Token Flow without ID Token

Request:

Auth Request Field	Value
Response Type	response_type=code
Scopes

Issued Tokens:

Endpoint	Authorization Code	Access Token	ID Token
Authorization Endpoint	issued	-	-
Token Endpoint	-	issued	-

Token Response

Request:

Auth Request Field	Value
Response Type	response_type=token
Scopes	openid

Issued Tokens:

Endpoint	Authorization Code	Access Token	ID Token
Authorization Endpoint	-	issues	-
Token Endpoint	-	-	-

IDToken Response

Request:

Auth Request Field	Value
Response Type	response_type=id_token
Scopes

Issued Tokens:

Endpoint	Authorization Code	Access Token	ID Token
Authorization Endpoint	-	-	issued
Token Endpoint	-	-	-

Implicit Flow

Legacy compatibility only

Implicit flow is still supported for existing integrations, but it should not be used for new applications. Tokens are delivered through the browser front channel, which is no longer the recommended model for SPAs, mobile apps, or native applications. Use authorization code with PKCE instead.

Request:

Auth Request Field	Value
Response Type	response_type=id_token token
Scopes

Issued Tokens:

Endpoint	Authorization Code	Access Token	ID Token
Authorization Endpoint	-	issued	issued
Token Endpoint	-	-	-

Hybrid Flow

Request:

Auth Request Field	Value
Response Type	response_type=id_token code
Scopes

Issued Tokens:

Endpoint	Authorization Code	Access Token	ID Token
Authorization Endpoint	issued	-	issued
Token Endpoint	-	issued	issued

Code and Token Response with OpenID

Request:

Auth Request Field	Value
Response Type	response_type=code token
Scopes	openid

Issued Tokens:

Endpoint	Authorization Code	Access Token	ID Token
Authorization Endpoint	issued	issued	-
Token Endpoint	-	issued	issued

Code and Token Response without OpenID

Request:

Auth Request Field	Value
Response Type	response_type=code token
Scopes

Issued Tokens:

Endpoint	Authorization Code	Access Token	ID Token
Authorization Endpoint	issued	issued	-
Token Endpoint	-	issued	-

Code, Token and IDToken Response

Request:

Auth Request Field	Value
Response Type	response_type=id_token token
Scopes	openid

Issued Tokens:

Endpoint	Authorization Code	Access Token	ID Token
Authorization Endpoint	issued	issued	issued
Token Endpoint	-	issued	issued

None Response

Request:

Auth Request Field	Value
Response Type	response_type=none
Scopes

Issued Tokens:

Endpoint	Authorization Code	Access Token	ID Token
Authorization Endpoint	-	-	-
Token Endpoint	-	-	-

Refresh Token Response

Request:

Auth Request Field	Value
Response Type	response_type=code
Scopes	openid offline_access

Issued Tokens:

Endpoint	Authorization Code	Access Token	ID Token	Refresh Token
Authorization Endpoint	issued	-	-	issued
Token Endpoint	-	issued	issued	issued

Tokens

The following tokens can be issued by ProAuth:

• id_token
  • Identity information about the user
  • Set of rules for validating an id_token: expiration and signature section
• access_token
  • Used as bearer tokens (can access authorized resources without further identification)
  • Usually short lifespan (expiration)
• refresh_token
  • Used to obtain new access tokens
  • Usually long-lived – allows for long-lived sessions that can be killed if necessary
  • Refresh tokens can be revoked by admins

Resources

The goal of authentication and authorization is to protect resources (i.e. an API). A token used to access a resource needs to be requested for this resource.

Different Scenarios

• Use a single access token with a single generic or global audience (i.e. all APIs in a single domain)
• Use a single access token with multiple audiences (i.e. one or more specific audiences fore each API)
• Use multiple access tokens, each with its own audience for each API

Resource and Audience

• A system consists of multiple resources which need to be protected
• Within a token request (authentication flows), the client requests the token be valid for one or many resources
• The identity provider verifies the request and creates tokens which are valid for the granted resources.
• The token contains an audience (aud) claim which indicates for what resources this token was issued for.

Claims and Scopes

Claims are assertions that one subject makes about itself or another subject.

• Information about subject like first name, last name, group membership
• Information about token like issuer and intended audience

Scopes are groups of claims

• Logical grouping of claims
• Consent to a scope will result in getting an ID Token containing the corresponding claims

Usage

• Claims are used to request a certain set of claims / access request
• The access token contains the requested scopes (and claims) whereas the id token contains the claims

OpenID Connect Scopes:

Scope	Claims
email	email, email_verified
address	address
profile	name, family_name, given_name, middle_name, nickname, preferred_username, profile, picture, updated_at website, gender, birthdate, zoneinfo, locale
phone	phone_number, phone_number_verified
openid	sub, auth_time, acr

The address scope returns the standard OIDC address claim as a JSON object, not as a string. ProAuth maps the primary SCIM address when present, otherwise the work address, otherwise the first non-empty address:

{
  "formatted": "1 Main St\n8000 Zurich\nSwitzerland",
  "street_address": "1 Main St",
  "locality": "Zurich",
  "region": "ZH",
  "postal_code": "8000",
  "country": "Switzerland"
}

The phone scope returns phone_number and phone_number_verified. phone_number_verified is a JSON boolean and maps to the v2 user PhoneNumberConfirmed field.

OIDC Claims Request Parameter

OpenID Connect clients can request individual claims with the claims authorization request parameter when scope groups such as profile or email are broader than needed. The parameter is a JSON object with separate id_token and userinfo targets. ProAuth merges these targeted requests with the normal scope-derived claims, so existing scope behavior is unchanged when the parameter is omitted.

Request an email claim in the ID token without requesting the full email scope:

{
  "id_token": {
    "email": { "essential": true }
  }
}

Request selected UserInfo claims independently of broad profile scope groups:

{
  "userinfo": {
    "name": null,
    "email": {}
  }
}

Use value or values to constrain the final claim value after ProAuth has loaded user data and applied claim rules. A constrained claim is emitted only when the final value matches:

{
  "userinfo": {
    "email": { "value": "alice@example.com" },
    "locale": { "values": [ "de-CH", "en-US" ] }
  }
}

ProAuth rejects malformed claims JSON and invalid claim request shapes. Unsupported requested claims, including unsupported custom claims marked as essential, are omitted rather than causing the authorization request to fail. The standard auth_time claim is emitted when requested as an essential ID token claim and the end-user authentication time is available.

Custom claim names are allowed. They can be supplied by federated input or by ProAuth claim rules, and value / values constraints are evaluated after those rules have run.

Advanced OIDC and OAuth Security

ProAuth v3 extends the secure OIDC baseline with features that are normally required in regulated, high-assurance, or enterprise SaaS deployments. These features can be enabled where they are needed without forcing every existing client application to migrate at once.

Hardened Authorization Requests

Pushed Authorization Requests (PAR) move the full authorization request from the browser URL to a back-channel POST request. ProAuth stores the pushed request and returns a short-lived request_uri; the browser redirect then only carries that handle. This keeps sensitive parameters out of browser history, reduces URL length problems, and prevents clients or intermediaries from accidentally changing request details in the front channel.

JWT-Secured Authorization Requests (JAR) let clients sign, and optionally encrypt, the authorization request as a JWT. ProAuth validates the signed request object before continuing the flow. Use JAR when the client and authorization server need cryptographic integrity for request parameters, especially in ecosystems that exchange authorization requests across organizational boundaries.

PAR and JAR can be used together. For FAPI-style clients, PAR is the central request-hardening feature. See PAR and JAR.

Strong Client Authentication

Client secrets are easy to understand but not always enough for high-value systems. ProAuth supports stronger client authentication methods at token, introspection, revocation, device authorization, and PAR endpoints:

• private_key_jwt: the client signs an assertion with its private key. ProAuth validates it with registered client app key sets. This avoids shared secrets and is the recommended asymmetric method for high-security confidential clients.
• client_secret_jwt: the client signs an assertion with its shared client secret. This improves request structure compared with posting the secret directly, but it is still based on a shared secret.
• mTLS client authentication: the client proves possession of a configured certificate during the TLS connection. This is useful for backend services, regulated integrations, and environments with mature certificate lifecycle management.

See JWT Client Authentication and Mutual TLS Client Authentication.

Sender-Constrained Access Tokens

Bearer tokens can be used by anyone who obtains them. Sender-constrained tokens reduce that risk by binding the token to key material that the legitimate client controls.

DPoP binds access tokens to a client-held asymmetric key. The client sends a signed DPoP proof with token and resource requests. ProAuth validates the proof, prevents proof replay, can require rotating DPoP nonces, and includes cnf.jkt in issued tokens. This is especially useful for browser, SPA, native, and mobile clients where mTLS is impractical.

Certificate-bound access tokens bind tokens to the SHA-256 thumbprint of the client certificate presented at the token endpoint. Resource servers can verify that the caller presents the same certificate when using the token. This is a strong fit for backend services and partner integrations that already operate with client certificates.

DPoP and mTLS certificate binding both satisfy the sender-constrained-token requirement used by FAPI 2.0 clients. See DPoP Token Binding and Mutual TLS Client Authentication.

FAPI 2.0 Security Profile

FAPI 2.0 Security Profile is an opt-in policy for high-value APIs. It turns a set of best-practice capabilities into enforceable rules:

• Authorization code flow only.
• S256 PKCE required.
• PAR required for authorization requests.
• Confidential clients only.
• Strong client authentication through private_key_jwt or mTLS.
• Sender-constrained access tokens through DPoP or certificate binding.
• Strict authorization-code and PAR lifetimes.
• Issuer identification in authorization responses.

FAPI mode can be required for a tenant or enabled for individual client applications. Existing non-FAPI clients keep their current behavior, which makes phased migration possible. Use this profile for financial, healthcare, government, and other high-assurance API access where configuration drift must be rejected at runtime rather than only documented.

See FAPI 2.0 Security Profile.

Token Protection and Introspection

ProAuth supports several token strategies so APIs can choose the right balance between self-contained validation, revocability, and confidentiality.

• Self-contained JWT access tokens allow APIs to validate tokens locally with ProAuth signing keys.
• Reference tokens return an opaque handle to the client and keep the token payload server-side. APIs validate the handle through introspection, which improves immediate revocation and keeps token contents away from clients and intermediaries.
• Encrypted tokens (JWE) protect token contents when a token may contain sensitive claims or crosses less-trusted infrastructure. ProAuth supports encryption for access tokens, ID tokens, UserInfo responses, and JWT introspection responses.
• JWT introspection responses let APIs request introspection results as signed, and optionally encrypted, JWTs. This gives resource servers cryptographic proof that the introspection result came from ProAuth while preserving the normal JSON response for clients that do not need JWT responses.

See Reference Tokens, Token Encryption, and Token Lifecycle.

Refresh-Token Replay Protection

For non-FAPI clients, ProAuth uses rolling refresh-token rotation. Each successful refresh-token grant returns a new refresh token and invalidates the previous one. If an old refresh token is used again, ProAuth treats it as a replay signal and revokes the token family for the user and client.

FAPI clients use stable sender-constrained refresh tokens. The refresh token is not rotated on every successful refresh grant, but every refresh request must still satisfy the configured FAPI client authentication and sender constraint, such as DPoP or mTLS.

Privacy and Data Minimization

Pairwise subject identifiers prevent relying parties from correlating the same user across unrelated client applications. Existing clients use public subjects by default and continue to receive the ProAuth user GUID as sub. Pairwise subjects are enabled per client app and produce a deterministic opaque sub for the user and client sector. Treat switching a live client from public to pairwise as a breaking identity-contract change for that relying party.

The OIDC claims request parameter lets clients request only the claims they need for ID tokens and UserInfo responses. This complements scopes such as profile, email, address, and phone, and helps reduce unnecessary claim release.

See Pairwise Subject Identifiers.

Enterprise Logout

Enterprise single sign-out needs more than deleting the ProAuth session. ProAuth supports:

• Back-channel logout: ProAuth sends signed logout tokens directly to registered relying parties. This is the preferred enterprise mechanism because it does not depend on browser iframe behavior.
• Front-channel logout: ProAuth can still notify relying parties through browser-loaded logout iframes for clients that require that pattern.

Back-channel logout is the stronger default for modern enterprise deployments. Front-channel logout remains useful for compatibility with clients that do not expose a back-channel endpoint. See Back-Channel Logout and Front-Channel Logout.

Device Authorization Grant

Device Authorization Grant lets clients without a comfortable browser or keyboard authenticate users safely. The device displays a user code and verification URL, the user completes authentication on another device, and the original client polls for completion. Use it for CLIs, kiosks, smart TVs, industrial devices, and IoT scenarios where embedding a password prompt would be unsafe or awkward.

See Device Authorization Grant.

Multi Tenancy

An important design goal of ProAuth is to support multi-tenancy all over the product and its functionality. A tenant is a customer / subsidiary / business unit using the application which authenticates through ProAuth. Often those entities have specific needs like special configurations, different federation settings or different requirements for MFA factors or simply just want to see their logo on the login screen. An authentication / authorization process always happens within a tenant configuration and therefore can be fully customized.

Technically, each tenant configuration spins up an authentication pipeline, so the authentication process is always specific for a tenant.

Runtime Configuration

Authentication requirements change over time and single-sign-on for new customers should be implemented seamlessly without redeployment of ProAuth. All configurations being applied in ProAuth will update the authentication pipelines during runtime and therefore new configurations and federated IDP instances can be added / modified / removed during runtime without any downtime. After a configuration change, the new authentication pipelines are created whereas the old authentication pipeline definitions still process the ongoing requests.

Federation and MFA

The primary use-case of ProAuth is to federate with other identity providers. The reason for this design decision is to support modern SaaS application scenarios where enterprise customers expecting to enable single-sign-on with their existing directories and identity providers. However, if this scenario is not applicable for any reasons, ProAuth offers an integrated user store where users and groups can be managed. The user store is the only module which stores user credentials in all other federated scenarios, this is not the case.

Every OIDC compliant identity server can be configured as a federated identity provider. In addition to that, there are further protocols and specific implementations supported.

Often, federated identity providers provide and enforce MFA on their own. This is fully supported by ProAuth. If this is not the case, or any additional security factor should be checked within the ProAuth authentication flow, any authentication pipeline can be extended to use additional MFA factors for authentication. Technically, multiple MFA validations could be added to a pipeline, in most cases only one is used.

ProAuth v3 also supports passkeys based on FIDO2/WebAuthn. Passkeys can be used for passwordless UserStore login and as phishing-resistant MFA for both UserStore and federated users. Users can register and manage passkeys through the Account Management portal, while administrators keep central control over where passkey login or passkey MFA is enabled. Passkeys are bound to the relying-party origin, which protects against credential phishing and removes shared secrets from the login experience.

The most common scenarios for ProAuth implementations are:

• Federated IDP / single-sign-on with Azure Active Directory (AAD)
• Federated IDP / single-sign-on with Active Directory Federation Services (ADFS for on-premises Active Directory)
• Federated IDP / single-sign-on with any OIDC compliant identity provider (i.e. Octa, Auth0, Google Directory)
• ProAuth User Store authentication (username / password authentication with login screen)
• ProAuth User Store passkey authentication (passwordless login)
• Passkey MFA for UserStore and federated identity providers
• Federated IDP / single-sign-on with social providers (B2C) (Microsoft account, Google account, Facebook account, Twitter account, ...)

ProAuth stores user information internally in a so called ProAuth user. The data stored comes from the federated identity provider. The user data managed in ProAuth can be extended by adding additional information in the user profile. In addition to that, group memberships can be manually managed in ProAuth (if the federated identity provider is not providing group memberships or if there is a need for additional managed groups).

In federated scenarios, ProAuth only knows about the user after the first login. To prevent that any user can authenticate from a federated directory, the automatic user creation up-on the first login request can be disabled. In this case, the user has to be created upfront by either using an invitation flow or synchronizing the directory with ProAuth. User and group synchronization is provided by offering a SCIM (System for Cross-domain Identity Management) interface. No credentials are synchronized, only user and group data. ProAuth is offering the following out-of-the-box synchronization integration:

• Azure Active Directory with SCIM Provisioning
• Active Directory Synchronization with ProAuth Directory Synchronization Tooling

Any other directory supporting the SCIM protocol can be setup for user and group provisioning in ProAuth. In those scenarios, there is no out-of-the-box support provided by ProAuth and the customer has to implement it on their own.

For detailed configuration instructions, see User Store Passkeys, Passkey MFA, and Account Security.

Security — Brute Force Protection

ProAuth includes built-in brute force protection to defend user accounts against automated credential-guessing attacks. Four configurable mechanisms are available:

• Permanent Account Locking — locks a user account after a defined number of consecutive failed login attempts. Requires manual unlock by an administrator.
• Temporary Account Locking — automatically locks a user account for a configurable duration, then unlocks it without administrator intervention.
• Progressive Login Throttling — introduces exponentially increasing delays between login attempts, making automated attacks impractical while keeping the impact on legitimate users minimal.
• CAPTCHA Protection — challenges users with a CAPTCHA after failed attempts or on every login, distinguishing humans from bots. Supports privacy-focused providers: Cloudflare Turnstile, hCaptcha, and Friendly Captcha.

These mechanisms apply to UserStore (password) authentication and can also be independently configured for MFA verification. All options are configurable per identity provider or MFA instance through the Management API and Admin UI.

For detailed configuration instructions, see User Store — Brute Force Protection and Multi-Factor Authentication — Brute Force Protection.

Token Exchange

ProAuth implements the OAuth 2.0 Token Exchange (RFC 8693) specification, which provides a protocol for requesting and obtaining security tokens from an authorization server. ProAuth supports two primary token exchange scenarios:

Cross-Client User Token Exchange

This scenario enables a seamless user experience across different applications within the same system. When a user is already authenticated in one client application (App A), another client application (App B) can request a token exchange to obtain a token as if the user had directly authenticated with App B.

Key characteristics:

• Limited to user access tokens issued by ProAuth (no external federation)
• Both client applications must be registered within ProAuth
• The exchanging client application must be explicitly authorized to exchange tokens for the other client application
• Preserves the user's identity and permissions while adapting to the target application's context

Service Principal Federation

This scenario allows external service tokens to be exchanged for internal service principal tokens, enabling secure service-to-service communication across organizational boundaries. A broker application validates the external token and exchanges it for an appropriate internal token.

Key characteristics:

• Enables federation of service principals from external identity providers
• The service principal client application must be configured with federated identity information (issuer and subject)
• The broker client application must be authorized to perform token exchange for the target service principal
• Maps external service identity to internal service principal without manual credential sharing

Both token exchange scenarios enhance security by:

• Eliminating the need to share credentials between applications
• Providing centralized control over token exchange permissions
• Creating audit trails for token exchanges
• Limiting token exchange to explicitly authorized client applications