SAML Security Considerations
Learn about additional SAML features that WorkOS supports.
SAML requests and responses each have their own unique confidentiality and integrity features. To use SAML with WorkOS, the only requirement is that the Identity Provider (IdP) signs the assertions within the SAML authentication response.
However, you may have customers that have stricter configuration requirements or you may simply want to raise the security bar by following recommendations. This document details what security features are available, how they can benefit you, your customer and their identity provider.
The parties involved in a SAML authentication request and response flow are:
- Identity Provider
- Service Provider (SP)
- User Agent, i.e. a browser
The SAML authentication request is a way for the SP to request confirmation that the user they’re presented with is who they’re claiming to be. It is relayed to the IdP via the user agent.
To address the opportunity to spoof or tamper with a SAML request to the IdP, the IdP may require that all SP’s sign the request. To accommodate this there needs to be a pre-existing relationship between the SP and IdP where a key-pair is shared. The IdP holds the public key (for verifying the request) and the SP holds the private key (for signing the request).
WorkOS recommends SAML request signing, this is especially important in cases where HTTPS is terminated or interrupted prior to reaching the IdP.
All of our requests embed the <IssueInstant> timestamp to allow the IdP to reject stale requests, however to mitigate tamper of this value request signing must be used.
(See SAML 2.0 Security Considerations sections 5.2.1.2, 6.5.1 for more detail).
WorkOS supports SAML request signing for all compatible connection types. Please contact WorkOS support to enable it.
The SAML response is an XML document provided by an IdP containing details about a user so that an SP can authenticate them. It is relayed to the SP via the user agent.
For reference in understanding the following features, below is a simplified hierarchy of the XML elements in a SAML Response:
This is required by WorkOS for all SAML connections. It is a core requirement for SAML IdPs to implement as of SAML 2.0 (see SAML 2.0 Profiles section 4.1.3.5).
Signed response assertions are enabled in the setup steps when you create a SAML connection.
This is the complete signature over the SAML response payload. In combination with an assertion signature it will provide additional integrity protection and is recommended by WorkOS (For details on threats addressed see SAML Security Considerations sections 7.1.1.6, 7.1.1.7).
Please contact WorkOS support to enable signed response message envelope.
The SAML assertions in the SAML response may contain sensitive data, and therefore there is an option to encrypt them to preserve confidentiality.
This feature is recommended in scenarios where the SAML response travels through HTTPS termination, so that accidental logging of sensitive data can be mitigated.
Please contact WorkOS support to enable encrypted response assertion.
The attribute statement is a sub-element of the assertion, some or all of the attributes in the statement can be encrypted as part of the SAML authentication protocol.
WorkOS does not currently support encrypted response attributes. It is recommended to use assertion encryption to envelope all the attributes if confidentiality is required.
This document offers guidance to integrate Single Sign-On with our standalone API into your existing auth stack. You might also want to look at User Management, a complete authentication platform that leverages Single Sign-On functionality out of the box, following best practices.