SAML Integration Guide

ID.me’s Identity Gateway platform provides a SAML 2.0 capable IDP service, which supports standardized, signed and encrypted assertions and different attribute bundles. This functionality can be used to enable applications to participate in a federated single sign-on (SSO) relationship with the ID.me network of credentials.

Overview

The ID.me SAML 2.0 IDP supports assertions, protocol bindings and profiles in accordance with the OASIS standard ( https://www.oasis-open.org/ ). These include:

  • SAML 2.0 assertions and all protocol messages
  • SAML 2.0 metadata
  • Web browser single-sign-on profile
  • Single logout profile
  • Generation and verification of XML signatures
  • XML encryption and signing
  • HTTP POST and HTTP Redirect Binding

The following diagram shows an overview of the SAML flow. The "SP" in this diagram stands for "Service Provider", a.k.a the partner.

Saml flow

Prerequisites

Applications must be enabled to support federated authentication via SAML 2.0 to consume the ID.me SAML service. Enablement of the functionality is provided through a variety of plugins and web access management services. Section 5.0 of this document provides a listing of resources for integration of the ID.me SAML IDP via several SAML SP software options.

What is SAML SSO

This is an abridged overview of SAML Federated Authentication. A full specification of the protocol can be found at https://www.oasis-open.org/


The objective of SAML Federated Authentication is to allow for the trusted access to distributed digital resources by users whom the service provider had no prior knowledge of or relationship with. The service also minimizes the number of times/locations a user must login to access resources across the web. This is accomplished by allowing a user to authenticate once via a SAML Identity Provider, then allowing that user to login to subsequent sites that are within the same ‘circle of trust’ without re-authenticating (assuming policies, timeouts and a lot of other rule sets are met!)


In order for this to work, a trust relationship must be established between the Identity Provider (ID.me) and the Service Provider.

To achieve this trust, ID.me allows each Service Provider to define discrete verification and authentication policies for each application through the ID.me Identity Gateway Platform.

ID.me SAML service supports both IDP and SP initiated

IDP Initiated SSO

The end user is redirected to a URL with the ID.me IDP service that contains the required parameters for an SSO handshake. This initiates a SAML authentication request to the IDP (ID.me). The user is presented with an ID.me login screen via a pop-up window or a full-screen redirect depending on the type of integration. Once the credentials have been submitted by the user, an authentication response in the form of an assertion is provided to the SP. Assuming that the verification and authentication/verification policies are met, the user is then able access the SP resource.

The parameters that are required in the initiation call are as follows:

  • EntityID – the entity ID for the given SP
  • AuthnContext – the handle for the policy being triggered
  • Binding – what SAML binding should be used for the response
  • RelayState – where the user should be redirected after a successful authentication

More information on authentication context and bindings can be found in the “Getting Started” section below.

SP Initiated SSO

The end user navigates directly to the SP and clicks sign-in with your ID.me credential. This initiates a SAML authentication request to the IDP (ID.me). The user is presented with a ID.me login screen via a pop-up window or a full-screen redirect depending on the type of integration. Once the credentials have been submitted by the user, an authentication response in the form of an assertion is provided to the SP. Assuming that the verification and authentication/verification policies are met, the user is then able access the SP resource.

Single Log Out (SLO)

Single Log Out across a network of federated SPs is achieved by providing the means for the end user to log out either at the IDP directly or at any SP within the network. This log out event results in the termination of the IDP initiated session, preventing the user from accessing another SP without re-authenticating. However, if an SP is generating their own session based on the IDP authentication response, the termination of the IDP session will not prevent further access to that SP. Access to SP’s issuing their own sessions is only terminated when the user logs out at that SP.