Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Describe the SAML Response in greater detail #497

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
Open

Describe the SAML Response in greater detail #497

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
c11a10a
Describe the SAML Response in greater detail
vrajmohan Sep 19, 2024
87b0cc7
Use abridged instead of elided
vrajmohan Sep 20, 2024
1851500
Try to retain XML formatting
vrajmohan Sep 20, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
68 changes: 39 additions & 29 deletions _includes/snippets/saml/auth/response_example.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,44 +1,54 @@
{% capture example %}
```xml
<samlp:Response ID="_b28d50c0-dc35-0134-96f3-06d8bac14e9d"
Version="2.0"
IssueInstant="2017-02-23T20:36:37Z"
Destination="https://sp.int.identitysandbox.gov/auth/saml/callback"
Consent="urn:oasis:names:tc:SAML:2.0:consent:unspecified"
InResponseTo="_6fca7b78-9ab7-49f5-bd62-18c48eac3c68"
xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol">
<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">
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[Question] Are the Response attributes intentionally placed on a single line? Is there a benefit over the existing layout?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It wasn't intentional. It is what SAML Tool's XML formatter gave me. It does substitute vertical scrolling (which I prefer) for horizontal scrolling. Do we have a preference?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good question, I only noticed that it was a change. I don't think either way is particularly readable.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In my opinion, the horizontal scrolling is better as it allows you to understand the structure from the "pretty-printed" indentation. Would anyone else like to weigh in with their opinions?

Note: Existing content in https://developers.login.gov/saml/authentication/#example-specifying-ial-aal-and-attributes follows horizontal scrolling.

<Issuer xmlns="urn:oasis:names:tc:SAML:2.0:assertion">https://idp.int.identitysandbox.gov/api/saml</Issuer>
<samlp:Status>
<samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success"/>
</samlp:Status>
<EncryptedAssertion xmlns="urn:oasis:names:tc:SAML:2.0:assertion">
<EncryptedData xmlns="http://www.w3.org/2001/04/xmlenc#" Id="ED" Type="http://www.w3.org/2001/04/xmlenc#Element">
<EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#aes256-cbc"/>
<ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
<EncryptedKey xmlns="http://www.w3.org/2001/04/xmlenc#" Id="EK">
<EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p"/>
<ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
<ds:KeyName/>
<ds:X509Data>
<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>
</ds:X509Data>
</ds:KeyInfo>
<CipherData>
<CipherValue>yaI+Z9oWcrP2WL02UdN7wdeoloWSBuz4nrFKh+vuyHitlk3A3/ATy4rtHerREue6uEYJ2sr7RoJbF/pqsr1j2ZWGJRL9FS++i0biE9iv3NwrW1MDvzGAaMiI9q+tmDqhorftiD+0byrtftZU2Emmwz34/bZJQKFszDeWlDrTVIXGDz+jF0Q+AvFxtaMrXXw6VmLlQlM/Hc9GiGCY+yalGmlteAJD+xk9aqUqfO9+qbwqufLQTpLyM8UdjHuwN9V4ZEo09er34SZD3ZhGq7IdWvROpcPeagU2+r6pivCmhY3x1t01uDtKe0jDt8LTGA1/P8atB3zQHkNnbGO1CiBKpg==</CipherValue>
</CipherData>
<ReferenceList>
<DataReference URI="ED"/>
</ReferenceList>
</EncryptedKey>
</ds:KeyInfo>
<CipherData>
<CipherValue>vy4Ohper0Oq24kU9GBTr0L8dHSBLkRpeu/iNr790cOQrAKphfPRCtLR7RHFI0mTCiko+Wy/oQqX4gu0LVtOOkcjJIicDyuWhIF6guUHvHz1PP4cv3pG++EhAJ73dbCPFSFkrDCzyMM5KZaY0xj6GpcYAVhOjez2ooOqwyTRYVpgozyuIreuooNFV8K++6GixLfBjw9T47eokKqLiROcRjEpV1dBoIkr34KtA7+TCrms1tLwAv4mdzCpUa7j</CipherValue>
<EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#aes256-cbc"/>
<ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
<EncryptedKey xmlns="http://www.w3.org/2001/04/xmlenc#" Id="EK">
<EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p"/>
<ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
<ds:X509Data>
<ds:X509Certificate>
MIIDgDCCAmgCCQCwpieA9CKuDDANBgkqhkiG9w0BAQUFADCBgTEYMBYGA1UEAwwP
U1AgU2luYXRyYSBEZW1vMQwwCgYDVQQKDANHU0ExDDAKBgNVBAsMAzE4ZjETMBEG
<!-- X509Certificate abridged -->
IYOalU+bIBpQt6EGN/mWBu7yZtgxKULZamJUUpd5xpcPcGKwf59etPVMTSxgeeQY
MFjibtIlMmAweHgIqDyF2s8Etz8hlcKrXIUAK5CoMvgUn41V

</ds:X509Certificate>
</ds:X509Data>
</ds:KeyInfo>
<CipherData>
<CipherValue>DUs/UGjZTIioxWuRdUs8dWK4sLZ3zmAoTxX/mxliznXJfKn7JGQ6u9ccAG+o
NbdunEQd0552Y6jdLGTulpuPxgC79gWsgxjV4sZzlALeLKu/VI/gUN7YNaoy
QHQeO0XsH51pu5P4H0fjee2sJ++jnrY4auOMIYE3jWFScmRGrDXnvde6N1MW
QThl1uSu2fDsQZdE9SOzg8rm8c85NcaBorJnHTTt7ywgLSt3weXkztUeujsc
6ifawqRIdfcvL8eZxqKBUHSRu9gIXbmp13VQVZuKHO+MLrO2eTNMS6wRpGjl
Lykqm6G3d8d7gn7oC08WI6YDrB5Kzo6hF/eaveOjtw==
</CipherValue>
</CipherData>
<ReferenceList>
<DataReference URI="ED"/>
</ReferenceList>
</EncryptedKey>
</ds:KeyInfo>
<CipherData>
<CipherValue>cIGCpOu5tXI1RuBj32Sas6saN5brvkYea2QYgIAFNi6NgHngIs4JAkcTGxRg
U9Vyfb2F3kndo5hBJaLmnKjLlwZRCBwoVfYfiaKUumH+igiPeyfcOGi617bN
dpylxgT3Exg/g8qX5V02nIibCvlgO9tm9mPL5Rx0EZ32HMOc+Q62TF7F3e6X
<!-- CipherValue abridged -->
2SWxCSIh0QLjt0Sos4ixK58eYc0p+8wbJnks14GzDGA07qJenT4NKxIIU2wW
y+0Uv+X9Bk3S+y/6ba+v
</CipherValue>
</CipherData>
</EncryptedData>
</EncryptedAssertion>
</samlp:Response>
```
{% endcapture %}
<div markdown="1" data-example="example" class="markdown long">
{{ example | markdownify }}
</div>
71 changes: 69 additions & 2 deletions _pages/saml/authentication.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -51,6 +51,63 @@ A proofed identity request at AAL2, with phishing resistent MFA, for email, phon
</samlp:AuthnRequest>
```
{% endcapture %}
{% capture decrypted_response %}
```xml
<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">
<Issuer>https://idp.int.identitysandbox.gov/api/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/2001/04/xmldsig-more#rsa-sha256"/>
<ds:Reference URI="#_b7a3ca0f-25a4-4365-af81-da8f04740564">
<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/2001/04/xmlenc#sha256"/>
<ds:DigestValue>5uICLRmnTHr/Ma7+uphAjCf86rmR+P6QELBf2C53mIc=</ds:DigestValue>
</ds:Reference>
</ds:SignedInfo>
<ds:SignatureValue>XT9CguQWKBvbqVsJ+Khu5/eyl09JVhHkUuyFHa98ViZUBVgL/Hc9gzwUr43CA7OVOO+uMfCc6WvPKeADF9w9kqJaUgsi8LiKC/nfDCY6+UiRoep2zmXyFJRAvrD/HbgVfayx/4Nn3ponRPZ/T/oezhimssFF66m+/UAwJekO9kuob+5n+uaOiFOMuHEycSdASH/iFnTSR1ajdo6AaLomG6YT8zJbuRzcKmesouAKPiQCJFt2cgstEs1zw8dvTgmozy4qd/0aMiZ52eGcXoORD8VZOQiY63HT8F4wkhk5eGU05sFcyfpg7dXNtKOfCddHwyngmgmPhpRN30ew5njg7w==</ds:SignatureValue>
<ds:KeyInfo>
<ds:X509Data>
<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>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[Nitpick] <ds:X509Certificate> open and close tags could be moved to different lines from the text contents (add linebreaks).

This would make it consistent with response_example.md (I'm also not sure how this affects syntax highlighting)

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'll take a crack at it.

</ds:X509Data>
</ds:KeyInfo>
</ds:Signature>
<Subject>
<NameID Format="urn:oasis:names:tc:SAML:2.0:nameid-format:persistent">34abda40-d5aa-4259-9f17-a3757fd2e094</NameID>
<SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
<SubjectConfirmationData InResponseTo="_bf054c05-5b2c-4773-a6a9-9ba075a87bc9" NotOnOrAfter="2024-09-18T16:23:36Z" Recipient="https://sp.int.identitysandbox.gov/auth/saml/callback"/>
</SubjectConfirmation>
</Subject>
<Conditions NotBefore="2024-09-18T16:20:31Z" NotOnOrAfter="2024-09-18T17:20:36Z">
<AudienceRestriction>
<Audience>urn:gov:gsa:SAML:2.0.profiles:sp:sso:identitysandbox</Audience>
</AudienceRestriction>
</Conditions>
<AttributeStatement>
<Attribute Name="uuid" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" FriendlyName="uuid">
<AttributeValue>34abda40-d5aa-4259-9f17-a3757fd2e094</AttributeValue>
</Attribute>
<Attribute Name="email" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" FriendlyName="email">
<AttributeValue>[email protected]</AttributeValue>
</Attribute>
<Attribute Name="aal" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri" FriendlyName="aal">
<AttributeValue>http://idmanagement.gov/ns/assurance/aal/2</AttributeValue>
</Attribute>
<Attribute Name="ial" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri" FriendlyName="ial">
<AttributeValue>http://idmanagement.gov/ns/assurance/ial/1</AttributeValue>
</Attribute>
</AttributeStatement>
<AuthnStatement AuthnInstant="2024-09-18T16:20:36Z" SessionIndex="_b7a3ca0f-25a4-4365-af81-da8f04740564">
<AuthnContext>
<AuthnContextClassRef>http://idmanagement.gov/ns/assurance/aal/2?phishing_resistant=true</AuthnContextClassRef>
</AuthnContext>
</AuthnStatement>
</Assertion>
```
{% endcapture %}

<div class="grid-row grid-gap">
<div class="desktop:grid-col-7 mobile:grid-col-full">
Expand Down Expand Up @@ -114,8 +171,18 @@ A proofed identity request at AAL2, with phishing resistent MFA, for email, phon
<div class="grid-row grid-gap">
<div class="desktop:grid-col-7 mobile:grid-col-full">
<h2 id="authentication-response">Authentication response</h2>
<p>After the user authenticates, Login.gov will redirect and POST a form back to your registered Assertion Consumer Service URL:</p>
<p>The SAMLResponse is a base64-encoded XML payload that contains encrypted data.</p>
<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>
<p markdown="1">`SAMLResponse` contains a base64-encoded XML payload that contains data that is encrypted with the service provider's public key.</p>
<p markdown="1"> The decrypted `SAMLResponse` contains a `<saml:Assertion>` element, which in turn contains the following elements: </p>
<dl>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[Praise] Description List in the wild! Thanks for using semantic HTML

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm still unhappy about mixing Markdown and HTML.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I find CMSes to be consistently bizarre in their authoring choices. The ones I've seen that are very straightforward for the author tend to be shockingly expensive. (or, I guess, we could just host a wiki)

<dt markdown="1">`Subject`</dt>
<dd>Contains the NameID, the Recipient of this information and the validity period.</dd>
<dt markdown="1">`AttributeStatement`</dt>
<dd>All the requested attributes.</dd>
<dt markdown="1">`AuthnStatement`</dt>
<dd>Contains the AAL that was used.</dd>
</dl>
<p>For example: {{ decrypted_response | markdownify }}</p>
<a href="{{ '/saml/logout/' | prepend: site.baseurl }}" class="usa-link margin-top-4 mobile:display-none desktop:display-block">Next step: Logout</a>
</div>
<div class="usa-layout-docs__main code-snippet-column desktop:grid-col-5">
Expand Down