Single sign-on

Configure Single Sign-On (SSO) in Recurly with Okta, Microsoft Entra, or Google — including SAML setup, certificate management, user transitions, and SCIM provisioning for Okta.

Single Sign-On (SSO) lets your team access Recurly using a single set of credentials from your identity provider — no separate Recurly password required. Recurly supports SSO via Okta, Microsoft Entra, and Google, with optional SCIM provisioning for Okta to automate user management.

Not included in Starter or Pro — contact Recurly Sales to upgrade

1Definition 2Key benefits 3Key details 4Set up Okta 5Set up Microsoft Entra 6Set up Google SSO 7Manage users and certificates 8SCIM for Okta 9FAQs and troubleshooting

Limitations

User provisioning: New users must be added manually in Recurly before they can authenticate via SSO for Microsoft Entra and Google. For Okta, user provisioning can be automated via SCIM — contact [email protected] for details.
Supported identity providers: Recurly SSO currently supports Okta, Microsoft Entra, and Google. Contact [email protected] to discuss other providers.
SCIM for Okta is available on request — contact your Recurly account manager or [email protected] for details.

Definition

Single Sign-On (SSO) is a user authentication method that allows a user to access multiple applications with one set of login credentials. In Recurly, SSO authentication is handled by your identity provider (Okta, Microsoft Entra, or Google) — reducing password sprawl, streamlining access management, and improving security across your team.

Key benefits

Enhanced security Reduce the number of passwords in use across your organization, minimizing the risk of password-related security breaches.

Streamlined access management One set of credentials for multiple applications means simpler access management and a smoother experience for your team.

Flexible identity provider support Supports Okta, Microsoft Entra, and Google — giving you flexibility to use your existing identity infrastructure.

Key details

Key principles

One-to-one relationship — Each Recurly user must have a corresponding account in the identity provider. A user can't use two different identity providers for the same Recurly account. For access to multiple Recurly sites via different providers, separate Recurly accounts are required.
User ID matching — The email address registered in Recurly must exactly match the email in your identity provider. Update the Recurly user email first if they differ.
Site-level configuration — SSO is configured per site. If a user is associated with multiple sites, the first site that requires SSO determines which identity provider and configuration the user must use.
Access control is separate — SSO handles authentication only. Once logged in, users have access to all Recurly sites associated with their account.
SSO replaces two-factor authentication — When a user switches to SSO, Recurly's two-factor authentication is disabled for that account.
Limited provider support — Only Okta, Microsoft Entra, and Google are currently supported. Contact [email protected] for other providers.

SSO certificates

Your identity provider generates an SSO public certificate used to sign and encrypt SAML responses between Recurly and your IdP. This certificate verifies that login requests are from the correct source and haven't been tampered with.

If the certificate expires and isn't updated, SSO users will be unable to log in. To find the expiration date, go to Admin → SSO Settings in Recurly — the expiration date is displayed alongside the certificate. Renew the certificate before it expires to avoid login disruptions.

Set up Okta

Step 1: Add the Recurly app in Okta

Open the App Catalog

As an Okta Administrator, go to Admin → Applications → Applications and click Browse App Catalog. Search for "Recurly."

Add the integration

Select Recurly from the results and click Add Integration. Under General Settings, set the application name and click Next.

Set the Default Relay State

Under Sign-On Options, set the Default Relay State to your Recurly site's subdomain (subdomain only — not the full URL). Find your subdomain under Configuration → Site Settings.

Upload the Recurly certificate

Get a copy of the certificate from [email protected] and upload it in this step.

Set the application username format

Select Email for the Application username format and click Done.

Assign the Recurly app to users

Assign the Recurly app to the appropriate users in Okta.

Step 2: Configure SAML credentials in Recurly

Get the metadata from Okta

In Okta, click the Sign On tab and then More Details to see the SAML metadata.

Enable SSO in Recurly

In Recurly, go to Admin → SSO Settings. Set Status to Enabled and Provider to Okta.

Copy the metadata to Recurly

Transfer the Okta metadata to Recurly SSO Settings using the field mapping below.

Okta field	Recurly field
Sign-On URL	Login URL
Issuer	SAML Issuer ID
Signing Certificate	Certificate

Save your changes

Click Save Changes once all fields are filled in.

Log in via SP-initiated SSO

Navigate to https://app.recurly.com/login/sso, enter your email, and click Log In.

Set up Microsoft Entra

Follow Microsoft's Entra Active Directory tutorial for Recurly to configure Microsoft Entra as your identity provider. Contact [email protected] if you need assistance during setup.

Set up Google SSO

Super Administrator permissions in Google Workspace are required for this configuration.

Configure a custom SAML app in Google Admin Console

Add a custom SAML app

In the Google Admin Console, go to Apps → Web and mobile apps. Click Add App → Add custom SAML app.

Name the app

Enter a name and optional description for the SAML app.

Copy the SSO URL and certificate

On the Google Identity Provider details page, copy the SSO URL and download the Certificate. You'll need these for the Recurly configuration.

Configure Service Provider details

On the Service Provider details page, set the following values exactly:

ACS URL: https://app.recurly.com/login/sso
Entity ID: https://app.recurly.com
Signed Response: Uncheck this box — Google won't sign the assertion if it's checked, but Recurly requires the assertion to be signed
Name ID format: EMAIL
Name ID: Basic Information → Primary email

Map the email attribute

On the Attribute mapping page, map Primary email to an app attribute named Email (case-sensitive).

Configure access

Open the SAML app

In the Admin Console, go to Apps → Web and mobile apps and select the SAML app you just created.

Assign user groups

Click User access, then under Groups, select the group to grant access.

NoteEmail addresses used to sign in to the SAML app must match the email addresses used to sign in to the Google domain.

Configure the Recurly app

Open SSO Settings in Recurly

Log into Recurly and go to Admin → SSO Settings.

Enter the SSO values

Set Login URL to the SSO URL copied from Google. Set SAML Issuer ID to https://app.recurly.com (matching the Entity ID from step 4 of the SAML app config). Set Certificate to the downloaded certificate. Toggle Single Sign-On to Enabled.

Save your settings

Click Save.

NoteIf Recurly App-initiated logins fail, confirm that the SAML Issuer ID in Recurly matches the Entity ID in the Google Service Provider details page.

Manage users and certificates

Finalize SSO settings after setup

After completing your identity provider configuration, enable SSO in Recurly:

Go to Admin → SSO Settings.
Click the Enabled radio button.

Once SSO is enabled, new user invitations automatically require SSO by default.

Existing usersEnabling SSO doesn't immediately affect existing users. To require SSO for existing users, update their settings manually using the steps below.

Transition an existing user to SSO

Open the user's profile

Navigate to the Users page on your Recurly site and select the user.

Enable SSO for the user

Click the Single Sign-On radio button. If the user has 2FA enabled, you'll be prompted to confirm disabling it.

After saving, Recurly logs the user out, sends them an email notification that SSO is now required, and the user can log back in via https://app.recurly.com/login/sso, the link in the notification email, or their identity provider's Recurly tile.

The Security column on the Users page shows each user's authentication method: SSO, 2FA, or blank (email and password only).

Invite a new user with SSO

With SSO enabled, new invitations default to requiring SSO. To invite a new user:

Send the invitation with the SSO option selected.
Ensure the user also has access to Recurly through your identity provider.
The user receives an email invitation and, upon accepting, is notified that SSO is required.

Remove SSO from an existing user

Open the user's profile

Navigate to the site requiring SSO for the user, then go to the Users page and click Edit for that user.

Change to password only

Set Account Security to Password only and confirm the action.

After saving, Recurly logs the user out and sends them an email with a link to reset their password.

Disable SSO for the site

Open SSO Settings

Navigate to the site, go to the Users page, and click Configure Single Sign-On.

Disable SSO

Select the Disable radio button and save. Confirm when prompted.

All SSO users are logged out, notified by email, and prompted to create a new password.

Update your SSO certificate

Okta

Generate a new certificate

In Okta, open the Recurly application, go to the Sign On tab, scroll to SAML Signing Certificates, and click Generate new certificate.

Activate the new certificate

Under Actions, activate the new certificate. The old certificate will show as Inactive.

Update Recurly

Download the new certificate under Actions and paste it into the Certificate field in your Recurly SSO Settings.

Microsoft Entra

See Microsoft's certificate management documentation for Entra.

Google

See Google's SSO certificate rotation documentation.

SCIM for Okta

SCIM (System for Cross-domain Identity Management) lets you automate user provisioning and deprovisioning in Recurly via Okta. Supported features include creating users, deactivating users, and group push.

Configure SCIM in Recurly

Open SSO Settings

In Recurly, navigate to Admin → SSO Settings.

Enable SCIM provisioning

Select Enable under SCIM Provisioning.

Set the initial provisioning role

Select a default role for new users provisioned via SCIM. This role can be updated after provisioning. It's recommended to create a dedicated role with appropriate permissions rather than using Site Admin as the default.

Save and copy the API token

Click Save Changes. Click the icon at the end of the API Token field to reveal it, then copy the token.

Configure SCIM in Okta

Open the Provisioning tab

In Okta, navigate to the Recurly SAML App and click the Provisioning tab.

Configure API integration

Click Configure API Integration, then Enable API Integration. Paste the Recurly API token into the API Token field.

Test and save

Click Test API Credentials. After a successful test, click Save.

Enable Create Users and Deactivate Users

Under To App, click Edit, enable Create Users and Deactivate Users, then click Save.

Once configured, users assigned to the Recurly app in Okta receive an invitation to the Recurly site. Users unassigned from the Recurly app in Okta are removed from the site.

SCIM group support

Configure groups in Okta

Create a group in Okta

Open the Okta Admin portal, expand Directory, click Groups, and create a new group.

Push the group to Recurly

Go to Applications → Applications, select the Recurly app, click Push Groups → Find Groups by Name, and select each group you want to push.

NoteGroups pushed via Push Groups should not also be assigned directly to the application — see Okta's documentation on Group Push limitations for details.

Pushed groups appear in Recurly prefixed with SCIM_.

Default permissionsWhen a group is first pushed to Recurly, the corresponding role is created with Customer Read Only permissions. Update the role's permissions in Recurly before assigning users.

Set group permissions in Recurly

Open the role in Recurly

Go to Admin → Roles and select the role that was pushed from Okta.

Edit permissions

Click Edit and assign the appropriate permissions.

Group notesGroups created from Okta can only be renamed and deleted from Okta when SCIM provisioning is enabled. Assign users to only one group — users assigned to multiple groups inherit only the permissions of the last group assignment.

Assigning and removing users

Assign users by adding them to the Recurly Okta App individually or through a group. Users are assigned the default SCIM role unless using Group Push, in which case they receive the corresponding role.

Remove users by unassigning them from the Recurly Okta App (individual) or removing them from the assigned group. Unassigning an entire group removes all users in that group from Recurly.

Changing a user's role

To change a user's role via groups: remove the user from their current pushed Okta group (their role reverts to the default SCIM role), then assign them to the pushed group corresponding to the target role.

Removing pushed groups

Unlink and delete the pushed group to delete the corresponding Recurly role — affected users revert to the default SCIM role. This is the recommended approach.
Unlink and leave the pushed group to preserve the Recurly role and keep affected users on their current permissions.

Migrating existing users to SCIM

After enabling SCIM, existing users assigned to the Recurly Okta Integration app need to be migrated — Okta only recognizes users as provisioned after SCIM is enabled.

To migrate: unassign and then reassign the users to the Recurly Okta Integration app. Unassigning won't remove them from Recurly since Okta doesn't recognize them as provisioned yet. During the brief window between unassigning and reassigning, users won't be able to log in. Once reassigned, Okta triggers a provisioning request — since the user already exists in Recurly, this is a no-op and the user's existing role is preserved.

A user's role only changes via SCIM migration if they're a member of a pushed Okta group.

FAQs and troubleshooting

I'm trying to log in at https://app.recurly.com/login but keep getting an email/password error. What should I do?

SSO users must log in at https://app.recurly.com/login/sso or via their identity provider — not the standard login URL.

I'm trying to log in at https://app.recurly.com/login/sso but get an invalid email error. How do I fix this?

You may be entering the wrong email address, or your account may not be configured for SSO. Contact your site administrator or [email protected] for help.

I'm trying to log in to a new site but get an error that I must first accept the invitation. What should I do?

Check your email for an invitation from Recurly and click the Accept invitation link. If you didn't receive it, check your spam folder or ask your site administrator to resend the invitation.

I'm logging in via my identity provider but get an 'invalid login' error on the Recurly side. What could cause this?

Verify that your Recurly account is configured to use SSO and that Recurly is expecting you to sign in via the identity provider you're using. If everything looks correct but login still fails, ask your site administrator to reset your account to password-only and then re-enable SSO.

Updated 5 days ago

Did this page help you?