---
title: SAML v2.0 and PingGateway
description: PingGateway implements SAML 2.0 to validate users and log them in to protected applications.
component: pinggateway
version: 2025.9
page_id: pinggateway:gateway-guide:saml
canonical_url: https://docs.pingidentity.com/pinggateway/2026/gateway-guide/saml.html
llms_txt: https://docs.pingidentity.com/pinggateway/llms.txt
docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md
keywords: ["Configuration", "SAML 2.0", "Federation"]
superseded_by: https://docs.pingidentity.com/pinggateway/2026/gateway-guide/saml.html
section_ids:
  saml_assertions: SAML assertions
  saml_configuration: SAML configuration
  saml_in_deployments_with_multiple_instances_of_pinggateway: SAML in deployments with multiple instances of PingGateway
  about_sp_initiated_sso: About SP-initiated SSO
  am_as_idp: AM as IdP
  pingone_as_idp: PingOne as IdP
  federation_using_the_samlfederationhandler_deprecated: Federation using the SamlFederationHandler (deprecated)
  additional_topics: Additional topics
---

# SAML v2.0 and PingGateway

PingGateway implements SAML 2.0 to validate users and log them in to protected applications.

For more information about the SAML 2.0 standard, refer to [RFC 7522](https://www.rfc-editor.org/rfc/rfc7522). The following terms are used:

* *Identity Provider* (IdP): The service that manages the user identity, for example PingOne Advanced Identity Cloud or AM.

* *Service Provider* (SP): The service that a user wants to access. PingGateway acts as a SAML 2.0 SP for SSO, providing an interface to applications that don't support SAML 2.0.

* *Circle of trust* (CoT): An IdP and SP that participate in federation.

* *Fedlet*: SAML configuration files.

### SAML assertions

SAML assertions can be signed and encrypted. Use SHA-256 variants (rsa-sha256 or ecdsa-sha256).

SAML assertions can contain configurable attribute values, such as user meta-information or anything else provided by the IdP. The attributes of a SAML assertion can contain one or more values, made available as a list of strings. Even if an attribute contains a single value, it is made available as a list of strings.

### SAML configuration

PingGateway scans SAML configuration files once, the first time that a request accesses the [SamlFederationFilter](../reference/SamlFederationFilter.html) or [SamlFederationHandler (deprecated)](../reference/SamlFederationHandler.html) after startup. Restart PingGateway after any change to the SAML configuration files.

### SAML in deployments with multiple instances of PingGateway

When PingGateway acts as a SAML service provider, session information is stored in the fedlet not the session cookie. In deployments with multiple instances of PingGateway as a SAML service provider, it is necessary to set up sticky sessions so that requests always hit the instance where the SAML interaction was started.

For information, refer to [Session state considerations](https://docs.pingidentity.com/pingam/8/saml2-guide/saml2-configuration.html#saml2-and-session-state) in AM's *SAML v2.0 guide*.

## About SP-initiated SSO

SP-initiated single sign-on (SSO) occurs when a user attempts to access a protected application directly through the service provider (SP). Because the user's federated identity is managed by the identity provider (IdP), the SP sends a SAML authentication request to the IdP. After the IdP authenticates the user, it provides the SP with a SAML assertion for the user.

For the SamlFederationFilter, prefer SP-initiated SSO to IdP-initiated SSO:

* A dedicated SAML URI is not required to start SP-initiated authentication.

* The HTTP session tracks the state of the user session.

The following sequence diagram shows the flow of information in SP-initiated SSO when PingGateway acts as a SAML 2.0 SP:

![SP-initiated SSO](_images/samlfilter.svg)

## AM as IdP

* [Unsigned/unencrypted SAML v2.0 assertions](federation-setup-filter.html)

* [Signed/encrypted SAML v2.0 assertions](federation-setup-signed-filter.html)

## PingOne as IdP

* [PingGateway with PingOne as a SAML IdP](../pingone/saml-ping-one.html)

## Federation using the SamlFederationHandler (deprecated)

|   |                                                                                                                          |
| - | ------------------------------------------------------------------------------------------------------------------------ |
|   | The SamlFederationHandler is deprecated. Use the [SamlFederationFilter](../reference/SamlFederationFilter.html) instead. |

* [About SP-initiated SSO with the SamlFederationHandler and PingAM](federation-about-sp-init.html)

* [About IdP-initiated SSO with PingAM](federation-about-idp-init.html)

* [Unsigned/unencrypted SAML v2.0 assertions](federation-setup-handler.html)

* [Signed/encrypted SAML v2.0 assertions](federation-setup-signed-handler.html)

* [SAML 2.0 and multiple applications](federation-setup-multi-sps-handler.html)

## Additional topics

* [Non-transient SAML v2.0 NameID format](federation-non-transient-name.html)

* [Example SAML v2.0 Fedlet files](federation-example-files.html)