Overview of SAML

A brief overview of SAML as it relates to the Akana API Platform implementation.

Table of Contents

What is SAML?

SAML, the Security Assertion Markup Language, is an XML-based identity federation standard. Among other capabilities, SAML can be used for single sign-on.

SAML is used for exchanging authentication and authorization data between these two entities:

  • A Service Provider (providing a service to the user).
  • An Identity Provider (providing identity verification of the user to the Service Provider).

How SAML is used in the platform

The Akana API Platform supports SAML Web Browser SSO for:

  • Single sign-on: As the single sign-on token for the Community Manager developer portal login (along with other tokens such as the OpenID Connect id_token token).
  • OAuth Provider domain: For resource owner login when using OAuth Authorization Server.

Why choose SAML web browser SSO?

SAML and OpenID Connect are both very popular and mainstream standards that support single sign-on. OpenID Connect is essentially JSON-based; SAML is an XML implementation.

There are two main reasons why you might choose SAML over OpenID Connect for your Akana API Platform implementation:

  • An existing SAML implementation
  • The need to support webservices, REST APIs, and user login with a common infrastructure

How SAML web browser SSO profile works: high-level view

As with other SSO solutions, SAML provides authentication and verification of end-users via the SAML Web Browser SSO Profile, so that applications can outsource this critical, sensitive, and complex task. At a high level, the exchange of information is as follows:

  1. The end-user requests a service from an app.

    App = Service Provider; provides service to the end-user. Corresponds to Relying Party role in OpenID Connect; relies on the Identity Provider for verification of the user's identity.

  2. Before providing the service to the user, the app must authenticate the user. To do this, the app redirects the user to a supported SAML Identity Provider (IdP) of the end-user's choosing. The IdP:
    1. Requests authentication information from the user.
    2. Verifies the information.
    3. Logs the user in.
    4. Redirects the user back to the app.

    The Identity Provider provides user authentication services to the Service Provider. This role corresponds to the Asserting Party role in OpenID Connect. The Identity Provider sends the authentication information in the form of an XML document called a SAML Assertion.

  3. The app delivers the service to the end-user.

Of course, before being able to authenticate their users via a SAML Identity Provider, the app must first set up an account with the SAML Identity Provider.

In addition, for authentication to be successful, the end-user must have an account with the SAML Identity Provider.

In the Akana API Platform, Policy Manager/Community Manager acts as a SAML Service Provider. Configuring this solution requires coordination between values set up in your account with the SAML Identity Provider and in the domain setup in Policy Manager, so that messages can be sent and received between Policy Manager and the applicable Identity Provider.

How SAML web browser SSO profile works: behind the scenes

As part of the SAML Web Browser SSO Profile standard, the Service Provider defines a metadata file which includes information and settings that allow the Service Provider and the Identity Provider to validate each other's messages.

Once you've chosen your SAML Identity Provider, you create a Service Provider account with the IdP. In the context of the platform, since the platform is acting as your Service Provider, some of the values you specify are determined by your own choices and some values are determined by the platform and what it supports. Once you provide values and make choices, the Identity Provider generates a metadata XML file that includes values relevant to messages from the Identity Provider to the platform (as your Service Provider). For an example, see Sample Metadata File: Identity Provider.

In the same way, you create a domain in Policy Manager for the Identity Provider. Here, you provide values relevant to the Identity Provider and values you specify with the Identity Provider, such as the attributes you will use to identify your users with the Identity Provider. For example, you might use firstname, lastname, and emailaddress, or you might use username and password. Once you've set up this information, the platform generates a metadata XML file that includes values relevant to messages from the Identity Provider to the Service Provider. For an example, see Sample Metadata File: Service Provider.

This exchange of information via metadata sets the groundwork for the establishment of mutual trust and secure exchange of information between the two parties. Validation, encryption, and decryption go on in the background and are transparent to the user, as shown in the diagram below.

In some cases, such as with SSO Circle, the IdP publishes a generic metadata file. In other cases, such as PingFederate, the IdP metadata file is customized for each account. The Service Provider metadata file is always custom; when configuring your account with the IdP, you must provide the metadata file or configure the values manually.

SAML web browser SSO: process flow diagram

The sequence diagram below shows the basic exchange of information between the consumer (via the User-Agent), the Service Provider, and the Identity Provider when the SAML Web Browser SSO profile is used for single sign-on.

Note: The diagram below is general to SAML. For specific options supported, refer to Supported SAML bindings for single sign-on.

SAML diagram

In the above:

  1. Redirect to Identity Provider for SSO Service: Service Provider sends {AuthnRequest} request (authentication request) to Identity Provider. Three bindings are offered by the SAML specification:
    • HTTP POST. Sends the message content as a POST parameter in the payload. For more information, see HTTP POST.
    • HTTP Redirect. Redirects the user to the Identity Provider for login. Sends the message content in the URL. For more information, see HTTP Redirect.
    • HTTP Artifact (not currently supported by the Akana solution). Instead of sending the message content, sends a SAML Artifact to the content so the Identity Provider can retrieve it from an Artifact Resolution Service. For more information, see HTTP Artifact.
  2. Redirect to Service Provider with SAML Assertion: Identity Provider sends {Response} message to Service Provider. Two bindings offered by the SAML specification:
    • HTTP POST
    • HTTP Artifact

SAML specifications

Below are links to information relating to the SAML 2.0 specifications: