SAML2 TLDR

I know you’re not here voluntarily - I appreciate that.

If you’re new to SAML2, this is a cheatsheet for you. Some of these facts will save you days of work so read them carefully!

SAML2 document

  • SAML2 is way to convey user data between systems

  • If you want to send a user’s details to another system, SAML2 is the standard you can use

  • Alternatives exist for SAML2 (Oauth2)

  • SAML2 is 2005 tech but today, many systems still rely on it (incl. Azure)

  • The SAML2 document has no nesting - it usually has a signature and issuer data and a bunch of assertions which is basically user data

SAML2 decoding

  • SAML2 documents received over the wire are base64 encoded - this has nothing to do with encryption and saml2 signatures

SAML2 decryption / encryption

  • Decryption has nothing to do with SAML2 signatures

  • If a SAML2 document has encrypted content (EncryptedAssertion), its signature must be checked before it is decrypted

  • You cannot decrypt a document that was encrypted with the public key, without a private key

  • You cannot decrypt a document that was encrypted with the private key, without the public key

  • If you can decrypt it doesn’t mean you can trust it

SAML2 signatures

  • SAML2 documents have signatures

  • Signatures verify, that the document is coming from a trusted source

  • The document level signature check will not pass after the document has been decrypted

  • The assertion level signature checks will not pass if the pre-decryption document level signature hasn't been removed

  • The signature element contains a Reference-infromation, which tells you what the signature should be checked against

  • SAML2 documents can have signatures in two levels: The entire document might have a signature, or just the assertions might have signatures or both.

  • SAML2 document level signature must be checked before decrypting

  • Document signing technology can vary between platforms and cause signature check failures (see: Wikipedia: XML signatures)

  • Document signing technology sucks (stackoverflow to the rescue)

All types of SAML2 documents:

  • unencrypted, unsigned document with unsigned assertions

  • unencrypted, unsigned document with signed assertions

  • unencrypted, signed document with unsigned assertions

  • unencrypted, signed document with signed assertions

  • encrypted, unsigned document with unsigned assertions

  • encrypted, unsigned document with signed assertions

  • encrypted, signed document with unsigned assertions

  • encrypted, signed document with signed assertions

SAML2 metadata

  • The metadata file tells you, what services are using the identity provider, your client should validate against this document in some scenarios

SAML2 message types

There are 4 different message types in SAML2

XSD schemas for all message types can be found online.

  • A request you send to the IDP that you want to authenticate AuthNRequest

  • A response you receive from the IDP that you were authenticated AuthNResponse

  • A request you send to the IDP that you want to log out SamlLogoutRequest

  • A response you receive from the IDP that you were logged out SamlLogoutResponse

SAML2 client implementation:

Do not simply copy other implementations, also consider the specification

The thing with SAML2 client implementations that are circulating around, is that they have a risk of being informed by each other rather than the specification, which leads to a high risk of blind spots.

Verify that your code is compliant with the SAML Security OWASP cheatsheet.

To implement a SAML2 client, you need to implement 4 endpoints / APIs / backend functions:

  • Endpoint that receives the initial request from your user and redirects their browser to the identiy provider of choice

  • Endpoint that receives the response (redirect) that the IDP sends back to your website after authenticating them and authenticates them using data data in the local domain as well (auth/idp/signin)

  • Endpoint that receives the request from the user to perform a logout and redirects the user to the identity provider for a logout operation (auth/idp/logout)

  • Endpoint that receives the response (redirect) that the IDP performs back to your website after logging them out of the IDP and then logs them out in the local domain as well (auth/idp/logoff)

Lari TuomistoSAML, SAML2, cheatsheet, beginner, getting startedKommentoi