SAML 2.0
Configure SAML 2.0 single sign-on for your Recomly organization.
SAML 2.0 lets you connect your organization to any SAML-compatible identity provider (IdP) — including Okta, Microsoft Entra ID (Azure AD), OneLogin, and others. When SSO is configured, users whose email domains match the provider are redirected to your IdP to sign in.
Service provider metadata
When configuring the integration in your IdP, use the following values. These are fixed per environment and do not change between providers.
| Field | Value |
|---|---|
| ACS URL (Reply URL) | Shown on the Single Sign-On page under Configure these values in your Identity Provider |
| Entity ID (Audience URI) | Shown on the Single Sign-On page under Configure these values in your Identity Provider |
| Recipient | Same as the ACS URL |
| Name ID format | Email address |
Retrieve the exact ACS URL and Entity ID from the Single Sign-On page in your account settings.
Required attribute
Your IdP must send the user's email address in the SAML assertion. Map the email attribute to the following claim URI:
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddressMost enterprise IdPs support this claim URI natively. Refer to your IdP's documentation if you need to create a custom attribute mapping.
Setup guide
Step 1 — Get your SP metadata
Go to Security → Single Sign-On and click Add Provider. Select SAML 2.0 as the provider type. Note the ACS URL and Entity ID shown in the blue info card — you will need these to create the application in your IdP.
Step 2 — Create an application in your IdP
In your identity provider, create a new SAML application. Use the values from Step 1:
- ACS URL / Reply URL — the ACS URL from Step 1
- Entity ID / Audience URI — the Entity ID from Step 1
- Name ID format — email address
- Attribute mapping — map the user's email to
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
Assign the application to the users or groups that should have access to Recomly.
Step 3 — Upload your IdP metadata
Once the application is created, your IdP will provide a federation metadata XML file. In Recomly:
- Go to Security → Single Sign-On and click Add Provider.
- Select SAML 2.0 as the provider type.
- Click Upload XML and select the metadata file downloaded from your IdP.
Step 4 — Configure email domains
Add the email domains whose users should be routed to this provider (e.g. acme.com). When a user enters their email on the sign-in page, Recomly matches the domain to the correct SSO provider. Domains must be unique across all providers in your organization.
Step 5 — Enable and save
Toggle Provider enabled on, then click Create Provider. Test by signing in with an account from your IdP to verify the connection before rolling it out to your team.
Updating the configuration
To update a provider (for example, when IdP certificates rotate), go to Security → Single Sign-On, click the edit icon next to the provider, and upload the new metadata XML. Saving overwrites the existing configuration. SSO remains active during the update with no downtime for users already authenticated.
Removing SAML SSO
To remove a provider, click the delete icon next to it on the Single Sign-On page and confirm. This immediately disables SSO for the associated domains and removes the provider configuration.
Sign-out behavior
When a user signs out, their active Cognito session is terminated and they are redirected to the Recomly login page.
The IdP-side session (the session your identity provider holds) is not automatically cleared at sign-out. This means a user who signs out and immediately returns may be silently re-authenticated by their IdP without being prompted to enter credentials again. This is a known limitation of Cognito-federated SSO for both SAML and OIDC. To fully end the IdP session, the user should close their browser.