Welcome to ID.me for developers! If you are interested in integrating ID.me, you are in the right place. Here we will cover how to get started implementing ID.me.

SAML Integration

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:

  • Check icon SAML 2.0 assertions and all protocol messages
  • Check icon SAML 2.0 metadata
  • Check icon Web browser single-sign-on profile
  • Check icon Single logout profile
  • Check icon Generation and verification of XML signatures
  • Check icon XML encryption and signing
  • Check icon 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.

Step 1: Build XML metadata of a SAML Service Provider

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.

Metadata Generator

Exchange Metadata with ID.me

<?xml version="1.0"?>
<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" validUntil="2023-07-04 03:36:35 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 2: Setup ID.me 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

Production Metadata Endpoint

Step 3: Direct User 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 include:
  • mfa
  • 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 include:
  • 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 include:
  • 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 4: Obtain SAML Response with User Attributes

    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">example@id.me</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">Pete</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">Zulauf</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">63484-1208</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">Best Buy Co, Inc.</saml:AttributeValue>
          </saml:Attribute>
        </saml:AttributeStatement>
      </saml:Assertion>
    </samlp:Response>
    Production Requirements

    Please follow the two steps outlined below. Note that you are responsible for ensuring that all implementations of the ID.me brand assets comply with accessibility requirements (example: Section 508 minimum color contrast requirements & WCAG guidelines). Visit https://webaim.org for more information.

    Step 1

    Verify your integration meets ID.me brand requirements and guidelines. For reference, please visit https://developers.id.me/brand-assets.

    Step 2

    Verify your integration returning SAML assertions and requests are executing upon retrieving the SAML response from ID.me.

    Step 3

    Verify all test credentials provided are generating the expected results based on configuration.

    Step 4

    Verify your platform digests and maps the verification data to the appropriate user and presents success messaging.

    Step 5

    Verify your ID.me application is in production mode and does not display "Sandbox Mode" to users.

    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 redirect uri:

    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.