SSOReady concepts: SAML Connections
Understanding SAML Connections in SSOReady
SAML connections store the SAML-related configuration that SSOReady needs to implement the SAML protocol on your behalf.
Every SAML connection belongs to exactly one organization. Organizations in turn belong to exactly one environment. You can have any number of SAML connections within an organization. Up to one SAML connection per organization can be primary.
The SAML protocol is designed such that your customer needs to put a SAML connection’s service provider configuration into their identity provider. Your customer also needs to give you settings that you put into the SAML connection’s identity provider configuration. When you use SSOReady’s self-service SAML configuration, your customer can securely do this configuration for you, without any work on your part.
Properties
SAML Connection ID
Every SAML connection has an ID starting with saml_conn_..., for example:
SAML connection IDs are universally unique.
Primary
Up to one SAML connection within an organization can be marked as “primary”.
A primary SAML connection works exactly like any other SAML connection,
but with one special behavior for your convenience: when you initiate a SAML
login, you can provide an
organizationExternalId
or
organizationId.
When you do so, the primary SAML connection of that organization gets used to do
the SAML login.
If none of the SAML connections in an organization are marked as primary, SAML
initiations using organizationExternalId or organizationId for that
organization will return an error from SSOReady’s API. The
solution is to mark one of the SAML connections as primary, or to pass a
samlConnectionId
instead.
Most of your customers will likely have exactly one SAML connection in their organization, but very large organizations often use multiple identity providers. For example, a conglomerate may buy your product for their entire workforce, but their subsidiaries use different identity providers. In that case, that conglomerate will have multiple SAML connections. Typically, they’ll have one SAML connection that is the “most important” one, which will be the one marked as primary.
Don’t worry too much about customers having multiple identity providers. SSOReady supports IDP-initiated SAML, which you can use as an “escape hatch” for complex scenarios.
Service Provider Configuration
SAML is intrinsically designed such that the connection between a “service provider” (your application) and an “identity provider” (your customer’s Okta/Google/Entra/etc.) is configured ahead of time. SAML requires that the SP and IDP exchange some details about one another before attempting to use SAML.
This exchange of details is commonly referred to as “configuring SAML”, and happens outside of the SAML protocol. Historically, it’s been done over email or support ticket. If you use SSOReady’s self-service SAML configuration, your customer can configure SAML without any work on your part.
Service provider configuration is the set of settings that SSOReady assigns on your behalf. These are settings that your customer ultimately needs to put into their identity provider for SAML to work.
Assertion Consumer Service (ACS) URL
A SAML Assertion Consumer Service URL is an HTTP endpoint that a SAML identity provider sends SAML assertions to. A SAML assertion is essentially a cryptographically authenticated message that tells the service provider who someone is.
SSOReady assigns the ACS URL on your behalf, and runs the HTTP endpoint for you. SSOReady handles authenticating the legitimacy of messages sent to the ACS URL for you. By default, the ACS URL looks something like:
If you use a custom domain for auth.ssoready.com, then the ACS URL will
instead look like:
Where auth.yourcompany.com is your custom auth.ssoready.com domain.
SP Entity ID
A SAML service provider (“SP”) entity ID is a unique identifier for the service provider. Identity providers include the SP entity ID in their assertions, and service providers check for this unique identifier to make sure the message was intended for them.
SSOReady verifies for you that SAML assertions have the correct SP entity ID as a guard against SAML replay attacks, wherein an attacker sends a legitimate SAML assertion meant for one service provider to your application instead. By default, the SP Entity ID looks something like:
If you use a custom domain for auth.ssoready.com, then the ACS URL will
instead look like:
Where auth.yourcompany.com is your custom auth.ssoready.com domain.
Identity Provider Configuration
Identity provider configuration is the set of settings that your customer’s identity provider assigns. These settings need to be inputted into SSOReady.
If you use SSOReady’s self-service SAML configuration, your customer can securely input these details into SSOReady without any work on your part.
IDP Entity ID
A SAML identity provider (“IDP”) entity ID is a unique identifier for the identity provider. Identity providers include the IDP entity ID in their assertions, and service providers check for this unique identifier as part of making sure the message is sent from the appropriate identity provider.
SSOReady verifies for you that SAML assertions have the correct IDP entity ID.
Because the IDP entity ID is assigned by your customer’s identity provider, its format will depend on which vendor they use.
Redirect URL
A SAML redirect URL is an HTTP endpoint that a service provider sends SAML authentication requests to. A SAML authentication request is a way for a service provider to kick off a SAML login. When you use SSOReady to initiate a SAML login, SSOReady sends a SAML authentication request on your behalf.
Because the redirect URL is assigned by your customer’s identity provider, its format will depend on which vendor they use.
Certificate
A SAML identity provider certificate is an X.509 certificate that an identity provider uses to cryptographically sign SAML assertions they send to the ACS URL. Service providers use the identity provider certificate to authenticate that the identity provider really sent the message.
SSOReady verifies for you that the SAML assertion is correctly signed by the correct IDP certificate.
Every SAML connection has a different IDP certificate. It is assigned by the
identity provider. Its value is not secret or sensitive. SSOReady displays the
IDP certificate as a
PEM-encoded
CERTIFICATE block containing a
DER-encoded
RSA public key.
These look like:
When using the SSOReady Management API, you will need to use this format when working with SAML connections.
Identity providers output the IDP certificate in various formats. If you use SSOReady’s self-service SAML configuration, your customer can securely input their certificate into SSOReady in the format their identity provider defaults to, without any work on your part.