Introduction to SAML v2.0
SAML 2.0 helps organizations share, or federate identities and services, without having to manage the identities or credentials themselves. The credentials are managed by a single entity, known as the identity provider (IDP). The services are provided by service providers (SPs). Both providers are configured to trust one another.
AM uses the concept of the circle of trust to manage the relationship between IDPs and SPs.
Terminology
| Term | Description |
|---|---|
End user |
The person who is attempting to access the resource or application. In SAML v2.0, the end user is often referred to as the subject. The end user uses a user-agent, usually a web browser, when performing a SAML v2.0 flow. |
Single sign-on (SSO) |
The ability for an end user to authenticate once but gain access to multiple applications, without having to authenticate separately to each one. |
Single log out (SLO) |
The ability for an end user to log out once but terminate sessions in multiple applications, without having to log out separately from each one. |
Assertions |
An assertion is a set of statements about an authenticated user that let services make authorization decisions, that is, whether to allow that user to access the service, and what functionality they can use. SAML assertions are XML-formatted tokens. Assertions issued by AM can contain the following information about an end user: . Their attributes, such as pieces of information from the user’s profile. . The level of authentication they have performed. |
Identity provider (IDP) |
The IDP is responsible for authenticating end users, managing their account, and issuing SAML assertions about them. |
Service provider (SP) |
The provider of the service or application that the end user is trying to access. The SP has a trust relationship with the IDP, which enables the SP to rely on the assertions it receives from the IDP. |
Circle of trust (CoT) |
A circle of trust is an AM concept that groups at least one IDP and at least one SP who agrees to share authentication information. |
Hosted and remote providers |
A hosted provider is one served by the current AM instance; a remote provider is one hosted elsewhere. |
Metadata |
Providers in SAML v2.0 share metadata, which represents the configuration of the provider, as well as the mechanisms it can use to communicate with other providers. For example, the metadata may contain necessary certificates for signing verification, as well as which of the SAML v2.0 bindings are supported. Sharing metadata greatly simplifies the creation of SAML v2.0 providers in a circle of trust. AM can import the XML-formatted metadata provided by remote providers. You can also export the metadata from hosted providers. For more information about metadata, refer to Metadata for the OASIS Security Assertion Markup Language (SAML) V2.0 in the SAML V2.0 Standard. |
Concepts
Security Assertion Markup Language (SAML) 2.0 is a standard that lets users access multiple services with a single set of credentials. The services may be provided by different organizations, using multiple domains. In summary, SAML v2.0 provides cross-domain single sign-on (CDSSO).
For more information, refer to Security Assertion Markup Language (SAML) v2.0.
SAML v2.0 depends on standards for describing how the providers interact and exchange information. The SAML v2.0 standards describe the messages sent between providers, how they are relayed, how they are exchanged, and common use cases.
In federation deployments where not all providers support SAML v2.0, AM can act as a multi-protocol hub; translating for providers that rely on other and older standards, such as WS-Federation. You can find an integration example in How do I configure PingAM as an Identity Provider for Microsoft Office 365 and Azure using WS-Federation? in the Knowledge Base.
When your organization acts as the IDP and you want to enable SPs to federate their services with yours, you can generate configuration files for a fedlet.
An AM fedlet is a small Java web application that can act as a SP for a specific IDP without requiring that you install all of AM. For more information on fedlets, refer to Implement SAML v2.0 service providers by using Fedlets.
Example flow
When configuring AM to provide single sign-on using SAML v2.0, you can:
-
Map accounts at the IDP to accounts at the SP, including mapping to an anonymous user.
-
As the IDP, make assertions to the SP, for example, to attest that the end user has authenticated with the IDP.
The SP then consumes assertions from the IDP to make authorization decisions, for example, to let an authenticated user complete a purchase that gets charged to the user’s account at the IDP.
-
An unauthenticated user attempts to access a SAML v2.0 SP.
-
The SP determines the IDP associated with the end user, and redirects the user’s browser to the IDP, using an HTTP 302 Redirect message. A SAML v2.0 authentication request is included in the query string.
This is an example of HTTP-Redirect binding and is the default when requesting SAML authentication by AM. AM also supports the HTTP-POST binding for processing SAML v2.0 authentication requests.
AM provides two deployment models to support single sign-on (SSO) when contacting the SP initially. For details, refer to Implement SSO and SLO.
-
The IDP validates the request, determines the authentication method that should be used, and authenticates the user.
The SP can include certain requirements for the authentication it requires the user to perform in the authentication request, for example, a requirement to use multiple factors.
-
The IDP creates a SAML Artifact, which contains a unique artifact ID for the SAML v2.0 response.
The IDP redirects the end user’s browser to the SP, and includes the SAML Artifact in the query parameters. The browser only has access to the artifact ID rather than the SAML response itself, reducing risk of malicious interference.
-
The SP communicates directly with the IDP using the SOAP protocol to retrieve the SAML response relating to the artifact ID.
The IDP returns the SAML response, including the assertion using the SOAP protocol, directly to the SP.
The information in the SAML response is not shared with the user agent. This is an example of HTTP-Artifact binding, and is the default when AM is returning SAML assertions. AM also supports the HTTP-POST binding for transmitting SAML v2.0 assertions.
-
The SP validates the SAML response and that the signature matches the public key it holds for the IDP.
Optionally, the SP can choose to create a new account locally for the user or associate an identifier in the assertion with a user account it already has locally. Linked accounts are often referred to as a federated identity. Refer to Federate identities.
In order to link to an existing account, the SP can require the end user to also authenticate to the SP to determine the matching local account. Once linked, the user only needs to authenticate at the IDP when attempting access.
-
The SP can now use the information provided in the assertion, and any details in the local federated identity, to authorize the user, and decide whether to provide its services to the end user.
Use case: Let staff access Google Workspace
A common use case for SAML v2.0 is to allow your internal staff to access and use the applications provided by Google Workspace, such as Google Docs and Google Sheets. This section highlights how AM provides the solution.
In this scenario, Google acts as the SP, and AM acts as the IDP for a hypothetical organization, Example.com.
-
In AM, an administrative user configures an AM instance as the IDP.
-
The administrative user then configures Google Workspace as a remote SP and provides the values that Google requires to use AM as its IDP. For example, the login and logout URLs, profile management URLs, and validation certificate.
-
The Google Workspace administrator enters the provided URLs and certificate into the Google Workspace Admin console for the domain being configured.
-
After configuration is complete, users attempting to access a Google Workspace service will be asked for their corporate email address:
-
Based on the domain of the email address, Google redirects the user to sign in to AM, acting as the IDP:
-
After successfully authenticating with AM, the user is redirected back to the Google Workspace application, for example, Google Docs.
Google, acting as the SP, creates a federated identity in its systems to manage local account options, such as privacy settings. The user can now access any of the Google Workspace apps, by authenticating to the IDP using their corporate Example.com account:
