OIDC
Configure OpenID Connect single sign-on for your Recomly organization.
OpenID Connect (OIDC) lets you connect your organization to any OIDC-compliant identity provider — including Okta, Microsoft Entra ID (Azure AD), Auth0, and others. When SSO is configured, users whose email domains match the provider are redirected to your IdP to sign in.
Redirect URI
When creating the OIDC application in your identity provider, set the redirect (callback) URI to the value shown on the Single Sign-On page under Configure this value in your Identity Provider.
Retrieve the exact Redirect URI for your environment from the Single Sign-On page in your account settings.
Required scopes
The application must request the following scopes:
openid email profileYour IdP must return the user's email address in the ID token or via the UserInfo endpoint.
Client authentication method
Recomly uses client_secret_post to authenticate with the token endpoint. Ensure your IdP application is configured to accept this method (as opposed to client_secret_basic).
Setup guide
Step 1 — Get the redirect URI
Go to Security → Single Sign-On and click Add Provider. Select OIDC as the provider type. Note the Redirect URI shown in the blue info card — you will need this when creating the application in your IdP.
Step 2 — Create an OIDC application in your IdP
In your identity provider, create a new OIDC (or OAuth 2.0) application:
- Application type — Web application
- Redirect URI — the Redirect URI from Step 1
- Grant type — Authorization Code
- Scopes —
openid,email,profile - Client authentication —
client_secret_post
Once created, note the Client ID, Client Secret, and Issuer URL — you will need these in the next step.
Assign the application to the users or groups that should have access to Recomly.
Step 3 — Enter your IdP details
Back in Recomly, fill in the provider fields:
| Field | Description |
|---|---|
| Provider name | A display name for this provider (e.g. Okta, Azure AD). |
| Issuer URL | The base URL of your IdP. Must be a valid HTTPS URL. Used for discovery. |
| Client ID | The client ID assigned to your application by the IdP. |
| Client Secret | The client secret assigned to your application by the IdP. |
| Authorization endpoint | The URL users are redirected to for sign-in. |
| Token endpoint | The URL used to exchange the authorization code for tokens. |
| UserInfo endpoint | The URL used to retrieve profile attributes after authentication. |
| JWKS URI | The URL of the IdP's public key set, used to verify ID tokens. |
Many IdPs publish these endpoint URLs in a discovery document at {issuer}/.well-known/openid-configuration. Click Discover next to the Issuer URL field to auto-populate the endpoint fields.
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 rotating the client secret), go to Security → Single Sign-On, click the edit icon next to the provider, and update the relevant fields. You must re-enter the Client Secret on every save — it is not displayed after the initial configuration.
Removing OIDC 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.