> For the complete documentation index, see [llms.txt](https://docs.securepass.me/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.securepass.me/documentation/reference/single-sign-on.md).

# Single sign on

Single sign-on lets a user authenticate once and reach every application they are entitled to, without signing in again at each one. SECUREpass acts as the Identity Provider.

This guide explains how SSO works in SECUREpass and which protocol to use for a given application. The step-by-step configuration screens are covered separately in *Manage Resources* — *Configuring a SAML application*, *Configuring an OpenID application* and *Configuring an OAuth application*.

## What SECUREpass SSO does

SSO in SECUREpass is a centralised, policy-based service. Once a user is authenticated, they reach all their authorised applications without further prompts.

Three characteristics are worth knowing before you plan a deployment.

**It is agentless.** There is no agent to download or install on the application side. This is what makes rollout to a new application a configuration exercise rather than a deployment exercise.

**It does not introduce a new user store.** SSO integrates with the directories and databases you already have — Active Directory, LDAP, a relational database — and enforces access control against those. Users keep their corporate credentials.

**It is stateless.** Configuration and security policy data live in an external directory or relational database, as do audit, key, reporting and session data. Nothing critical is held in the SSO service itself.

Logging out of one application logs the user out of all of them. Session management stays consistent rather than leaving orphaned sessions behind on applications the user has forgotten about.

## Supported protocols

| Protocol       | Use it for                                                                           |
| -------------- | ------------------------------------------------------------------------------------ |
| SAML 2.0       | Web applications that support SAML federation. SECUREpass acts as IdP.               |
| OpenID Connect | Modern web and mobile applications, and anything expecting a RESTful JSON API.       |
| OAuth 2.0      | API authorisation — authorization code with PKCE, client credentials, refresh token. |
| RADIUS         | VPNs, Wi-Fi access points and network devices.                                       |
| Header-based   | Legacy applications behind a reverse proxy that cannot speak a federation protocol.  |
| WS-Federation  | Federation across separate security domains.                                         |

{% hint style="info" %}
**Note**

The master documentation also lists agentless desktop SSO over Kerberos and NTLM on Windows domains, which does not appear in the technical solution document; the technical solution document lists WS-Federation, which does not appear in the master documentation. Confirm both with Product before publishing this table.
{% endhint %}

## SAML 2.0

SECUREpass supports SAML 2.0 for web-based applications, exchanging assertions between SECUREpass as Identity Provider and the application as Service Provider. The Service Provider requests and obtains an authentication assertion using digitally signed requests, and makes its access control decision on that basis.

### How the flow works

{% stepper %}
{% step %}

## The user requests a resource

They attempt to reach something hosted by the Service Provider. The SP determines that authentication is required and identifies the appropriate Identity Provider.
{% endstep %}

{% step %}

## The SP sends a SAML request to the IdP

This is redirected through the user's browser as a series of HTTP redirects or posts.
{% endstep %}

{% step %}

## The IdP authenticates the user

SECUREpass receives the request and authenticates — by password, by MFA, or by whatever the applicable risk profile demands.
{% endstep %}

{% step %}

## The IdP issues a SAML response

SECUREpass generates a response containing a signed assertion that the user has been authenticated, and returns it to the SP through the browser.
{% endstep %}

{% step %}

## The SP grants access

It validates the response and grants access to the requested resource based on what the assertion contains.
{% endstep %}
{% endstepper %}

The user never presents credentials to the Service Provider. That is the point: the SP grants access without ever handling the user's password.

### What you configure

Exchange metadata between SECUREpass and the application, configure the assertion, and map the attributes the application expects — commonly email, name and roles.

## OpenID Connect

OpenID Connect lets a client application verify a user's identity based on authentication performed by SECUREpass, and obtain basic profile information at the same time. It is a RESTful HTTP API using JSON.

### How the flow works

{% stepper %}
{% step %}

## The client application sends an authentication request

The request is sent to SECUREpass, which acts as the OpenID Provider. The request carries information about the client and the scope being requested.
{% endstep %}

{% step %}

## SECUREpass prompts the user to authenticate

Credentials, MFA, or whatever the risk profile requires.
{% endstep %}

{% step %}

## SECUREpass returns an authorization code

SECUREpass returns an authorization code to the client application. This is a temporary code, not an access token.
{% endstep %}

{% step %}

## The client exchanges the code for a token

It sends the authorization code together with its own client ID and client secret to the SECUREpass token endpoint, which verifies both and issues an access token.
{% endstep %}

{% step %}

## The client retrieves user information

Using the access token, it calls the SECUREpass userinfo endpoint, which validates the token and returns the user's information.
{% endstep %}
{% endstepper %}

The authorization code acts as an intermediary so that the user's authentication status is exchanged for a token without exposing credentials to the client.

### What you configure

Register the application as a client, then set the redirect URIs, the scopes, and the client secret. OAuth 2.0 authorization code with PKCE, client credentials and refresh token flows are all supported.

## RADIUS-based SSO

RADIUS handles authentication, authorisation and accounting for network services — Wi-Fi and VPN in particular.

The Service Provider, such as a VPN gateway or wireless access point, sends an authentication request to SECUREpass over RADIUS. SECUREpass verifies the credentials, generates an authentication assertion carrying the user's identity and authentication status, and returns it over the same protocol. The gateway grants or denies access on that basis.

This is what lets a user authenticate once with SECUREpass and then reach network services as well as web applications.

## Header-based authentication

Header-based authentication carries the authentication information inside HTTP request headers rather than asking for a username and password. It exists for applications that cannot participate in a federation protocol.

The user's request is routed through an application server integrated with SECUREpass. That server raises an authorization request, SECUREpass prompts for credentials, and on success returns an authentication token. The application server then sets the token as a header parameter on subsequent requests to the backend application, which verifies it and grants access. If authentication fails, access is denied and an error is shown.

This is the right choice for legacy applications behind a reverse proxy, and the wrong choice for anything that could use SAML or OIDC instead.

## WS-Federation

WS-Federation carries identity, authentication and authorisation across separate security domains. Use it where applications sit in a different trust domain from SECUREpass and expect WS-Federation rather than SAML.

## Sessions, step-up and logout

SECUREpass synchronises session attributes with the calling application over SAML or OpenID Connect, and manages authentication requests intelligently on that basis.

The practical consequence: if an application requires two factors and the user has already satisfied one of them in the current session, SECUREpass prompts for the second factor alone — provided the session timeout has not been exceeded. Users are not made to repeat authentication they have already completed.

A session can hold three kinds of information, all of which can be made available to applications:

* Fixed session attributes
* Protected properties
* Custom properties

Administrators control session duration, token expiry and refresh, and single logout behaviour.

## The application portal

Users launch their applications from the SSO portal, where everything assigned to them appears in one place and opens with a single click.

From the same portal a user can raise an access request for an application they do not yet have. Requests run through the approval workflow, including four-eyes approval where that is configured. Approvals are covered in *Approvals*.

## What SSO gives you operationally

* One place for users to find every application assigned to them.
* Corporate credentials rather than a separate set — SSO integrates with your existing LDAP or Active Directory.
* Centralised permission management across all federated applications.
* Access requests raised by users themselves, through the self-service portal.
* Four-eyes approval on access requests, for a transparent authorisation trail.
* All SSO activity logged centrally, so auditors have a single place to audit from.

The protocol is the only real decision here — SAML for federated web applications, OpenID Connect for modern and mobile ones, RADIUS for the network, header-based for legacy systems that cannot do better. Everything else is the same behind the scenes: authenticate once against the directory you already have, and let SECUREpass carry the assertion.