SSOReady environments hold onto top-level settings about your application, such as your app’s URL. They also serve as the parent resource for organizations, which in turn hold onto SAML connections and SCIM directories.

You should create one SSOReady environment per “deployment environment” your application uses, e.g. one each for “production”, “staging”, and “local dev”.

Properties

Environment ID

Every environment has an ID starting with env_..., for example:

env_579r04bhgwhl0zq7f3ynj8hh0

Environment IDs are universally unique.

Display Name

You can assign your environments a human-friendly display name. SSOReady does not show this to your customers. It is internal-only.

Redirect URL

The redirect URL for an environment is where SSOReady will redirect your users after they log in via SAML. This URL is also often called the “SSOReady callback page”.

For more details on what you should run on this page, see “Handling SAML Logins” in the SAML quickstart.

OAuth Redirect URI

Optional. When using SAML-over-OAuth (SAML NextAuth.js integration), this is the URL SSOReady will redirect your users to.

If you aren’t using SAML-over-OAuth, disregard this field.

Custom SSOReady Auth URL

If you’ve enabled Custom Domains on this environment, this is the URL that your customers will see instead of auth.ssoready.com.

Organizations

Environments contain any number of organizations. You can create organizations in one of two ways:

1. By hand, using the SSOReady web application
2. Programmatically, using the Management API

API Keys

To implement SAML or SCIM, you need to call SSOReady’s API from your application using our SDKs or our HTTP API. To do that, you’ll need an SSOReady API key.

SSOReady API keys are scoped to within an environment; you cannot create an API key that can access multiple environments.

You can create API keys by going to “API Keys” on the side navigation, and clicking the “Create API Key” button.

API Keys have two properties of note:

• An API Key ID, starting with api_key_..., is a non-sensitive identifier that uniquely identifies an API key. It is not a secret.

• An API Key Secret, starting with ssoready_sk_..., is a secret. Do not share it with others.

  When using SSOReady’s SDKs, use the ssoready_sk_... API key secret as the SSOREADY_API_KEY environment variable.

  When using SSOReady’s HTTP API, use the ssoready_sk_... API key secret as in an Authorization: Bearer ssoready_sk_... HTTP header.

Once you create an API key, you can only view the API key secret once. SSOReady only stores the hash of the API key secret. If you’ve lost the API key secret, or accidentally published it publicly, delete the API key and create a new one.

Deleting an API key also revokes the API key secret.

Management API

All SSOReady API keys allow you to use the SAML and SCIM APIs. This will allow you to implement enterprise single sign-on and enterprise directory sync.

If you have so many enterprise customers that using SSOReady’s web application is unacceptable, SSOReady also supports a Management API.

API keys with Management API access enabled can programmatically manage (i.e. create, list, get, and update) organizations, SAML connections, SCIM directories, and customer self-serve links within an organization.

For more details, see the Management API documentation.

Custom Domains

Running auth.ssoready.com on a custom domain

SAML connections and SCIM directories both require that your customers configure certain URLs that point at your application. Those URLs need to be endpoints implementing the SAML and SCIM protocols.

When you use SSOReady, SSOReady runs those endpoints on your behalf. By default, those endpoints have auth.ssoready.com in their names, because that’s the hostname where SSOReady runs endpoints on your behalf. For example, SAML ACS URLs and SCIM Base URLs both contain auth.ssoready.com by default.

You can also run your SSOReady instance on a custom domain you control, such as auth.yourcompany.com. When running SSOReady on a custom domain, your customers see your custom domain instead of auth.ssoready.com in their setup instructions.

To set up a custom domain, you’ll need to have control over the DNS settings for that domain. The SSOReady web application will ask you to create a custom CNAME record pointing at an SSOReady-controlled domain. We require you to create a custom CNAME before you can enable a custom domain for two reasons:

1. So that traffic your customers send to your custom auth.ssoready.com domain will still be served by SSOReady, and
2. SSOReady needs to provision a TLS certificate for your custom domain, because communication with auth.ssoready.com (or its custom domain aliases) must be done over HTTPS. We can only do this if we first demonstrate that your custom domain CNAMEs requests to a domain we control.

Adding a custom domain does not break any existing SAML connections or SCIM directories. Existing SAML connections and SCIM directories will continue to use auth.ssoready.com, but all new SAML connections or SCIM directories will use your custom domain.

Adding a custom domain does not change the API calls you make to SSOReady. You do not need to change any code, such as any code that calls Get SAML Redirect URL and Redeem SAML Access Code. Regardless of whether you use a custom domain, your backend’s API calls to SSOReady will be directed at api.ssoready.com.

Running admin.ssoready.com on a custom domain

SSOReady can host a self-serve SAML/SCIM setup UI on your behalf. By default, that UI runs on admin.ssoready.com, but you can run it on a custom domain too.

To set up a custom admin.ssoready.com domain, you’ll need to have control over the DNS settings for your custom domain. The SSOReady web application will ask you to create a custom CNAME record pointing at an SSOReady-controlled domain.

Once you enable a custom admin.ssoready.com domain, all new self-serve setup links will use it.

Adding a custom admin.ssoready.com domain does not change the API calls you make to SSOReady. You do not need to change any code. If you use the Management API to programmatically create setup links, the setup URLs will automatically pick up your custom domain.

Custom Branding

SAML and SCIM are both designed such that they require setup on you and your customer’s end before they can work. To do that setup, you need to give your customer specific instructions, tailored to the identity provider they use.

SSOReady can host a self-serve SAML/SCIM setup UI on your behalf. To make that setup UI feel on-brand for your product, you can customize:

1. Your company’s name and logo, which appear in the navigation bar
2. A return URL, which points to your application. If you configure a return URL, the self-serve setup UI will have a “Back to [your company name]” link in the navigation bar, which takes users back to your application.

When you configure custom branding settings, the SSOReady web application will show you a preview of what your users will see.