SAML 2.0

Integration

Estimated task time: ~15 minutes

Create a developer account

Sign up for a developer account to access additional developer documentation and set the stage for a new integration. There is no need to go through the entire setup process. Your ID.me team will assist with configuring a new SAML integration.

Exchange and ingest IdP and SP Metadata

Once an account is created, SAML metadata (along with keys) must be exchanged to ensure proper configuration of the endpoints.

Sandbox IdP Metadata

Production IdP Metadata

Preserving formatting and whitespace is critical 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

Direct users to AuthNRequest

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

1https://api.idmelabs.com/saml/SingleSignOnService?EntityID=<EntityID>&Binding=<binding>&AuthnContext=<policy-handle></policy-handle>

Parameters

NameDescription
EntityIDAn EntityID is a globally unique name for a SAML entity, either an Identity Provider (IdP) or a Service Provider (SP).
BindingThe ID.me IdP SAML service supports HTTP POST and HTTP Redirect binding
NameIDFormatThe ID.me IdP SAML service supports the following NameID formats:
- 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:1.1:nameid-format:unspecified
- 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: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
AuthnContextThe ID.me IdP SAML service supports invoking different authentication and verification policies on a per-application or per-request basis. The policy name is required to be passed along within the element.
RelayStateRelayState is an optional parameter that identifies a specified destination URL your users will access after signing in with SSO.

ID.me XML Signature

All ID.me SAML messages are digitally signed. This includes all requests, assertions and metadata. The XML signature is contained within the element. The signature serves as proof that only the IdP could have signed the element, and also to guarantee the integrity of the assertion. ID.me signs messages using SHA256, SHA384 and SHA512 algorithms.

1<samlp:Response xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
2xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
3ID="_67016ed111db-4bce-b065-45bcd564cd0e"
4Version="2.0"
5IssueInstant="2015-02-04T22:30:48Z"
6Destination="..."
7Consent="urn:oasis:names:tc:SAML:2.0:consent:unspecified"
8InResponseTo="_6a12a9ef28696226601602f669545e7ebb1c80d19a">
9<saml:Issuer>api.id.me</saml:Issuer>
10<ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
11<ds:SignedInfo>...</ds:SignedInfo>
12<ds:SignatureValue>...</ds:SignatureValue>
13<ds:KeyInfo>...</ds:KeyInfo>
14</ds:Signature>
15<samlp:Status>
16<samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success" />
17</samlp:Status>
18<saml:Assertion ID="_d20913189703-4b8b-97f4-c96ef7b1dccd" Version="2.0" IssueInstant="2015-02- 04T22:30:46Z">...</saml:Assertion>
19</samlp:Response>

ID.me XML Encryption

ID.me requires all SAML assertions to be encrypted. This helps protect any confidential data in the response. The encrypted assertion is contained within the element. ID.me supports using AES-128, AES-192 and AES-256 as message encryption algorithms.

1<samlp:Response xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
2xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
3ID="_46965880a3f0-461b-bc99-5ba262e812b3"
4Version="2.0"
5IssueInstant="2015-02-04T22:46:25Z"
6Destination="..."
7Consent="urn:oasis:names:tc:SAML:2.0:consent:unspecified"
8InResponseTo="_8bf72df7b4922883b1adad99926a0293c6e135b6da">
9<saml:Issuer>idp-staging.idmeinc.net</saml:Issuer>
10<ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">...</ds:Signature>
11<samlp:Status>
12<samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success" />
13</samlp:Status>
14<saml:EncryptedAssertion>
15<xenc:EncryptedData xmlns:xenc="http://www.w3.org/2001/04/xmlenc#" Id="_43a44a93ad36-4616-
16b1e6-2a96d4f3134c" Type="http://www.w3.org/2001/04/xmlenc#Element">
17<xenc:EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#aes256-cbc" />
18<ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
19<xenc:EncryptedKey Id="_78c2d92d0c46-4820-b8f0-52698580d7c9">
20<xenc:EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p" />
21<xenc:CipherData>
22  <xenc:CipherValue>...</xenc:CipherValue>
23</xenc:CipherData>
24</xenc:EncryptedKey>
25</ds:KeyInfo>
26<xenc:CipherData>
27<xenc:CipherValue>...</xenc:CipherValue>
28</xenc:CipherData>
29</xenc:EncryptedData>
30</saml:EncryptedAssertion>
31</samlp:Response>

Receive response signed and encrypted assertion

1<samlp:Response xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"  
2xmlns: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">
3  <saml:Issuer>http://idp.example.com/metadata.php</saml:Issuer>
4  <samlp:Status>
5    <samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success"/>
6  </samlp:Status>
7  <saml:Assertion xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xs="http://www.w3.org/2001/XMLSchema" ID="_d71a3a8e9fcc45c9e9d248ef7049393fc8f04e5f75" Version="2.0" IssueInstant="2014-07-17T01:01:48Z">
8    <saml:Issuer>http://idp.example.com/metadata.php</saml:Issuer>
9    <saml:Subject>
10      <saml:NameID SPNameQualifier="http://sp.example.com/demo1/metadata.php" Format="urn:oasis:names:tc:SAML:2.0:nameid-format:transient">_ce3d2948b4cf20146dee0a0b3dd6f69b6cf86f62d7</saml:NameID>
11      <saml:SubjectConfirmation
12Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
13        <saml:SubjectConfirmationData NotOnOrAfter="2024-01-18T06:21:48Z" Recipient="http://sp.example.com/demo1/index.php?acs" InResponseTo="ONELOGIN_4fee3b046395c4e751011e97f8900b5273d56685"/>
14      </saml:SubjectConfirmation>
15    </saml:Subject>
16    <saml:Conditions NotBefore="2014-07-17T01:01:18Z" NotOnOrAfter="2024-01-18T06:21:48Z">
17      <saml:AudienceRestriction>
18        <saml:Audience>http://sp.example.com/demo1/metadata.php</saml:Audience>
19      </saml:AudienceRestriction>
20    </saml:Conditions>
21    <saml:AuthnStatement AuthnInstant="2014-07-17T01:01:48Z" SessionNotOnOrAfter="2024-07-17T09:01:48Z" SessionIndex="_be9967abd904ddcae3c0eb4189adbe3f71e327cf93">
22      <saml:AuthnContext>
23        <saml:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:Password</saml:AuthnContextClassRef>
24      </saml:AuthnContext>
25    </saml:AuthnStatement>
26    <saml:AttributeStatement>
27      <saml:Attribute Name="uid" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
28        <saml:AttributeValue xsi:type="xs:string">test</saml:AttributeValue>
29      </saml:Attribute>
30      <saml:Attribute Name="mail" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
31        <saml:AttributeValue xsi:type="xs:string">test@example.com</saml:AttributeValue>
32      </saml:Attribute>
33      <saml:Attribute Name="eduPersonAffiliation" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
34        <saml:AttributeValue xsi:type="xs:string">users</saml:AttributeValue>
35        <saml:AttributeValue xsi:type="xs:string">examplerole1</saml:AttributeValue>
36      </saml:Attribute>
37    </saml:AttributeStatement>
38  </saml:Assertion>
39</samlp:Response>

Initiate business logic

After decrypting the assertion invoke your Business logic to use the Assertion and guide the user to the next steps per the response received.

Note: If an attribute is missing, the system will return a null value

Best practice

It is best practice to develop code in a manner that gracefully handles variations in data. For example, a name that contains a hyphen.

Payload specification

HandleNameMax LengthNull possibleComment
emailEmail255No
uuidUnique identifier32No
fnameFirst Name255YesIndividuals with only 1 legal name would have that name placed in the Last Name attribute
mnameMiddle Name255Yes
lnameLast Name255No
birth_dateBirth Date10NoDate format: YYYY-MM-DD
socialFull SSN9Yes
itinFull ITIN9Yes
ssn_itinFull SSN or ITIN9YesIf a member has both SSN and ITIN, SSN takes precedence
streetStreet255Yes123 Main St Apt 1a
street1Street1255Yes123 Main St
street2Street2255YesApt 1a
cityCity255Yes
stateState255YesAbbreviation or full state
zipPostal Code10YesUS Postal format: 00000, 00000-0000, or 000000000
phonePhone11YesPhone format: 10000000000
emails_confirmedConfirmed Emailsn/aNoArray of string values

International users will have a higher rate of Null values for the address attributes.

Additional attributes may be available. Discuss your use case with your ID.me team.