Documentation

SAML 2.0

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.

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
  • Single logout profile
  • Generation and verification of XML signatures
  • XML encryption and signing
  • HTTP POST and HTTP Redirect Binding

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.

Prerequisites

Build SAML Service Provider [SP] XML Metadata

Building the XML metadata of a SAML Service Provider providing some information is the first step to getting started: EntityID, Endpoints (Attribute Consume Service Endpoint, Single Logout Service Endpoint), its public X.509 cert, NameId Format, Organization info and Contact info.

Exchange Metadata with ID.me

Example

<?xml version="1.0"?> <md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" validUntil="2024-10-22 15:06:21 UTC" cacheDuration="PT604800S" entityID="https://example.id.me"> <md:SPSSODescriptor AuthnRequestsSigned="true" WantAssertionsSigned="true" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">false <md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified</md:NameIDFormat> <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://example.id.me/saml/callback" index="1"/> </md:SPSSODescriptor> </md:EntityDescriptor>

Step 1. Setup ID.me Relying Partner [RP] Metadata

Once you have built your SAML SP metadata and exchanged with ID.me to create your SAML instance, ID.me SAML metadata (along with keys) must be exchanged to ensure proper configuration of the endpoints. A copy of the current, full metadata can be found at the links below. Note that preserving formatting and whitespace is important when importing any XML metadata. The metadata document describes the IDP to a SP, including the following elements: The endpoint addresses for communication The X.509 certificates being used to sign and encrypt SAML assertions The SAML bindings supported by the service provider

Sandbox Metadata Endpoint
 https://api.idmelabs.com/saml/metadata/provider
Production Metadata Endpoint
 https://api.id.me/saml/metadata/provider

Step 2. Direct Member To AuthnRequest Endpoint

The client app must send the user to the AuthnRequest endpoint in order to initiate the SAML process. At the AuthnRequest endpoint, the user authenticates on the ID.me server and then grants or denies access to the app.

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.

AuthnRequest Example

<samlp:AuthnRequest xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" ID="https://example.id.me" Version="2.0" ProviderName="SP test" IssueInstant="2014-07-16T23:52:45Z" Destination="https://example.id.me/saml/callback" ProtocolBinding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" AssertionConsumerServiceURL="https://example.id.me/saml/callback"> <saml:Issuer>http://sp.example.com/demo1/metadata.php</saml:Issuer> <samlp:NameIDPolicy Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified" AllowCreate="true"/> <samlp:RequestedAuthnContext Comparison="exact"> <saml:AuthnContextClassRef>[YOUR_AUTHNCONTEXT]</saml:AuthnContextClassRef> </samlp:RequestedAuthnContext> </samlp:AuthnRequest>

Environments

Sandbox
 https://api.idmelabs.com
Production
 https://api.id.me

Endpoint

/saml/SingleSignOnService

URL Example

/saml/SingleSignOnService?EntityID=example.id.me&AuthnContext=login&NameIDPolicy=urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified

Parameters

Name Handle Description
EntityID ID The unique name that distinguishes it from any other entity.
AuthnContext RequestedAuthnContext Specifies which ID.me policy the SP requests the IDP to authenticate and verify the user to grant access to a specifc resource.
Supported values can be found here:
Standard OAuth/OIDC Scope & SAML AuthnContext Values
NameIDFormat NameIDPolicy Defines the name identifier formats supported by the IDP. Name identifiers are a way for providers to communicate with each other regarding a user.
Supported values can be found here:
  • urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
  • urn:oasis:names:tc:SAML:1.1:nameid-format:X509SubjectName
  • urn:oasis:names:tc:SAML:1.1:nameid-format:WindowsDomainQualifiedName
  • urn:oasis:names:tc:SAML:2.0:nameid-format:kerberos
  • urn:oasis:names:tc:SAML:2.0:nameid-format:entity
  • urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
  • urn:oasis:names:tc:SAML:2.0:nameid-format:persistent
  • urn:oasis:names:tc:SAML:2.0:nameid-format:transient
  • urn:oasis:names:tc:SAML:2.0:nameid-format:encrypted
Binding ProtocolBinding Represents the mechanism leveraged to transport SAML responses.
Supported values can be found here:
  • urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST
  • urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect
RelayState RelayState A parameter used to identify the specific resource the user will access after they are signed in and directed to the relying party (RP).

Step 3: Obtain SAML Response With Attribute Assertions

Protected REST endpoints can be access by making HTTP requests with the access token for a given user. The ID.me server will validate the access token to ensure it has not expired and that its scope covers the requested resource.

Example SAML Response

<samlp:Response xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" ID="_8e8dc5f69a98cc4c1ff3427e5ce34606fd672f91e6" Version="2.0" IssueInstant="2014-07-17T01:01:48Z" Destination="http://sp.example.com/demo1/index.php?acs" InResponseTo="ONELOGIN_4fee3b046395c4e751011e97f8900b5273d56685"> <saml:Issuer>http://idp.example.com/metadata.php</saml:Issuer> <samlp:Status> <samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success"/> </samlp:Status> <saml:Assertion xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xs="http://www.w3.org/2001/XMLSchema" ID="pfxfe5c883c-21aa-849c-7215-2a9915a14502" Version="2.0" IssueInstant="2014-07-17T01:01:48Z"> <saml:Issuer>http://idp.example.com/metadata.php</saml:Issuer><ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#"> <ds:SignedInfo><ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/> <ds:SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/> <ds:Reference URI="#pfxfe5c883c-21aa-849c-7215-2a9915a14502"><ds:Transforms><ds:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/><ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/></ds:Transforms><ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/><ds:DigestValue>VphTxU6WtufRaDm1hrEeB+yFu+s=</ds:DigestValue></ds:Reference></ds:SignedInfo><ds:SignatureValue>HdxT1pb0EqREWXtuQLYVE/B46ZQeybL8YDPrEHV8kvN9C1c2mEAkSlUYsrrFawypv3D9VsG2BeBBF30Af42DZiGRl8qFlSmr5yuO14pHqaJ44S8KZYD2nVjhEhJBAJHPxPpwsztvb1ezQd8E08fsyD9Iz2PSQLUUAERhKG+153Y=</ds:SignatureValue> <ds:KeyInfo><ds:X509Data><ds:X509Certificate>MIICajCCAdOgAwIBAgIBADANBgkqhkiG9w0BAQ0FADBSMQswCQYDVQQGEwJ1czETMBEGA1UECAwKQ2FsaWZvcm5pYTEVMBMGA1UECgwMT25lbG9naW4gSW5jMRcwFQYDVQQDDA5zcC5leGFtcGxlLmNvbTAeFw0xNDA3MTcxNDEyNTZaFw0xNTA3MTcxNDEyNTZaMFIxCzAJBgNVBAYTAnVzMRMwEQYDVQQIDApDYWxpZm9ybmlhMRUwEwYDVQQKDAxPbmVsb2dpbiBJbmMxFzAVBgNVBAMMDnNwLmV4YW1wbGUuY29tMIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDZx+ON4IUoIWxgukTb1tOiX3bMYzYQiwWPUNMp+Fq82xoNogso2bykZG0yiJm5o8zv/sd6pGouayMgkx/2FSOdc36T0jGbCHuRSbtia0PEzNIRtmViMrt3AeoWBidRXmZsxCNLwgIV6dn2WpuE5Az0bHgpZnQxTKFek0BMKU/d8wIDAQABo1AwTjAdBgNVHQ4EFgQUGHxYqZYyX7cTxKVODVgZwSTdCnwwHwYDVR0jBBgwFoAUGHxYqZYyX7cTxKVODVgZwSTdCnwwDAYDVR0TBAUwAwEB/zANBgkqhkiG9w0BAQ0FAAOBgQByFOl+hMFICbd3DJfnp2Rgd/dqttsZG/tyhILWvErbio/DEe98mXpowhTkC04ENprOyXi7ZbUqiicF89uAGyt1oqgTUCD1VsLahqIcmrzgumNyTwLGWo17WDAa1/usDhetWAMhgzF/Cnf5ek0nK00m0YZGyc4LzgD0CROMASTWNg==</ds:X509Certificate></ds:X509Data></ds:KeyInfo></ds:Signature> <saml:Subject> <saml:NameID SPNameQualifier="http://sp.example.com/demo1/metadata.php" Format="urn:oasis:names:tc:SAML:2.0:nameid-format:transient">_ce3d2948b4cf20146dee0a0b3dd6f69b6cf86f62d7</saml:NameID> <saml:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer"> <saml:SubjectConfirmationData NotOnOrAfter="2024-01-18T06:21:48Z" Recipient="http://sp.example.com/demo1/index.php?acs" InResponseTo="ONELOGIN_4fee3b046395c4e751011e97f8900b5273d56685"/> </saml:SubjectConfirmation> </saml:Subject> <saml:Conditions NotBefore="2014-07-17T01:01:18Z" NotOnOrAfter="2024-01-18T06:21:48Z"> <saml:AudienceRestriction> <saml:Audience>http://sp.example.com/demo1/metadata.php</saml:Audience> </saml:AudienceRestriction> </saml:Conditions> <saml:AuthnStatement AuthnInstant="2014-07-17T01:01:48Z" SessionNotOnOrAfter="2024-07-17T09:01:48Z" SessionIndex="_be9967abd904ddcae3c0eb4189adbe3f71e327cf93"> <saml:AuthnContext> <saml:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:Password</saml:AuthnContextClassRef> </saml:AuthnContext> </saml:AuthnStatement> <saml:AttributeStatement> <saml:Attribute Name="uuid" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"> <saml:AttributeValue xsi:type="xs:string">d733a89e2e634f04ac2fe66c97f71612</saml:AttributeValue> </saml:Attribute> <saml:Attribute Name="email" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"> <saml:AttributeValue xsi:type="xs:string">[email protected]</saml:AttributeValue> </saml:Attribute> <saml:Attribute Name="fname" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"> <saml:AttributeValue xsi:type="xs:string">Alayna</saml:AttributeValue> </saml:Attribute> <saml:Attribute Name="lname" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"> <saml:AttributeValue xsi:type="xs:string">Kihn</saml:AttributeValue> </saml:Attribute> <saml:Attribute Name="zip" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"> <saml:AttributeValue xsi:type="xs:string">04587</saml:AttributeValue> </saml:Attribute> <saml:Attribute Name="affiliation" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"> <saml:AttributeValue xsi:type="xs:string">Fully Managed, Inc.</saml:AttributeValue> </saml:Attribute> </saml:AttributeStatement> </saml:Assertion> </samlp:Response>

Errors

If the user denies the access request or if the request is invalid, the client will be informed using the following parameters appended to the response location:

Codes

Code Description
urn:oasis:names:tc:SAML:2.0:status:AuthnFailed The responding provider was unable to successfully authenticate the principal.
urn:oasis:names:tc:SAML:2.0:status:Requester The request could not be performed due to an error on the part of the requester.
urn:oasis:names:tc:SAML:2.0:status:Responder The request could not be performed due to an error on the part of the SAML responder or SAML authority.
urn:oasis:names:tc:SAML:2.0:status:VersionMismatch The SAML responder could not process the request because the version of the request message was incorrect.
urn:oasis:names:tc:SAML:2.0:status:InvalidAttrNameOrValue Unexpected or invalid content was encountered within a or element.
urn:oasis:names:tc:SAML:2.0:status:InvalidNameIDPolicy The responding provider cannot or will not support the requested name identifier policy.
urn:oasis:names:tc:SAML:2.0:status:NoAuthnContext The specified authentication context requirements cannot be met by the responder.
urn:oasis:names:tc:SAML:2.0:status:NoAvailableIDP Used by an intermediary to indicate that none of the supported identity provider elements in an can be resolved or that none of the supported identity providers are available.
urn:oasis:names:tc:SAML:2.0:status:NoPassive Indicates the responding provider cannot authenticate the principal passively, as has been requested.
urn:oasis:names:tc:SAML:2.0:status:NoSupportedID Used by an intermediary to indicate that none of the identity providers in an are supported by the intermediary.
urn:oasis:names:tc:SAML:2.0:status:PartialLogout Used by a session authority to indicate to a session participant that it was not able to propagate logout to all other session participants.
urn:oasis:names:tc:SAML:2.0:status:ProxyCountExceeded Indicates that a responding provider cannot authenticate the principal directly and is not permitted to proxy the request further.
urn:oasis:names:tc:SAML:2.0:status:RequestDenied The SAML responder or SAML authority is able to process the request but has chosen not to respond. This status code MAY be used when there is concern about the security context of the request message or the sequence of request messages received from a particular requester.
urn:oasis:names:tc:SAML:2.0:status:RequestUnsupported The SAML responder or SAML authority does not support the request.
urn:oasis:names:tc:SAML:2.0:status:RequestVersionDeprecated The SAML responder cannot process any requests with the protocol version specified in the request.
urn:oasis:names:tc:SAML:2.0:status:RequestVersionTooHigh The SAML responder cannot process the request because the protocol version specified in the request message is a major upgrade from the highest protocol version supported by the responder.
urn:oasis:names:tc:SAML:2.0:status:RequestVersionTooLow The SAML responder cannot process the request because the protocol version specified in the request message is too low.
urn:oasis:names:tc:SAML:2.0:status:ResourceNotRecognized The resource value provided in the request message is invalid or unrecognized.
urn:oasis:names:tc:SAML:2.0:status:TooManyResponses The response message would contain more elements than the SAML responder is able to return.
urn:oasis:names:tc:SAML:2.0:status:UnknownAttrProfile An entity that has no knowledge of a particular attribute profile has been presented with an attribute drawn from that profile.
urn:oasis:names:tc:SAML:2.0:status:UnknownPrincipal The responding provider does not recognize the principal specified or implied by the request.
urn:oasis:names:tc:SAML:2.0:status:UnsupportedBinding The SAML responder cannot properly fulfill the request using the protocol binding specified in the request.