Single Sign-On

Feature Overview

Single sign-on ("SSO") is a service that makes it easier for your employees to access the systems they need to do their jobs, without having to maintain separate usernames and passwords for each system. Your Security team will appreciate knowing that there are fewer passwords floating around, and that it's easier to control who has access to your Recurly data.

Recurly's SSO currently works with three identity providers, Okta, Microsoft Azure, and Google. Your employees login to any of the supported identity providers, and from there they can then access Recurly. Once your employee is logged in, they get access to all of their Recurly sites (as they always have). Deep links to specific accounts, subscriptions, invoices or transactions still work because Recurly also supports an SSO login flow that originates at Recurly (known as "Service Provider initiated login").

📘

Contact Recurly Support to enable Single Sign-On

This feature is available to Recurly customers subscribed to the Professional, Elite, or Enterprise plans. To get access to the feature, please contact Support.

Key principles and assumptions

In order for SSO to work properly, there are some design assumptions that you need to understand.

1. There needs to be a one-to-one relationship between a user's account and their identity provider. i.e. [email protected] cannot use both Okta AND Microsoft Azure as their IdP for SSO. If your company has employees that need to use more than 1 SSO identity provider to access different sites in Recurly, those employees will need to have separate accounts in Recurly ... one for each identity provider.
2. The user ID in Recurly must match the user ID in your identity provider. Recurly uses email address as the user ID, so the email address that Okta, Azure, or Google has for the user must be the same as the email address for the Recurly user. If the two do not match, you can update the user email in Recurly and then enable SSO for the user.
3. You configure SSO at the site-level in Recurly. So if a user is associated with 2 sites, and both require the user to use SSO, the first site to require SSO will "win" and be the site whose SSO configurations define which IdP / SSO the user will be required to use.
4. SSO controls the authentication to Recurly App, it does not govern which sites the user gets access to once they are logged in. So if a user is using SSO and is associated with multiple sites in Recurly, once they are logged in, they will see / be able to navigate to all of their sites.
5. When the user is using SSO, they no longer get access to Recurly's 2-factor authentication service.
6. Recurly currently offers support for Okta, Microsoft and Google single sign-on products. If you're interested in SSO but use a different identity provider, please contact Support and let us know which identity provider you want to use.

Configuration and setup

To enable and get up and running with SSO, follow these steps:

For Okta

Supported features:

• SP-initiated SSO
• IdP-initiated SSO

Step 1. Add the Recurly application to your Okta instance and assign the appropriate people

1. Login to Okta as an Okta Administrator, and navigate to the "Admin" section
2. Expand “Applications” in the left navigation pane.
3. Click on “Applications”
4. Click “Browse App Catalog” and search for Recurly
5. Click on Recurly in the search results then click “Add Integration”
6. Under “General Settings”, configure the application name.

• Click “Next”
• Under Sign-On Options
• Configure “Default Relay State” to your site’s subdomain.
  • In Recurly, the Recurly Subdomain can be found under Site Settings from the Configuration navigation section of the site.
    • Only use the subdomain and not the full URL.

• Upload the Recurly certificate
• Please contact Recurly Support to get a copy of the certificate
• Set “Application username format” to “Email”
• Click “Done” to save the application settings.

• The final step to take in Okta is to assign the Recurly App to the appropriate people

Step 2. Configure the SAML credentials in Recurly
In Okta, click on the “Sign On” tab and then click on “More details” to expand the Metadata details.

• In Recurly, navigate to the site you want to be the site that enforces users to use SSO
• Expand the Admin section of the site and click on “SSO Settings”
• Set “Status” to Enabled.
• Set “Provider” name to Okta
• Copy from the Okta Recurly application metadata the following over to the Recurly SSO settings.

• In Recurly, navigate to the site you want to be the site that enforces users to use SSO
• Navigate to the Users page for that site
• Click the "Configure Single Sign-On" button
• Copy the SAML configurations over from Okta to Recurly as directed by the Okta instructions.

Click “Save Changes”

For SP-initiated SSO Login:
Open the following url: https://app.recurly.com/login/sso

• Enter your Email
• Click Log In

For Microsoft Azure

Please refer to the documentation on Microsoft's site here

For Google SSO

Google can be configured as an Identity Provider in Recurly App by configuring a "Custom SAML App" in Google Workspace.

Note: Super administrator permissions are needed to perform the configuration steps

Configure Custom SAML App in Google Admin Console

1. In the Google Admin Console, navigate to "Apps > Web and mobile apps". Click "Add App", then "Add custom SAML app"

2. Enter the name for the SAML app. Optionally, add a description.

3. On the Google Identity Provider details page, copy the "SSO URL" and download the "Certificate".

4. in the Service Provider details page, configure the values accordingly:
   • ACS URL: https://app.recurly.com/login/sso
   • Entity ID: https://app.recurly.com
   • Ensure that the “Signed Response” box is unchecked. Google will not sign the assertion if this is checked, but Recurly requires that the assertion is signed.
   • Name ID format: select "EMAIL" from the dropdown menu.
   • Name ID: select "Basic Information > Primary email" from the dropdown menu.

5. On the "Attribute mapping" page, map the "Primary email" to an app attribute named "Email" (the name for this app attribute is case sensitive)

🚧

Please ensure that your configuration matches the screenshot above

Configure Access

The SAML app can be turned on/off for everyone in the organization. Specific Google groups can also be assigned access.

1. Navigate back to the Admin console, and go to "Apps > Web and mobile apps". Select the newly created SAML app to the open the following view:

2. Click "User access" to open the following view:

3. Under "Groups", select the group to give access to.

🚧

Ensure that the email addresses users use to sign in to the SAML app match the email addresses they use to sign in to the Google domain

Configure Recurly App

1. Log into Recurly App and navigate to "Admin > SSO Settings"

2. Configure SSO Settings using the values coped from the Google Admin Console
   • Set "Login URL" to the "SSO URL".
   • Set "SAML Issuer ID" to the same value entered in the "Entity ID" field during step 4 of configuring the custom SAML app
   • Set "Certificate" to the certificate that was downloaded.
   • Toggle "Single Sign-On" to "Enabled"
   • Save your settings

🚧

If you encounter any issues with RA initiated logins, ensure that the SAML Issuer ID configured in Recurly App matches the Entity ID value in the Google Service Provider details page.

Finalize your setup

Once you've completed the steps specific to your chosen identity provider, the last step is to select the "Enabled" radio button.

• When SSO is enabled, new invitations for users to join your site will default to having SSO selected for that user.
• Existing users will not yet be affected by the SSO configurations. To update existing users to require them to start using SSO, follow the steps outlined below.

Background and importance of having a valid SSO Certificate

The SSO public certificate generated by your Identity Provider is used to sign and encrypt the SAML responses and assertions sent between Recurly and your Identity Provider. This allows Recurly and your Identity Provider to validate that the login requests are coming from the intended source and that the requests haven’t been altered.

❗️

Consequences of not updating the certificate

Recurly will not be able to use your certificate to verify the integrity of the SAML responses and assertions sent from your identity provider if it has expired. As a result, your SSO users will not be able to log in.

Finding the certificate expiration date

The expiration date can be found in your site's SSO settings, under the certificate that you have uploaded.

How to update your certificate

Please follow these steps to generate a new certificate according to your chosen identity provider:

Okta

1. Navigate to your Applications and click on the application you configured for Recurly.
2. Navigate to the "Sign On" tab and scroll down to the "SAML Signing Certificates".
3. Click "Generate new certificate"

4. Under "Actions", activate the newly generated certificate (Note: the old certificate should have an "Inactive" status after the new certificate has been activated)

5. Under "Actions" again, download the certificate and paste it into the "Certificate" field in your site's SSO settings.
6. Your site should no longer be displaying notifications regarding your SSO certificate and the new certificate's expiration date should be displayed.

Azure

Please refer to the documentation on Microsoft's site.

Google

Please refer to the documentation on Google's site.

Updating existing users to require them to use SSO:

Now that you have enabled SSO for your site, you can now start updating existing users to require them to use SSO to login to Recurly.

• Navigate to the /users page for your site
• Select a user that you want to update to require them to use SSO to login
• Select the "Single Sign-On" radio button
• Click "Save Changes" button at the bottom of the page
• If the user is currently using 2-factor authentication, you will be prompted to confirm that you want to disable 2FA and replace it with SSO.

• If you save the changes,
  • Recurly will log the user out of any current session on Recurly
  • Recurly will send the user an email notifying them that SSO is now required for their Recurly login
  • The user can log back in to Recurly either by clicking on the link in the email they receive, by navigating to http://app.recurly.com/login/sso, or by logging into their identity provider and clicking on the Recurly tile.
• You will also notice on the users page for your site a "Security" column in the table of users. Look for "SSO" or "2FA" to see if the user is using either SSO or 2FA. If you see nothing in that column, it means they are simply using their email and password to login.

Inviting a user to join a site and requiring them to use SSO

When SSO is enabled for your site, any time you invite a user to join your site, your invitation will default to requiring that they use SSO to login to Recurly. You can uncheck that option on the invitation if you wish.

• Assuming that you send the invitation with the SSO option selected:
  • Be sure that the user also has access to Recurly through your identity provider
  • The user will receive an email from Recurly inviting them to join your site
  • If they accept the invitation, they will be notified that they will be required to use SSO to login
• Note: if the user already had an account in Recurly, and was already using SSO to access Recurly, they will continue to do so, using the SSO identity provider that they were previously using.
  • For users on your site, you can see which site is the one requiring them to use SSO by clicking on their user profile. If a different site is the site that is requiring them to use SSO, you'll see the details on their profile:

Updating an existing user to no longer require them to use SSO

If you decide that you no longer want to require a user to use SSO to login, you can do so by following these steps:

• Navigate to the site that is requiring the user to use SSO
• Navigate to the users page for that site, and select to "edit" the user that you want to update
• Change the Account Security to "password only"
• You will be prompted to confirm your action, since you are downgrading the Account Security from SSO to password only
• Once you save your changes:
  • Recurly will log the user out of any current session on Recurly
  • Recurly will send the user an email notifying them that SSO is no longer required for their Recurly login. The email will contain a link that takes the user into Recurly's password reset flow. The user simply enters their email address, gets another email from Recurly containing a temporary URL that takes them to a page where they can create a new password for their Recurly account.

Disabling SSO

You may find yourself wanting to disable SSO completely for your site. If this happens, follow these steps:

• Navigate to the site for which you want to disable SSO, and go to the users page for that site
• Click on the "Configure Single Sign-On" button
• Select the "Disable" radio button, and then save your changes
• You will be prompted to confirm your action. If you confirm the action:
  • Every user that is required to use SSO by this site will be logged out of any current session on Recurly
  • Recurly will send the users an email notifying them that SSO is now required for their Recurly login
  • The users will follow the same flow as described above to create a new password for their Recurly account

Limitations

• Recurly does not yet support provisioning users through your SSO IdP. For the time being, you will need to add new users to Recurly before they can use SSO to login and authenticate to Recurly.
• SSO is only available through Okta and Microsoft Azure for now. If you want to use SSO with a different identity provider, please contact Support and let us know which IdP you want to use.

Troubleshooting

🚧

SCIM for Okta - Only for merchants with this active in Early Access Program

SCIM for Okta

This feature is currently in Early Access and only applies to merchants in EA currently. If you are interested in the EA program for this feature please reach out to Recurly Support

Current supported features:

• Create Users
• Deactivate Users

Steps to enable SCIM for Okta:

1. In your Recurly site, navigate to SSO Settings under the Admin section.
2. Select Enable under SCIM Provisioning
3. Select an initial provisioning role for new users.
   1. This role will be used for initial user provisioning. The role for the user can be updated later.
   2. By default, new sites have only a site admin role. It is recommended to create a new user role under the Role section with the desired permissions.
   3. Click Save Changes to save the configuration and generate an API Token.

• Click on the icon at the end of the API Token field to display the API Token. Copy the API Token to your clipboard.
• In the Okta portal, navigate to the Recurly SAML App.
• Click on the Provisioning tab

• Click on Configure API Integration

• Click on Enable API Integration
• Paste the Recurly API Token copied from the Recurly SSO Settings page to the API Token field.

• Click Test API Credentials.

• After a successful test of the API Integration, click Save.
• Under "To App", Click Edit.

• Enable Create Users and Deactivate Users and Click Save.

• As users are Assigned the Recurly App in Okta, the users will receive an invite to the Recurly site that was configured for SCIM Provisioning.
• When users are unassigned the Recurly App in Okta, the user will be removed from the site configured for SCIM Provisioning.

🚧

SCIM for Okta - Only for merchants with this active in Early Access Program