Documentation

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.

Security

SAML is a secure protocol, which supports encryption and message signing. In addition, the HTTP communication security between the SP and the IDP is ensured by using SSL (TLS v1.1 or higher).

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.


<samlp:Response xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
      xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
      ID="_67016ed111db-4bce-b065-45bcd564cd0e"
      Version="2.0"
      IssueInstant="2015-02-04T22:30:48Z"
      Destination="..."
      Consent="urn:oasis:names:tc:SAML:2.0:consent:unspecified"
      InResponseTo="_6a12a9ef28696226601602f669545e7ebb1c80d19a">
  <saml:Issuer>api.id.me</saml:Issuer>
  <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
    <ds:SignedInfo>...</ds:SignedInfo>
    <ds:SignatureValue>...</ds:SignatureValue>
    <ds:KeyInfo>...</ds:KeyInfo>
  </ds:Signature>
  <samlp:Status>
    <samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success" />
  </samlp:Status>
  <saml:Assertion ID="_d20913189703-4b8b-97f4-c96ef7b1dccd" Version="2.0" IssueInstant="2015-02- 04T22:30:46Z">...</saml:Assertion>
</samlp:Response>

XML Encryption

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


<samlp:Response xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
      xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
      ID="_46965880a3f0-461b-bc99-5ba262e812b3"
      Version="2.0"
      IssueInstant="2015-02-04T22:46:25Z"
      Destination="..."
      Consent="urn:oasis:names:tc:SAML:2.0:consent:unspecified"
      InResponseTo="_8bf72df7b4922883b1adad99926a0293c6e135b6da">
  <saml:Issuer>idp-staging.idmeinc.net</saml:Issuer>
  <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">...</ds:Signature>
  <samlp:Status>
    <samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success" />
  </samlp:Status>
  <saml:EncryptedAssertion>
    <xenc:EncryptedData xmlns:xenc="http://www.w3.org/2001/04/xmlenc#" Id="_43a44a93ad36-4616-
    b1e6-2a96d4f3134c" Type="http://www.w3.org/2001/04/xmlenc#Element">
      <xenc:EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#aes256-cbc" />
      <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
      <xenc:EncryptedKey Id="_78c2d92d0c46-4820-b8f0-52698580d7c9">
          <xenc:EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p" />
          <xenc:CipherData>
              <xenc:CipherValue>...</xenc:CipherValue>
          </xenc:CipherData>
      </xenc:EncryptedKey>
      </ds:KeyInfo>
      <xenc:CipherData>
        <xenc:CipherValue>...</xenc:CipherValue>
      </xenc:CipherData>
    </xenc:EncryptedData>
  </saml:EncryptedAssertion>
</samlp:Response>