A SAML login flow is an audit log of a single time one of your users attempted to log in via SAML. SAML login flows track the timestamp and details of every step in the SAML protocol.

A SAML login flow belongs to exactly one SAML connection.

Properties

SAML Login Flow ID

Every SAML login flow has an ID starting with saml_flow_..., for example:

saml_flow_c2nrnid1sr9nexrqorczyxqpb

SAML login flow IDs are universally unique.

Start Time

A SAML login flow’s start time tracks when the login process began. For SP-initiated flows, this tracks when your application initiated a SAML login. For IDP-initiated flows, this tracks when the identity provider redirected the user to the SAML connection’s ACS URL.

Last Activity Time

A SAML login flow’s last activity time tracks the last time any progress has happened on the SAML login flow. It’s equal to the timestamp of the latest event in the SAML login flow’s event log.

Status

A SAML login flow can be in one of three states:

• Succeeded SAML login flows are ones where your application handled the SAML login, by calling the Redeem SAML Access Code endpoint.
• Failed SAML login flows are ones where the identity provider provided an invalid SAML assertion. Failed SAML login flows have error details.
• In Progress SAML login flows aren’t succeeded or failed yet. The user may still be navigating their identity provider, and the SAML login flow may still yet succeed or fail.

State

A SAML login flow’s state is the state you provided to the “Get SAML Redirect URL” endpoint.

You can do anything you like with this state, but the most common use-case is to keep track of where to redirect your user back to after logging in with SAML.

If your user logged in to your product using Identity Provider-initiated SAML (e.g. they clicked on your app inside their corporate Okta dashboard), then this state will be empty.

SSOReady validates the authenticity of non-empty state values. You do not need to implement your own CSRF on top of it, but doing so anyway will have no bad consequences.

Under the hood, SSOReady uses a SAML RelayState to implement this functionality.

User Email

Successful SAML login flows keep track of the end user’s email address.

SSOReady always validates these email addresses against the appropriate organization’s domains. If the identity provider sends an email address outside the list of allowed domains, the SAML login flow have an email outside organization domains error.

User Attributes

Successful SAML login flows keep track of arbitrary user attributes an identity provider passed along about an end user.

These attributes are always a mapping of keys and values. User attribute keys and values are both guaranteed to be strings.

Error Details

When a SAML login flow fails, SSOReady will include details about the problems with that SAML login flow.

SAML Connection Not Fully Configured

SSOReady can’t securely authenticate logins for a SAML connection if any of the following haven’t been configured:

• IDP Entity ID
• IDP Redirect URL
• IDP Certificate

If you initiate a SAML login against a SAML connection that doesn’t have these IDP-related settings configured, then you will get an error about the SAML connection not being fully configured.

To fix this error, you need to configure all the IDP-related settings on the SAML connection.

Environment OAuth Redirect URI Not Configured

This error will only ever arise if you’re using SAML-over-OAuth. SSOReady can’t carry out SAML-over-OAuth if you haven’t configured an OAuth Redirect URI.

If you initiate a SAML-over-OAuth login against a SAML connection belonging to an environment lacking an OAuth Redirect URI, then you will get an error.

To fix this error, you need to configure an OAuth Redirect URI on the environment.

Unsigned Assertion

SSOReady requires that SAML assertions be cryptographically signed. Most identity providers do so by default, but some can be configured to not do so.

To fix this, your customer must change their identity provider settings to sign assertions.

Bad Issuer

Every SAML assertion includes an “issuer”. This needs to correspond to the SAML connection’s IDP Entity ID. If the SAML assertion’s <saml2:Issuer> element isn’t the same as the expected IDP entity ID, then SSOReady will reject the SAML assertion.

To fix this, you need to update the SAML connection’s IDP entity ID to be the expected value. You can’t ask your customer to change their identity provider’s entity ID; that’s not a setting most identity providers allow users to configure.

Bad Audience

Every SAML assertion includes an “audience”. This needs to correspond to the SAML connection’s SP Entity ID. If the SAML assertion’s <saml2:Audience> element isn’t the same as the expected SP entity ID, then SSOReady will reject the SAML assertion.

To fix this, you need to have your customer update their identity provider settings to provide the correct SP Entity ID.

Bad Signature Algorithm

Every SAML assertion specifies the cryptographic algorithm used to verify its authenticity. This information is listed in the <ds:SignatureMethod> of the assertion.

If a SAML assertion uses any signature algorithm other than RSA PKCS #1 v1.5 (identified in SAML as http://www.w3.org/2001/04/xmldsig-more#rsa-sha256), then SSOReady will reject the SAML assertion.

The most common way this issue arises is when an Identity Provider is configured to sign messages using RSA-SHA1. SSOReady does not honor SHA1; though SHA1 was considered acceptable when SAML was initially released, it is generally not considered secure enough for cryptographic signatures today.

To fix this, your customer must change their identity provider settings to use RSA-SHA256 as the signature method.

Bad Digest Algorithm

Every SAML assertion specifies the digest algorithm used to verify its authenticity. This information is listed in the <ds:DigestMethod> of the assertion.

If a SAML assertion uses any digest algorithm other than SHA-256 (identified in SAML as http://www.w3.org/2001/04/xmlenc#sha256), then SSOReady will reject the SAML assertion.

The most common way this issue arises is when an Identity Provider is configured to compute message digests using SHA1. SSOReady does not honor SHA1; though SHA1 was considered acceptable when SAML was initially released, it is generally not considered secure enough for cryptographic signatures today.

To fix this, your customer must change their identity provider settings to use SHA256 as the digest method.

Bad Certificate

Every SAML assertion indicates the certificate that should be used to verify its authenticity. SSOReady does not ever use this end-user-provided certificate directly, because it’s untrusted. Only the certificate you configured on the SAML connection is used to authenticate SAML assertions.

If a SAML assertion has a <ds:X509Certificate> that isn’t identical to the certificate you configured on the SAML connection, then SSOReady will reject the SAML assertion.

The most common way this issue arises is when your customer rotates the certificate in their identity provider. In that case, their identity provider will send requests with the new certificate, but SSOReady will still expect the old certificate.

To fix this, you need to update the SAML connection’s identity provider certificate.

Email Outside Organization Domains

SSOReady applies an additional layer of security on top of the traditional SAML security model: before accepting a SAML login, SSOReady verifies that the user’s email is within the parent organization’s whitelist of domains.

SSOReady does this check for you to mitigate the fact that your customers can put whatever emails they please into their identity provider. Without SSOReady’s domain check, a malicious customer (or one of their disgruntled IT admins) could send you SAML assertions that contain the email addresses of a different customer. A simple whitelist of domains that an organization is allowed to log in as prevents this type of attack.

If your customer is sending you legitimate SAML assertions that fail because of the domain whitelist, you can fix that by adding the legitimate email address’s domain to the domain whitelist.

Event Log

Every SAML flow has an event log that will contain up to four elements:

Requested SAML Redirect URL

Represents when you called the Get SAML Redirect URL endpoint, and the URL you got back from that call.

Initiated SAML Flow

Represents when your end user visited the redirect URL, and the SAML authentication request that SSOReady sent their identity provider.

Received SAML Assertion

Represents when your user was redirected from their identity provider back to SSOReady. Contains the SAML assertion SSOReady received from the identity provider.

Redeemed SAML Access Code

Represents when your application called the Redeem SAML Access Code endpoint. Contains the data your application got back from that API call.