Skip to content

Commit c11a10a

Browse files
vrajmohanvrajmohan
committed
Describe the SAML Response in greater detail
The existing documentation for the SAML Authentication response (https://developers.login.gov/saml/authentication/#authentication-response) is low on detail - it just states that the response contains encrypted data. The example provided is for the _encrypted_ response and does not help in understanding the payload. This change attempts to: - provide a description of the actual data elements returned - adds an example of the decrypted response
1 parent 7f9cf63 commit c11a10a

File tree

2 files changed

+109
-30
lines changed

2 files changed

+109
-30
lines changed

‎_includes/snippets/saml/auth/response_example.md‎

Lines changed: 40 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -1,38 +1,50 @@
11
{% capture example %}
22
```xml
3-
<samlp:Response ID="_b28d50c0-dc35-0134-96f3-06d8bac14e9d"
4-
Version="2.0"
5-
IssueInstant="2017-02-23T20:36:37Z"
6-
Destination="https://sp.int.identitysandbox.gov/auth/saml/callback"
7-
Consent="urn:oasis:names:tc:SAML:2.0:consent:unspecified"
8-
InResponseTo="_6fca7b78-9ab7-49f5-bd62-18c48eac3c68"
9-
xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol">
3+
<samlp:Response xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" ID="_7f3d8cd9-d3f8-4b47-a571-5272810d5073" Version="2.0" IssueInstant="2024-09-18T16:20:36Z" Destination="https://sp.int.identitysandbox.gov/auth/saml/callback" Consent="urn:oasis:names:tc:SAML:2.0:consent:unspecified" InResponseTo="_bf054c05-5b2c-4773-a6a9-9ba075a87bc9">
104
<Issuer xmlns="urn:oasis:names:tc:SAML:2.0:assertion">https://idp.int.identitysandbox.gov/api/saml</Issuer>
115
<samlp:Status>
126
<samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success"/>
137
</samlp:Status>
148
<EncryptedAssertion xmlns="urn:oasis:names:tc:SAML:2.0:assertion">
159
<EncryptedData xmlns="http://www.w3.org/2001/04/xmlenc#" Id="ED" Type="http://www.w3.org/2001/04/xmlenc#Element">
16-
<EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#aes256-cbc"/>
17-
<ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
18-
<EncryptedKey xmlns="http://www.w3.org/2001/04/xmlenc#" Id="EK">
19-
<EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p"/>
20-
<ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
21-
<ds:KeyName/>
22-
<ds:X509Data>
23-
<ds:X509Certificate>MIIDejCCAmICCQDxlELhbJBQdzANBgkqhkiG9w0BAQUFADB/MRYwFAYDVQQDDA1TUCBSYWlscyBEZW1vMQwwCgYDVQQKDANHU0ExDDAKBgNVBAsMAzE4ZjETMBEGA1UEBwwKV2FzaGluZ3RvbjELMAkGA1UECAwCREMxCzAJBgNVBAYTAlVTMRowGAYJKoZIhvcNAQkBFgsxOGZAZ3NhLmdvdjAeFw0xNjA4MTgyMDIzMzNaFw0yNjA4MTYyMDIzMzNaMH8xFjAUBgNVBAMMDVNQIFJhaWxzIERlbW8xDDAKBgNVBAoMA0dTQTEMMAoGA1UECwwDMThmMRMwEQYDVQQHDApXYXNoaW5ndG9uMQswCQYDVQQIDAJEQzELMAkGA1UEBhMCVVMxGjAYBgkqhkiG9w0BCQEWCzE4ZkBnc2EuZ292MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA6gWv5EDu88CgWTgo+B8+Rp7ZSjNKKdud2I4U6Bfr0IMerdrh1LVwO6JOli/qRRDqECQz7Jm6m4XnVvf1bUiQd8cn/FheQfD2NuDNfrnAvyIRIHDgGHGSx3vjPZJVYi5BVmEOPFEKYEKHqS/UGnNjkS2XsoAkstRe6gioo4Hd2WLwjuCMqgNA3vgwyVxdgfI5vsrm6q43X15wb/wCP4r2rGKGSUIIshZPeUcPOzBMAmwVqREN4ux79Ee5K/87aXBVRF7Z2tFV1d5KEXO3dCw+T6cspj9MjfY2976cQfBXWnDKGdNWaLdwtFqvpgo9IXRxlAmUQtx8SC8z+zXaSSGB/wIDAQABMA0GCSqGSIb3DQEBBQUAA4IBAQCtc97SZLs5eBx7LrxdaeP5hq2etB7l6uM6+l/eSvXu8LlQfTUT7URxX4hXbKyORs1BLpnMYxofeyJlzb9K0koy1ZFhUtBufvU1R+ouMfZlV3QGOUMIUp00UNS39b74214jpuUYi7oEM0gHBN3BXxVyzUEAzt2HYHp2Im97ERSmTMkvSfiqilx/t03qIuZVxzu+jIU2BQUxS7s6XQ2DpDbvfggmnvToCmNA0VSg9rZkziOLSRHblcUpdMYH8+mzbTCfgg/Of0kTDVqXzgNa/iR0HUq18bDf3iFebS/sugwXN3vCxdCnad64q5tqF+VscZEtc7Okech2OuctnWy0nzFQ</ds:X509Certificate>
24-
</ds:X509Data>
25-
</ds:KeyInfo>
26-
<CipherData>
27-
<CipherValue>yaI+Z9oWcrP2WL02UdN7wdeoloWSBuz4nrFKh+vuyHitlk3A3/ATy4rtHerREue6uEYJ2sr7RoJbF/pqsr1j2ZWGJRL9FS++i0biE9iv3NwrW1MDvzGAaMiI9q+tmDqhorftiD+0byrtftZU2Emmwz34/bZJQKFszDeWlDrTVIXGDz+jF0Q+AvFxtaMrXXw6VmLlQlM/Hc9GiGCY+yalGmlteAJD+xk9aqUqfO9+qbwqufLQTpLyM8UdjHuwN9V4ZEo09er34SZD3ZhGq7IdWvROpcPeagU2+r6pivCmhY3x1t01uDtKe0jDt8LTGA1/P8atB3zQHkNnbGO1CiBKpg==</CipherValue>
28-
</CipherData>
29-
<ReferenceList>
30-
<DataReference URI="ED"/>
31-
</ReferenceList>
32-
</EncryptedKey>
33-
</ds:KeyInfo>
34-
<CipherData>
35-
<CipherValue>vy4Ohper0Oq24kU9GBTr0L8dHSBLkRpeu/iNr790cOQrAKphfPRCtLR7RHFI0mTCiko+Wy/oQqX4gu0LVtOOkcjJIicDyuWhIF6guUHvHz1PP4cv3pG++EhAJ73dbCPFSFkrDCzyMM5KZaY0xj6GpcYAVhOjez2ooOqwyTRYVpgozyuIreuooNFV8K++6GixLfBjw9T47eokKqLiROcRjEpV1dBoIkr34KtA7+TCrms1tLwAv4mdzCpUa7j</CipherValue>
10+
<EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#aes256-cbc"/>
11+
<ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
12+
<EncryptedKey xmlns="http://www.w3.org/2001/04/xmlenc#" Id="EK">
13+
<EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p"/>
14+
<ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
15+
<ds:X509Data>
16+
<ds:X509Certificate>
17+
MIIDgDCCAmgCCQCwpieA9CKuDDANBgkqhkiG9w0BAQUFADCBgTEYMBYGA1UEAwwP
18+
U1AgU2luYXRyYSBEZW1vMQwwCgYDVQQKDANHU0ExDDAKBgNVBAsMAzE4ZjETMBEG
19+
<!-- X509Certificate elided -->
20+
IYOalU+bIBpQt6EGN/mWBu7yZtgxKULZamJUUpd5xpcPcGKwf59etPVMTSxgeeQY
21+
MFjibtIlMmAweHgIqDyF2s8Etz8hlcKrXIUAK5CoMvgUn41V
22+
23+
</ds:X509Certificate>
24+
</ds:X509Data>
25+
</ds:KeyInfo>
26+
<CipherData>
27+
<CipherValue>DUs/UGjZTIioxWuRdUs8dWK4sLZ3zmAoTxX/mxliznXJfKn7JGQ6u9ccAG+o
28+
NbdunEQd0552Y6jdLGTulpuPxgC79gWsgxjV4sZzlALeLKu/VI/gUN7YNaoy
29+
QHQeO0XsH51pu5P4H0fjee2sJ++jnrY4auOMIYE3jWFScmRGrDXnvde6N1MW
30+
QThl1uSu2fDsQZdE9SOzg8rm8c85NcaBorJnHTTt7ywgLSt3weXkztUeujsc
31+
6ifawqRIdfcvL8eZxqKBUHSRu9gIXbmp13VQVZuKHO+MLrO2eTNMS6wRpGjl
32+
Lykqm6G3d8d7gn7oC08WI6YDrB5Kzo6hF/eaveOjtw==
33+
</CipherValue>
34+
</CipherData>
35+
<ReferenceList>
36+
<DataReference URI="ED"/>
37+
</ReferenceList>
38+
</EncryptedKey>
39+
</ds:KeyInfo>
40+
<CipherData>
41+
<CipherValue>cIGCpOu5tXI1RuBj32Sas6saN5brvkYea2QYgIAFNi6NgHngIs4JAkcTGxRg
42+
U9Vyfb2F3kndo5hBJaLmnKjLlwZRCBwoVfYfiaKUumH+igiPeyfcOGi617bN
43+
dpylxgT3Exg/g8qX5V02nIibCvlgO9tm9mPL5Rx0EZ32HMOc+Q62TF7F3e6X
44+
<!-- CipherValue elided -->
45+
2SWxCSIh0QLjt0Sos4ixK58eYc0p+8wbJnks14GzDGA07qJenT4NKxIIU2wW
46+
y+0Uv+X9Bk3S+y/6ba+v
47+
</CipherValue>
3648
</CipherData>
3749
</EncryptedData>
3850
</EncryptedAssertion>
@@ -41,4 +53,4 @@
4153
{% endcapture %}
4254
<div markdown="1" data-example="example" class="markdown long">
4355
{{ example | markdownify }}
44-
</div>
56+
</div>

‎_pages/saml/authentication.md‎

Lines changed: 69 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -51,6 +51,63 @@ A proofed identity request at AAL2, with phishing resistent MFA, for email, phon
5151
</samlp:AuthnRequest>
5252
```
5353
{% endcapture %}
54+
{% capture decrypted_response %}
55+
```xml
56+
<Assertion xmlns="urn:oasis:names:tc:SAML:2.0:assertion" ID="_b7a3ca0f-25a4-4365-af81-da8f04740564" IssueInstant="2024-09-18T16:20:36Z" Version="2.0">
57+
<Issuer>https://idp.int.identitysandbox.gov/api/saml</Issuer>
58+
<ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
59+
<ds:SignedInfo>
60+
<ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
61+
<ds:SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"/>
62+
<ds:Reference URI="#_b7a3ca0f-25a4-4365-af81-da8f04740564">
63+
<ds:Transforms>
64+
<ds:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
65+
<ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
66+
</ds:Transforms>
67+
<ds:DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/>
68+
<ds:DigestValue>5uICLRmnTHr/Ma7+uphAjCf86rmR+P6QELBf2C53mIc=</ds:DigestValue>
69+
</ds:Reference>
70+
</ds:SignedInfo>
71+
<ds:SignatureValue>XT9CguQWKBvbqVsJ+Khu5/eyl09JVhHkUuyFHa98ViZUBVgL/Hc9gzwUr43CA7OVOO+uMfCc6WvPKeADF9w9kqJaUgsi8LiKC/nfDCY6+UiRoep2zmXyFJRAvrD/HbgVfayx/4Nn3ponRPZ/T/oezhimssFF66m+/UAwJekO9kuob+5n+uaOiFOMuHEycSdASH/iFnTSR1ajdo6AaLomG6YT8zJbuRzcKmesouAKPiQCJFt2cgstEs1zw8dvTgmozy4qd/0aMiZ52eGcXoORD8VZOQiY63HT8F4wkhk5eGU05sFcyfpg7dXNtKOfCddHwyngmgmPhpRN30ew5njg7w==</ds:SignatureValue>
72+
<ds:KeyInfo>
73+
<ds:X509Data>
74+
<ds:X509Certificate>MIID+TCCAuGgAwIBAgIUUS6s9Rb+KY0fT0qKKgqPPJij/HMwDQYJKoZIhvcNAQELBQAwgYsxCzAJBgNVBAYTAlVTMR0wGwYDVQQIDBREaXN0cmljdCBvZiBDb2x1bWJpYTETMBEGA1UEBwwKV2FzaGluZ3RvbjEMMAoGA1UECgwDR1NBMRIwEAYDVQQLDAlMb2dpbi5nb3YxJjAkBgNVBAMMHWxvZ2luLmdvdi5pZGVudGl0eXNhbmRib3guZ292MB4XDTI0MDEyMjIwMTcwN1oXDTI1MDQwMTIwMTcwN1owgYsxCzAJBgNVBAYTAlVTMR0wGwYDVQQIDBREaXN0cmljdCBvZiBDb2x1bWJpYTETMBEGA1UEBwwKV2FzaGluZ3RvbjEMMAoGA1UECgwDR1NBMRIwEAYDVQQLDAlMb2dpbi5nb3YxJjAkBgNVBAMMHWxvZ2luLmdvdi5pZGVudGl0eXNhbmRib3guZ292MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAhmcFFn4b56vHlGBQ1Lx6AXz17sqKnCc6sJ+9csP1RtQBI0NpPHB2z9Di1PNk/ElK7V7yh3uMu4FJYw30GZFUl2f/ttsDkNHrwfh/jzbMNjrOSc0P25oem4uOUfeGH9jtMhKa+HZLOaOmcyWFKkYR2mwacEbQJ1CWviHtP8AzHUPSbHklAmusRLuygTjq0+QRJZgSezGqwU1L3ixPq+gMzPtMS+fxsMOVo2eosip440gz4rcqUUogtD2hV8EQi3+GIkGYuMTS81ug/385TCPEhzWMnNmDi3HykOZeRNb4GfCYw0Yx+v+cb7BPD5EdxUHNwliHvSiRAeYqLjBjuNUfKQIDAQABo1MwUTAdBgNVHQ4EFgQUusictYnNM2TbIt5STz2lkYN1sI8wHwYDVR0jBBgwFoAUusictYnNM2TbIt5STz2lkYN1sI8wDwYDVR0TAQH/BAUwAwEB/zANBgkqhkiG9w0BAQsFAAOCAQEATuLF4kHeP7FY9Wzm3DfF+m/5wUhJEtbsF8J9Wq8duhQ4/gtZVJgMDUKLsnSDLCtWiRlsFXquI8tlo32JsVo5NfZI9WYsub7192iCYpqE+x5G+94tt5vAayoF7GKGPxatyldxAQUz7RUzwqas7NCYXQ0p7wZrMqF8z2yvaUgL55v8TJIb7RP+D8b47Cmzx7IYmx3Co30vZWysQe61Bv880hG11YJsBAc0hmyWlokJYZZVm+xcjKkm6aFyyAbeCe0Kh68QU7f9YkpFv/sW2RIvZ/Z0gvxjJE+YJBwOwPDDHdkb0ZmKOJvlaabi5lkTZvUtTHXb5Hu7DxRRt91dm77MlQ==</ds:X509Certificate>
75+
</ds:X509Data>
76+
</ds:KeyInfo>
77+
</ds:Signature>
78+
<Subject>
79+
<NameID Format="urn:oasis:names:tc:SAML:2.0:nameid-format:persistent">34abda40-d5aa-4259-9f17-a3757fd2e094</NameID>
80+
<SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
81+
<SubjectConfirmationData InResponseTo="_bf054c05-5b2c-4773-a6a9-9ba075a87bc9" NotOnOrAfter="2024-09-18T16:23:36Z" Recipient="https://sp.int.identitysandbox.gov/auth/saml/callback"/>
82+
</SubjectConfirmation>
83+
</Subject>
84+
<Conditions NotBefore="2024-09-18T16:20:31Z" NotOnOrAfter="2024-09-18T17:20:36Z">
85+
<AudienceRestriction>
86+
<Audience>urn:gov:gsa:SAML:2.0.profiles:sp:sso:identitysandbox</Audience>
87+
</AudienceRestriction>
88+
</Conditions>
89+
<AttributeStatement>
90+
<Attribute Name="uuid" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" FriendlyName="uuid">
91+
<AttributeValue>34abda40-d5aa-4259-9f17-a3757fd2e094</AttributeValue>
92+
</Attribute>
93+
<Attribute Name="email" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" FriendlyName="email">
94+
<AttributeValue>[email protected]</AttributeValue>
95+
</Attribute>
96+
<Attribute Name="aal" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri" FriendlyName="aal">
97+
<AttributeValue>http://idmanagement.gov/ns/assurance/aal/2</AttributeValue>
98+
</Attribute>
99+
<Attribute Name="ial" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri" FriendlyName="ial">
100+
<AttributeValue>http://idmanagement.gov/ns/assurance/ial/1</AttributeValue>
101+
</Attribute>
102+
</AttributeStatement>
103+
<AuthnStatement AuthnInstant="2024-09-18T16:20:36Z" SessionIndex="_b7a3ca0f-25a4-4365-af81-da8f04740564">
104+
<AuthnContext>
105+
<AuthnContextClassRef>http://idmanagement.gov/ns/assurance/aal/2?phishing_resistant=true</AuthnContextClassRef>
106+
</AuthnContext>
107+
</AuthnStatement>
108+
</Assertion>
109+
```
110+
{% endcapture %}
54111

55112
<div class="grid-row grid-gap">
56113
<div class="desktop:grid-col-7 mobile:grid-col-full">
@@ -114,8 +171,18 @@ A proofed identity request at AAL2, with phishing resistent MFA, for email, phon
114171
<div class="grid-row grid-gap">
115172
<div class="desktop:grid-col-7 mobile:grid-col-full">
116173
<h2 id="authentication-response">Authentication response</h2>
117-
<p>After the user authenticates, Login.gov will redirect and POST a form back to your registered Assertion Consumer Service URL:</p>
118-
<p>The SAMLResponse is a base64-encoded XML payload that contains encrypted data.</p>
174+
<p markdown="1">After the user authenticates, Login.gov will redirect and POST a form back to your registered Assertion Consumer Service URL with a hidden form control named `SAMLResponse`.</p>
175+
<p markdown="1">`SAMLResponse` contains a base64-encoded XML payload that contains data that is encrypted with the service provider's public key.</p>
176+
<p markdown="1"> The decrypted `SAMLResponse` contains a `<saml:Assertion>` element, which in turn contains the following elements: </p>
177+
<dl>
178+
<dt markdown="1">`Subject`</dt>
179+
<dd>Contains the NameID, the Recipient of this information and the validity period.</dd>
180+
<dt markdown="1">`AttributeStatement`</dt>
181+
<dd>All the requested attributes.</dd>
182+
<dt markdown="1">`AuthnStatement`</dt>
183+
<dd>Contains the AAL that was used.</dd>
184+
</dl>
185+
<p>For example: {{ decrypted_response | markdownify }}</p>
119186
<a href="{{ '/saml/logout/' | prepend: site.baseurl }}" class="usa-link margin-top-4 mobile:display-none desktop:display-block">Next step: Logout</a>
120187
</div>
121188
<div class="usa-layout-docs__main code-snippet-column desktop:grid-col-5">

0 commit comments

Comments
 (0)