Introducing SAML v2.0

SAML v2.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. The services are provided by service providers. Both providers are configured to trust one another.

Overview of SAML v2.0 in AM
SAML v2.0 AM overview

AM uses the concept of the circle of trust to manage the relationship between IDPs and SPs.

Security Assertion Markup Language (SAML) v2.0 is a standard that enables users to access multiple services using only 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).

SAML v2.0 Terminology
TermDescription

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 issues by AM may contain the following pieces of information about an end user:

  1. Their attributes, such as pieces of information from the user's profile.

  2. The level of authentication they have performed.

Identity Provider (IDP)

The identity provider 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 service provider has a trust relationship with the identity provider, 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 identity provider and at least one service provider who agree to share authentication information.

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 other providers, which are referred to as remote providers. You can also export the metadata from providers created in an AM instance, referred to as hosted providers.

For more information about metadata, see Metadata for the OASIS Security Assertion Markup Language (SAML) V2.0 in the SAML V2.0 Standard.


For more information, see Security Assertion Markup Language (SAML) v2.0.

When configuring AM to provide single sign-on using SAML v2.0, you can map accounts at the identity provider to accounts at the service provider, including mapping to an anonymous user.

The identity provider can then make assertions to the service provider, for example, to attest that the end user has authenticated with the identity provider.

The service provider then consumes assertions from the identity provider to make authorization decisions, for example to let an authenticated user complete a purchase that gets charged to the user's account at the identity provider.

SAML v2.0 Flow
SAML v2.0 flow

  1. An unauthenticated user attempts to access a SAML v2.0 service provider.

  2. The service provider determines the identity provider 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, see Implementing SSO and SLO.

  3. The identity provider validates the request, determines the authentication method that should be used, and authenticates the user.

    The SP may include certain requirements for the authentication it requires the user to perform in the authentication request, for example a requirement to use multiple factors.

  4. 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. Note that the browser only has access to the artifact ID rather than the SAML response itself, reducing risk of malicious interference.

  5. 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.

  6. 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. See Federating Identities.

    Note

    In order to link to an existing account, the SP may require the end user to also authenticate to the SP to determine the matching local account. Once linked, the user will only need to authenticate at the IDP when attempting access.

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

SAML v2.0 requires interoperability, and 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 who rely on other and older standards, such as WS-Federation (for integration with Active Directory Federation Services, for example).

For information about implementing WS-Federation, refer to "How do I configure AM (All versions) as an Identity Provider for Microsoft Office 365 and Azure using WS-Federation?" in the ForgeRock Knowledge Base.

When your organization acts as the identity provider and you want to enable service providers 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 service provider for a specific identity provider without requiring that you install all of AM. For more information on fedlets, see Implementing SAML v2.0 Service Providers by Using Fedlets.

Use case: Allow staff to 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 service provider, and AM acts as the identity provider for a hypothetical organization; Example.com.

  1. In AM, an administrative user configures an AM instance as the IDP.

  2. 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 log in and log out URL, profile management URLs, and validation certificate.

  3. The Google Workspace administrator enters the provided URLs and certificate into the Google Workspace Admin console for the domain being configured.

  4. After configuration is complete, users attempting to access a Google Workspace service will be asked for their corporate email address:

    Identifying with email address to Google, the SP
  5. Based on the domain of the email address, Google redirects the user to sign in to AM, acting as the IDP:

    Identifying at the IDP with user name
  6. 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:

    Managing a federated identity at the SP.

Read a different version of :