Client Applications

Create Client Applications

When creating a ClientApp following settings need to be provided:

Setting	Description
Name	Name of the Client Application
Secret	Secure secret; empty when it's a public Client Application (SPA)
Enabled	Only active when it's set to true, otherwise the login is declined
Is Public	Set to true when Client Application is used for a SPA which cannot handle secrets
Is Restricted	Enable if only assigned users or users of assigned groups are allowed to login
Include Groups Claims	Enable when groups needs to be provided as claims
Access Token Type	Choose SelfContainedJwtToken (default) or ReferenceToken for issued access tokens
Token Encryption	Optional. Configure JWE algorithms and client keys after creating the ClientApp

For further configuration, edit the ClientApp once it is created.

Edit Client Applications

Following additional configuration can be changed once a ClientApp is created:

Setting	Description
Allow Cross Subscription	Allows a client application to be used across multiple subscriptions instead of just the one in which it was created
Resource Filter	Enable to only grant Resources defined in the ClientApp Resources list
Scope Filter	Enable to only grant Scopes defined in the ClientApp Scopes list
Access Token Type	Controls whether access tokens are returned as self-contained JWTs or as opaque reference tokens
Access Grant Consent	Define the consent type when logging in
Logout Consent	Define the consent type when logging in
Client Uri	Define the Client Application URI; optional
Logo Uri	Define a Client Application logo URI, optional
Authorized ProAuth Users	List of ProAuth users which are allowed to login (only available when client app is Restricted )
Authorized ProAuth Groups	List of ProAuth group member users which are allowed to login (only available when client app is Restricted )
Client App Secrets	List of secrets for this Client Application, possibility to set an expiration
Login Redirect Uri	Define a Client Application redirect URI, mandatory
Logout Redirect Uri	Define a Client Application logout redirect URI, optional when not using Logout
Backchannel Logout Uri	HTTPS endpoint on the client application that receives OIDC back-channel logout POST requests
Backchannel Logout Session Required	Enable when the client requires a sid claim in every logout token
Frontchannel Logout Uri	HTTP(S) endpoint on the client application that ProAuth loads in a hidden iframe during browser logout
Frontchannel Logout Session Required	Enable when the client requires iss and sid on every front-channel logout iframe URL
Metadata	List of detail information for this Client Application (unique key)
ClientApp Resources	List of allowed or available Resources for this Client Application
ClientApp Scopes	List of allowed or available Scopes for this Client Application
ClientApp Roles	List of available Roles for the Client Application
MFA Instances	List of available MFA instances
Tenants	List of allowed Tenants which can use the Client Application for authentication; if empty, no Tenant filter is active

Dynamic login redirect URI

If your application uses subdomains or URL paths to identify the tenant, you can set placeholders in the login redirect URI. In this case, the login request parameter acr_values with the tenant property can be omitted.

The following placeholders are supported:

• tenantkey

  This setting is defined in the Tenant entity

• tenantid

  This is the primary key of the Tenant entity

INFO

The redirect URI and the placeholders must be lowercase.

Samples:

• https://.myapp.com
• https://www.myapp.com/
• https://www.myapp.com/

Token Exchange Configuration

OAuth 2.0 Token Exchange (RFC 8693) enables secure token-to-token exchanges between different client applications within an identity system. ProAuth implements token exchange to support two key scenarios: cross-client user token exchange and service principal federation.

Overview

Token exchange allows a client application to exchange an existing token for a new token with different properties, potentially targeting a different audience or client application. This capability is particularly useful in distributed systems where users or services need to seamlessly interact across multiple applications.

Configuration Requirements

To enable token exchange, you must configure the following:

1. Authorization for Token Exchange: The client application that will perform the token exchange (source client) must be explicitly authorized to exchange tokens for specific target client applications.

2. Federated Identity Configuration: For service principal federation, additional configuration is required to map external identity providers' tokens to internal service principals.

Cross-Client User Token Exchange

This scenario allows a user token from one client application to be exchanged for a token that appears as if the user had directly logged in through another client application.

Configuration Steps

1. Identify the source client application that will request the token exchange
2. Identify the target client application for which a new token should be issued
3. Add the target client application to the source client's allowed token exchange list:

!ClientAppDto
id: b8075fdb-ac4f-4c25-8f2a-2
name: "ProAuth ExchangeToken Source TestClient A"
# ...
---
!ClientAppDto
id: "ff64b54e-3d4f-426d-ad1a-da30ebed78ab"
name: "ProAuth ExchangeToken Target TestClient B"
# ...
allowedTokenExchangeClientApps:
  - id: "b8075fdb-ac4f-4c25-8f2a-2085a9addbf6"

Example Use Case

A user authenticates to your main portal application, which then needs to access a dashboard application on the user's behalf. Instead of requiring a new login, the portal application can exchange the user's token for a token valid for the dashboard application.

Service Principal Federation

This scenario allows an external service token (such as from Azure, AWS, or GCP) to be exchanged for an internal service principal token within ProAuth. This enables secure cross-organizational service-to-service communication.

Configuration Steps

1. Configure the Service Principal Client Application

First, configure the client application that represents the service principal with federated identity information:

!ClientAppDto
id: "c400a0ee-f266-45f2-8fba-f5884ed2e386"
name: "Service Principal"
# ...
clientAppFederatedIdentities:
  - id: b4e9c08d-1b36-4cf0-8c65-1a3ee0676f7a
    issuer: https://auth.external.com
    subject: 123456789

Where:

• issuer: The URI of the external identity provider that issues the tokens
• subject: The subject identifier (usually in the sub claim) of the external service account

You can add multiple federated identities if the service principal needs to accept tokens from different external sources.

2. Configure the Token Broker

Then, configure the client application that will act as a broker to perform the token exchange:

!ClientAppDto
id: "39bda194-1967-4d8e-a190-60448d5c1ab3"
name: "Broker"
# ...
allowedTokenExchangeClientApps:
  - id: "c400a0ee-f266-45f2-8fba-f5884ed2e386"

Example Use Case

Your organization has a partner that needs to access your internal API. The partner authenticates using their own identity provider. The broker service validates the partner's token and exchanges it for an internal token that your API trusts.

Token Exchange API Usage

Once configured, client applications can use the token exchange endpoint:

POST /connect/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:token-exchange
&subject_token=eyJhb...existing token...
&subject_token_type=urn:ietf:params:oauth:token-type:access_token
&audience=https://target-audience
&client_id=broker-client-id
&client_secret=broker-client-secret

For service principal federation, the broker would submit the external token as the subject_token parameter.

Security Considerations

• Token exchange should only be allowed between trusted applications within your system
• Always validate the token exchange authorization before allowing an exchange
• Monitor token exchange activities to detect potential abuse
• Consider implementing additional security checks for service principal federation
• Use scopes to limit the permissions of exchanged tokens as appropriate

By properly configuring token exchange, you can enable secure and seamless interactions between different applications in your ecosystem while maintaining strong security boundaries.

JWT Client Authentication

ProAuth supports JWT bearer client authentication for confidential clients using the OpenID Connect private_key_jwt and client_secret_jwt methods. These methods can be used at all ProAuth OAuth endpoints that require client authentication: token, introspection, revocation, device authorization, and pushed authorization request (PAR).

JWT client authentication is configured per client application with the tokenEndpointAuthMethod setting:

• client_secret_basic
• client_secret_post
• client_secret_jwt
• private_key_jwt
• none

When a client application has an authentication configuration, ProAuth accepts only the configured method for that client. Existing clients without this configuration continue to use the legacy secret-based behavior.

Use the v2 Management API resource api/management/v2/ClientAppAuthenticationConfiguration to create or update this configuration. The request body uses these fields:

Field	Description
clientAppId	Client application id that owns the authentication configuration.
tokenEndpointAuthMethod	Authentication method. Use private_key_jwt or client_secret_jwt for JWT client authentication.
jwksUri	HTTPS URI for the client's public JWKS. Valid only for private_key_jwt; userinfo, fragments, and private or reserved network targets are rejected.
jwksJson	Inline client JWKS document. Valid only for private_key_jwt.
requireCertificateBoundAccessTokens	Optional token-binding flag. It may be enabled for non-mTLS methods, but the client must then present a valid certificate at the token endpoint so ProAuth can bind issued access tokens.

Configure private_key_jwt

Use private_key_jwt when the client can keep a private signing key and ProAuth can validate assertions with the corresponding public key.

Register exactly one JWKS source for the client:

• jwksUri: HTTPS URI that returns the client's public JWKS. ProAuth resolves the host before fetching, does not follow redirects, enforces a short timeout and response-size cap, and rejects loopback, private, link-local, multicast, documentation, and reserved network targets.
• jwksJson: Direct JWKS document stored with the client configuration.

Example direct JWKS:

{
  "tokenEndpointAuthMethod": "private_key_jwt",
  "jwksJson": "{\"keys\":[{\"kty\":\"RSA\",\"kid\":\"client-key-1\",\"use\":\"sig\",\"alg\":\"RS256\",\"n\":\"...\",\"e\":\"AQAB\"}]}"
}

Example JWKS URI:

{
  "tokenEndpointAuthMethod": "private_key_jwt",
  "jwksUri": "https://client.example.com/.well-known/jwks.json"
}

The client signs each assertion with the private key. ProAuth validates the JWT header algorithm, kid, signature, issuer, subject, audience, expiration, and replay protection.

Configure client_secret_jwt

Use client_secret_jwt when the client and ProAuth share a client secret and the client signs assertions with HMAC.

{
  "tokenEndpointAuthMethod": "client_secret_jwt"
}

No JWKS source is allowed for this method. ProAuth validates the assertion with the active client secret.

Assertion Requirements

The request must include:

client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
client_assertion=<signed JWT>

The JWT must contain:

• iss: the client application id.
• sub: the client application id.
• aud: the exact endpoint URL being called, for example /connect/token, /connect/introspect, /connect/revoke, /connect/device, or /connect/par.
• exp: a future expiration time.
• jti: a unique assertion id.

The jti value is stored until the assertion expires and cannot be reused for the same client.

Example token request with private_key_jwt:

POST /connect/token HTTP/1.1
Host: idp.example.com
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&
client_id=00000000-0000-0000-0000-000000000000&
client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&
client_assertion=eyJhbGciOiJSUzI1NiIsImtpZCI6ImNsaWVudC1rZXktMSJ9...

Example token request with client_secret_jwt:

POST /connect/token HTTP/1.1
Host: idp.example.com
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&
client_id=00000000-0000-0000-0000-000000000000&
client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&
client_assertion=eyJhbGciOiJIUzI1NiJ9...

Use the same request parameters at /connect/introspect, /connect/revoke, /connect/device, and /connect/par when those endpoints require client authentication. The assertion audience must be changed for each endpoint.

Client libraries fail closed for explicit secret-based methods. If ProAuth.Oidc.Client or ProAuth.Bff is configured with ClientSecretBasic, ClientSecretPost, or ClientSecretJwt, a client secret must be present. Use Auto only when the application intentionally allows public-client behavior when no secret is configured.

Discovery Metadata

Tenant discovery advertises client_secret_jwt and private_key_jwt in:

• token_endpoint_auth_methods_supported
• introspection_endpoint_auth_methods_supported
• revocation_endpoint_auth_methods_supported

PAR support is advertised through pushed_authorization_request_endpoint; ProAuth applies the same configured client authentication method to PAR requests.

Mutual TLS Client Authentication

ProAuth supports OAuth 2.0 Mutual-TLS Client Authentication and certificate-bound access tokens according to RFC 8705. mTLS client authentication can be used at all ProAuth OAuth endpoints that require client authentication: token, introspection, revocation, device authorization, and pushed authorization request (PAR).

Configure the method per client application with tokenEndpointAuthMethod:

• tls_client_auth
• self_signed_tls_client_auth

When RequireCertificateBoundAccessTokens is enabled, access tokens issued by the token endpoint include a cnf claim with the SHA-256 thumbprint of the presented client certificate. This is enabled by default for mTLS client authentication methods and disabled by default for other methods.

Use the v2 Management API resource api/management/v2/ClientAppAuthenticationConfiguration to create or update this configuration. The request body uses these fields:

Field	Description
clientAppId	Client application id that owns the authentication configuration.
tokenEndpointAuthMethod	Authentication method. Use tls_client_auth or self_signed_tls_client_auth for mTLS client authentication.
requireCertificateBoundAccessTokens	Optional token-binding flag. Defaults to true for mTLS methods and false for other methods.
tlsClientAuthSubjectDn	Registered subject distinguished name for tls_client_auth.
tlsClientAuthSanDns	Registered DNS subject alternative name value or values for tls_client_auth.
tlsClientAuthSanUri	Registered URI subject alternative name value or values for tls_client_auth.
tlsClientAuthSanIp	Registered IP subject alternative name value or values for tls_client_auth.
tlsClientAuthSanEmail	Registered email subject alternative name value or values for tls_client_auth.
jwksUri	HTTPS URI for the client's public JWKS. Valid only for self_signed_tls_client_auth; userinfo, fragments, and private or reserved network targets are rejected.
jwksJson	Inline client JWKS document. Valid only for self_signed_tls_client_auth.

tls_client_auth

Use tls_client_auth when the client presents a certificate that is validated by TLS termination or a trusted ingress. ProAuth checks the certificate validity period and matches the presented certificate against at least one registered metadata value.

Example client authentication configuration:

{
  "tokenEndpointAuthMethod": "tls_client_auth",
  "requireCertificateBoundAccessTokens": true,
  "tlsClientAuthSubjectDn": "CN=client.example.com,O=Example Corp,C=CH",
  "tlsClientAuthSanDns": "client.example.com"
}

The following metadata fields are supported and matched exactly:

• tlsClientAuthSubjectDn
• tlsClientAuthSanDns
• tlsClientAuthSanUri
• tlsClientAuthSanIp
• tlsClientAuthSanEmail

Multiple SAN values can be registered as comma-separated, semicolon-separated, or line-separated values.

tls_client_auth requires at least one subject DN or SAN metadata field. JWKS settings are not allowed for this method.

self_signed_tls_client_auth

Use self_signed_tls_client_auth when the client presents a self-signed certificate and ProAuth validates the certificate public key against the client's registered JWKS.

Register exactly one JWKS source:

{
  "tokenEndpointAuthMethod": "self_signed_tls_client_auth",
  "requireCertificateBoundAccessTokens": true,
  "jwksJson": "{\"keys\":[{\"kty\":\"RSA\",\"kid\":\"client-cert-key\",\"n\":\"...\",\"e\":\"AQAB\"}]}"
}

jwksUri is also supported. Remote JWKS fetching is HTTPS-only, does not follow redirects, enforces a short timeout and response-size cap, and rejects loopback, private, link-local, multicast, documentation, and reserved network targets. The certificate public key must match one registered RSA or EC JWK.

self_signed_tls_client_auth requires exactly one JWKS source. Subject DN and SAN metadata fields are not used for this method.

Forwarded Certificates

Direct TLS client certificates are read from HttpContext.Connection.ClientCertificate. For Kubernetes or reverse-proxy deployments, configure forwarded client certificates per tenant through tenant options. Forwarding is disabled by default.

Tenant option	Default	Description
ClientCertificateForwardingEnabled	False	Enables trusted forwarded client certificate headers for the tenant.
ClientCertificateForwardingKnownProxies	empty	Comma-separated proxy IP addresses allowed to forward client certificates.
ClientCertificateForwardingKnownNetworks	empty	Comma-separated proxy CIDR ranges allowed to forward client certificates.
ClientCertificateForwardingXForwardedClientCertHeader	X-Forwarded-Client-Cert	Envoy-style header that contains a Cert= value.
ClientCertificateForwardingPemCertificateHeaders	X-SSL-Client-Cert,X-Client-Cert,ssl-client-cert	Comma-separated header names containing URL-escaped PEM certificates.

Example tenant option values:

ClientCertificateForwardingEnabled=True
ClientCertificateForwardingKnownNetworks=10.0.0.0/24
ClientCertificateForwardingXForwardedClientCertHeader=X-Forwarded-Client-Cert
ClientCertificateForwardingPemCertificateHeaders=X-SSL-Client-Cert,X-Client-Cert,ssl-client-cert

ProAuth accepts Envoy-style X-Forwarded-Client-Cert values with Cert= and URL-escaped PEM headers. Forwarding is disabled by default. Do not enable certificate forwarding unless the ingress strips untrusted incoming certificate headers and sets them itself after validating the client certificate. For isolated Kubernetes system-test deployments where hosted build agents can come from changing Azure IP ranges, use a loose test-only tenant option such as ClientCertificateForwardingKnownNetworks=0.0.0.0/0,::/0. Only use this when the ingress strips inbound certificate headers from callers and sets the trusted header itself.

Certificate-Bound Access Tokens

For token-endpoint-issued access tokens, ProAuth adds:

{
  "cnf": {
    "x5t#S256": "base64url-encoded-certificate-sha256-thumbprint"
  }
}

ProAuth enforces this proof for its OIDC bearer endpoints such as userinfo. External resource servers should require the same presented client certificate and compare its SHA-256 thumbprint with cnf.x5t#S256 from the JWT access token or token introspection response.

Refresh tokens and authorization-endpoint-issued implicit or hybrid access tokens are not certificate-bound.

Discovery Metadata

Tenant discovery advertises tls_client_auth and self_signed_tls_client_auth in:

• token_endpoint_auth_methods_supported
• introspection_endpoint_auth_methods_supported
• revocation_endpoint_auth_methods_supported

PAR support is advertised through pushed_authorization_request_endpoint; ProAuth applies the same configured client authentication method to PAR requests. Discovery also sets tls_client_certificate_bound_access_tokens to indicate support for RFC 8705 certificate-bound access tokens.

Device Authorization Grant

ProAuth supports the OAuth 2.0 Device Authorization Grant defined by RFC 8628. Use this flow for clients that cannot comfortably open an embedded browser or enter a password directly, such as CLI tools, smart TVs, kiosks, and IoT devices.

The device client receives a device_code, a short user_code, and a verification URL. The user opens the verification URL on another device, signs in, reviews consent, and approves or denies the request. The device client polls the token endpoint until ProAuth can issue tokens or returns a final error.

Flow

Client Configuration

Enable the grant on the client application with the v2 Management API field allowDeviceAuthorizationGrant. The v1 Management API does not expose this setting.

Public clients may call the device authorization endpoint with client_id only. Confidential clients use the configured client authentication method from ClientAppAuthenticationConfiguration, including client_secret_basic, client_secret_post, client_secret_jwt, private_key_jwt, tls_client_auth, and self_signed_tls_client_auth.

{
  "name": "Example CLI",
  "isPublic": true,
  "allowDeviceAuthorizationGrant": true,
  "scopeFilterEnabled": true,
  "resourceFilterEnabled": true
}

Requested scopes and resources are still validated against the client application's configured filters. Request openid to receive an ID token and request offline_access to receive a refresh token.

Device Authorization Request

POST /{tenantKey}/connect/device HTTP/1.1
Content-Type: application/x-www-form-urlencoded

client_id=example-cli&scope=openid%20profile%20offline_access&resource=https%3A%2F%2Fapi.example.com

Successful response:

{
  "device_code": "opaque-high-entropy-device-code",
  "user_code": "ABCD-1234",
  "verification_uri": "https://idp.example.com/connect/verify",
  "verification_uri_complete": "https://idp.example.com/connect/verify?user_code=ABCD-1234",
  "expires_in": 600,
  "interval": 5
}

The user_code is short, uppercase, and case-insensitive. ProAuth stores only hashes of the device code and user code.

User Verification

Users can open either the tenant-specific verification URL or the root verification URL:

• /{tenantKey}/connect/verify
• /connect/verify

When verification_uri_complete is used, the user_code is prefilled. Root verification resolves the active user code to the correct tenant before continuing through the normal login, MFA, and consent checks.

The user may approve or deny the request. Approval stores a protected authenticated principal for the pending device session. Denial makes token polling fail with access_denied.

Token Polling

POST /{tenantKey}/connect/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:device_code
&client_id=example-cli
&device_code=opaque-high-entropy-device-code

Polling responses follow RFC 8628:

Condition	OAuth error
User has not completed verification	authorization_pending
Client polls faster than the current interval	slow_down
Device session expired	expired_token
User denied the request	access_denied
Device code is missing, invalid, belongs to another client, or was already redeemed	invalid_grant

After a slow_down response, ProAuth increases the current polling interval by 5 seconds. Clients should wait at least the latest interval before polling again.

Tenant Options

Option	Default	Description
DeviceCodeLifetime	00:10:00	Lifetime of the device authorization session, including both the device code and user code.
DeviceCodePollingInterval	00:00:05	Initial minimum polling interval returned as interval.

Discovery Metadata

The OpenID Connect discovery document advertises:

• device_authorization_endpoint
• urn:ietf:params:oauth:grant-type:device_code in grant_types_supported

Device clients should prefer the discovery metadata instead of constructing endpoint URLs manually.

Back-Channel Logout

Back-channel logout lets ProAuth notify relying party applications directly when a ProAuth browser session ends. This is useful for enterprise single sign-out because it does not depend on browser iframes or third-party cookies.

Configure the client application with:

Setting	Description
backchannel_logout_uri	Absolute HTTPS endpoint that accepts logout notifications. The URI must not contain a fragment.
backchannel_logout_session_required	When enabled, ProAuth only sends notifications for this client when a sid is available. New interactive OIDC sessions include a sid.

HTTP back-channel logout URIs are rejected by default. They can be enabled only for non-public clients with the development/test setting BaseServiceSettings:AllowInsecureBackchannelLogoutUris.

Receiver Endpoint

The client endpoint must accept an HTTP POST with content type application/x-www-form-urlencoded. ProAuth sends one form field:

logout_token=<signed JWT>

The logout token is signed with the same signing keys published by the ProAuth JWKS endpoint and uses typ value logout+jwt. Validate the token as a JWT and check:

Claim	Expected value
iss	The ProAuth issuer for the tenant.
aud	The client application ID.
iat and exp	The token is short lived and expires after 2 minutes.
jti	Unique token identifier. Receivers must reject replays until the logout token expires.
events	Contains http://schemas.openid.net/event/backchannel-logout.
sid	Session identifier for the OP browser session when available.
sub	ProAuth subject identifier for the logged-out user.

The logout token never contains a nonce claim.

ProAuth.Bff performs this validation for BFF applications. When back-channel logout is enabled, the BFF must have IDistributedCache registered. The cache is used for logout-token replay protection keyed by issuer, audience, and jti, and should be backed by Redis or another shared provider in multi-instance deployments.

Delivery And Retries

When a user logs out, ProAuth sends one immediate POST to each enabled client application that participated in the same OP session and has a backchannel_logout_uri. Clients from other sessions are not notified.

Responses 200 OK and 204 No Content are treated as successful. Network failures, timeouts, HTTP 408, HTTP 429, and HTTP 5xx responses are retried. HTTP 4xx responses such as 400, 401, and 403 are treated as permanent delivery failures.

Retryable failures are stored in the ProAuth state store and processed by the back-channel logout retry job. The default retry policy uses exponential backoff starting at 60 seconds, capped at 60 minutes, and stops after 6 attempts. In multi-instance deployments, all instances must share the same state store and lock store so the retry queue is durable and only one worker processes due entries at a time.

Troubleshooting

If a client does not receive logout notifications, verify that the client application is enabled, backchannel_logout_uri is configured, and the URI is reachable from the ProAuth runtime. Also verify that TLS certificates are trusted by the ProAuth container.

If retries are not processed, verify that the ProAuth job queue is running and that all instances use the same state store and lock store configuration. Permanent failures are not retried; check the receiving application logs for HTTP 400, 401, or 403 responses.

If a BFF rejects all logout notifications with a replay-protection configuration error, register a distributed cache provider before enabling back-channel logout. In production, avoid per-instance memory caches because they cannot detect replays that arrive at another pod.

Front-Channel Logout

Front-channel logout lets ProAuth notify relying party applications through the user's browser when a ProAuth browser session ends. ProAuth renders hidden iframes for client applications that participated in the same OP session and have a front-channel logout URI configured.

Configure the client application with:

Setting	Description
frontchannel_logout_uri	Absolute HTTP(S) endpoint loaded by the browser in a hidden iframe. The URI must not contain a fragment.
frontchannel_logout_session_required	When enabled, ProAuth includes the client only when a sid is available. New interactive OIDC sessions include a sid.

Logout Request

For every active client application with frontchannel_logout_uri, ProAuth appends these query parameters:

Parameter	Description
iss	The ProAuth issuer for the tenant.
sid	The OP session identifier from the ID token.

Existing query parameters on the configured URI are preserved. If the configured URI already contains iss or sid, ProAuth replaces those values with the authoritative logout values.

Front-Channel vs Back-Channel Logout

Front-channel logout is widely supported and works well for browser-based clients that already handle iframe logout notifications. It depends on the browser loading the client endpoint, so browser tracking protections and third-party cookie restrictions can make it less reliable.

Back-channel logout sends a signed logout_token directly from ProAuth to the client application's server endpoint. Prefer back-channel logout for confidential server-side applications and enterprise single sign-out where delivery reliability matters.

Both mechanisms can be configured on the same client application. When both are configured, ProAuth renders the front-channel iframe and also sends the back-channel logout notification for the same active session.

RP-Initiated Logout

Front-channel logout is triggered during normal RP-Initiated Logout through the ProAuth end-session endpoint. When post_logout_redirect_uri is supplied, ProAuth first renders the hidden iframes and then redirects the browser to the validated post-logout redirect URI, preserving the state parameter.

Reference Access Tokens

Client applications can choose the access token format with Access Token Type.

Value	Behaviour
SelfContainedJwtToken	Default. ProAuth returns a signed JWT access token. Resource servers can validate it locally with issuer metadata and signing keys.
ReferenceToken	ProAuth returns an opaque 32-byte base64url handle. The signed JWT access-token payload is stored server-side and resource servers validate the handle through token introspection.

Reference tokens are useful when immediate revocation and smaller tokens are more important than offline resource-server validation. Because the token contents are not visible to clients or intermediaries, APIs must call the introspection endpoint to get claims, scopes, expiry, audience, and client information.

Resource Server Validation

Resource servers that accept reference tokens must call the introspection endpoint:

POST /connect/introspect
Authorization: Basic <client credentials>
Content-Type: application/x-www-form-urlencoded

token=<access_token>&token_type_hint=access_token

An active reference token returns the same access-token payload data that a JWT client would receive locally, including scope, client_id, aud, sub, iss, iat, and exp. Missing, expired, or revoked reference tokens return active: false.

Revocation And Cleanup

Revoking a reference access token marks the stored token payload revoked immediately, so introspection returns inactive right away. With the database token backend, revoked and expired token rows are removed by the normal token prune job. With the Redis/state-store backend, revoked tokens are retained for the configured revocation TTL, or hard-deleted immediately when that TTL is 0.

Token Encryption

ProAuth can return encrypted JWTs for access tokens, ID tokens, and UserInfo responses. Encrypted tokens use compact JWE serialization and contain an inner signed JWT. This hides token contents from browsers, proxies, logs, and other intermediaries while preserving signature validation after decryption.

Client Configuration

Configure encryption on the ClientApp:

Setting	Description
Access Token Encryption Enabled Override	Optional per-client override. Empty inherits the tenant default. true encrypts self-contained access tokens. Reference access tokens remain opaque handles.
ID Token Encrypted Response Alg	JWE key management algorithm for ID tokens.
ID Token Encrypted Response Enc	JWE content encryption algorithm for ID tokens.
UserInfo Encrypted Response Alg	JWE key management algorithm for UserInfo JWT responses.
UserInfo Encrypted Response Enc	JWE content encryption algorithm for UserInfo JWT responses.
JWKS URI	HTTPS endpoint that exposes the client's RSA encryption public keys. Userinfo, fragments, redirects, and private or reserved network targets are rejected.
JSON Web Key Set	Directly registered client JWK Set. This is protected at rest and can contain RSA public keys or symmetric oct keys.

ID token and UserInfo encryption are enabled when both alg and enc are configured and ProAuth can resolve a matching client encryption key. If encryption is configured but no usable key is available, token issuance fails instead of returning plaintext.

Supported Algorithms

Key management algorithms:

• RSA-OAEP
• RSA-OAEP-256
• A128KW
• A256KW

Content encryption algorithms:

• A128CBC-HS256
• A256CBC-HS512
• A128GCM
• A256GCM

Symmetric key wrapping algorithms (A128KW, A256KW) require a directly registered JWK Set. ProAuth does not load symmetric keys from a remote JWKS URI and never publishes client symmetric keys.

Remote encryption JWKS fetching uses the same enterprise remote-document policy as JWT client-authentication keys: HTTPS only, DNS resolution before fetch, no redirects, short timeout, response-size cap, and public-address-only targets. Use a directly registered JWK Set for private-network key material.

Resource Server Integration

APIs that receive encrypted self-contained access tokens can either decrypt and validate the inner signed JWT with the client-held private/symmetric key, or use ProAuth token introspection. Introspection resolves encrypted access tokens by the token hash stored by ProAuth and returns the same payload data as for signed JWT access tokens.

Reference access tokens are unchanged by access-token encryption settings. The client still receives an opaque handle, and APIs validate it through introspection.

Discovery And JWKS

The discovery document advertises supported ID token and UserInfo encryption algorithms. The ProAuth JWKS endpoint includes ProAuth encryption public keys with use: enc for server-issued encrypted internal tokens. Client encryption keys remain configured on each ClientApp.