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.

OpenID Connect Flows Overview

Primary OIDC Flows

• Authorization Code [response_type=code]
  • Used for back-channel communication (i.e. server-side web application)
  • After successful authentication, the response contains a code value. This code can later be exchanged for an access token and an id token.
  • The middleware needs a client id and a client secret.
  • This flow supports long-lived sessions through the use of refresh tokens
• Implicit [response_type=id_token token]
  • Used for front-channel communication (i.e. SPA, mobile app)
  • After successful authentication, the response contains an id token and an access token.
  • This flow does not support long-lived sessions
• Hybrid [response_type=code id_token]
  • This flow combines the above two in different combinations – what is needed for the use case

Other OICD 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)
• Resource Owner Password Credentials [not recommended]
  • Highly-trusted applications can use the resource owner password flow, which requests that users provide credentials (username and password) using an interactive form.
  • Because credentials are sent to the backend it is highly recommended to only use this flow for highly trusted applications.

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

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 an 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

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

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 second 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 Second Factors

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 a second factor on their own. This is fully supported by ProAuth. If this is not the case, or any additional security factor should be checked withing the ProAuth authentication flow, any authentication pipeline can be extended to use additional factors for authentication. Technically, multiple second factor validations could be added to a pipeline, in most cases only one is used.

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)
• 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.

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