The Reference Docs Developer Hub

Welcome to the Reference Docs developer hub. You'll find comprehensive guides and documentation to help you start working with Reference Docs as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Single Sign-On

Boost security and streamline management of employee logins to Recurly with 3rd party 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 support for SSO uses SAML 2.0 to provide full support for authentication scenarios where employees login to your chosen "identity provider" (e.g. Okta), and from Okta they 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 or Enterprise plan. 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. sample@recurly.com cannot use both Okta AND Google 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 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 user is using SSO, they no longer get access to Recurly's 2-factor authentication service.
  6. Recurly currently offers support for Okta's single sign-on product. If you're interested in SSO but use a different identity provider, please 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:

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

  • Login to Okta as an Okta Administrator, and navigate to the "Admin" section
  • Click "Add Application"
  • Search for and add "Recurly"
  • Configure the "General" settings however you want
  • On the "Sign-On Options" page, upload the Recurly certificate
  • 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 "Sign On" tab and then click on "View Setup Instructions"
  • 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.
Okta Field
Recurly Field
  1. Identity Provider Single Sign-On URL

Login URL

  1. Identity Provider Issuer

SAML Issuer ID

  1. X.509 Certificate

Certificate

Step 3: 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.

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 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

Issue
Cause and resolution

I'm trying to login at https://app.recurly.com/login but I keep getting an error that the email address or password is incorrect.

If you are an SSO user, you should be logging in at https://app.recurly.com/login/sso, or via your identity provider.

I'm trying to login at https://app.recurly.com/login/sso but I keep getting an error that my email address is invalid

You are either entering the wrong email address, or your account may not be set up as an SSO account. Contact your site administrator or Recurly Support.

I'm trying to login to my new site, but I get an error that I "must first accept the invitation to join this site".

You have been invited to join a site, but you have not yet accepted the invitation. When you are invited to join a site, you get an email from Recurly asking you to accept the invitation. As a security protection, you must click on the "Accept invitation" link / button in the email before we will allow you to allow you to access the site, and before we will allow that site to require you to use SSO.

If you did not get an email inviting you to join the site, first check your spam folder, and then ask the Administrator for the new site to resend you the invitation.

I'm trying to login via my identity provider, but the login is failing - I get to Recurly and see an error message that the login is invalid.

First thing to verify is that your Recurly account is required to use SSO, and that Recurly is expecting you to sign in via the identity provider that you are using.

Ask your site Administrator to log into Recurly and pull up your user profile (navigate to any Recurly site you are associated with, then go to the /users page and click "edit" next to your user). There, the Admin will be able to see a. is your account using SSO to login? and b. if it is, which site is requiring you to use SSO ... and from there you can find out what identity provider we are expecting you to use.

If the identity provider looks correct for your account, then have the site Administrator look at the SSO configurations to ensure that they are correctly setup.

If you see that you confirm that your Recurly account is expected to use SSO, and the SSO identity provider is correct, and the SSO configurations are correct, but you still can't login, then have the site Administrator set your account back to just using a password, and then set your account to use SSO again.