Skip to main content

🔌 Setup a SSO Connection

Single sign-on (SSO) is a common request for mature businesses that want to adopt new SaaS applications. With Cryptr as a single integration you can enable your application to support single sign-on for all popular SSO providers. When a SSO authentication suscceeds with the SSO Provider of your customer, you'll get a modern Json Web Token because Cryptr respects the OAuth 2 framework. We will see together how you can easily and quickly set up an SSO connection in 4 steps.

First you create an organization, this is the users directory of your customer.

API ENDPOINTS USED IN THIS GUIDES

You ca read more about endpoints during this guide with our API Reference.

About Identity Providers

Before to start, maybe you need to understand what's an Identiy Provider. If you won't, you can gohead directly to 1st step of the integration.

The SSO provider of your customer

You will often see the term Identity Provider. This is your client's SSO provider. Cryptr supports the following Identity Providers:

  • Azure Active Directory
  • ADFS
  • Google
  • Okta
  • Ping Federate (Ping Identity)
  • Ping One (Ping Identity)

An Identity Provider will always be identified at Cryptr by an "idp_id" its unique and immutable identifier.

The IDP ID or idp_id (Identity Provider Identifier)

Each SSO connection are stored in a distinct directory for a dedicated customer (Organization). You can find the domain of the user's Organization with this user's atttributes domain.

Service Provider VS Identity Provider

You may hear of Service Provider. And you ask what is the difference with an identity provider. A Service Provider is your own Service that manages the connection to the SSOs (and more precisely to the Identity Providers) of your customers. Cryptr takes care for you to generate and configure your Service Provider with the required needs.

In one sentence: your Service Provider consumes your client's Identity Provider, this is a SSO connection.

Step 1. The Organization owner

If you already has an Organization, and you want to create a SSO Connection for this, you can go directlty to Step 2.

An Organization is the users directory of your customers with a strong identifier we called the domain. All created users will be stored in dedicated environnment for this customers, with a unique identifier to scope your actions in connexion with this customers. So we need to create the place where we'll store users & configuration of this new customer, then get the identifier.


Create a new Organization with a name & a locality (the cityof the organization) :

Query

curl https://${YOUR_CRYPTR_SERVICE_URL}/api/v2/organizations \
-d locality="Lille" \
-d name="Misapret"


Now we get the domain of our new Organization, here misapret is the domain identifier. Now, each time a new user will be created from our SSO, or we add a new configuration, it will be stored in a clean separated directory.


We can fetch the users from this Organization :

Query

curl https://${YOUR_CRYPTR_SERVICE_URL}/api/v2/org/:domain/users


Of course, at this time our list is empty. To see more about Organization and User, please have a look at our Organization API Reference and User API Reference. We can store the end users of our Organization, and attach a SSO connection to this. But we need to handle the user flow.

Step 2. Redirection after a login

If you already has an Application where to redirect your users, you can go directlty to Step 3.

Just like the Magic Link connection, your applications can specify where to redirect a user after a successful authentication. However unlike our Magic Link connection, a user can start their authentication directly from your SSO authentication screen at Cryptr. It is therefore necessary in addition to the redirections that Cryptr could authorize, to specify a default redirect. So no user will be stuck after an SSO authentication.

But what is a redirect for Cryptr. A redirect is your registered app and a url on that app. This is a security issue, and an ergonomic comfort for your users.


Create a new Application type with a the URL redirection to indicate to Cryptr where you want to redirect your user.

Query

curl https://${YOUR_CRYPTR_SERVICE_URL}/api/v2/org/:domain/applications \
-d name="App of Misapret"
-d allowed_origins_cors=["https://app.misapret.com/"]
-d allowed_redirect_uris_after_login=["https://app.misapret.com/account", "https://app.misapret.com/welcome"]
-d allowed_redirect_uris_after_logout=["https://app.misapret.com/bye"]
-d application_type="react"
-d default_redirect_uri_after_login="https://app.misapret.com/account"
-d default_redirect_uri_after_logout="https://app.misapret.com/account"
-d description="Everything to deal with bank"

Note the client_idof the application, it is the authentication identifier of your app.

Now, we can create a new SSO Connection, because we get the two resources to do that : the Organization and the Application.

Step 3. SSO Connection creation

With a created Organization, and an Application, we can create SSO Conneciton between your application & your customer (the Organzation).

Create a new SSO Connection type. The response auto expand default_redirection and onboarding nested elements

Query

curl 'https://${YOUR_CRYPTR_SERVICE_URL}/api/v2/sso-connections' \
-d application_id="organization_client_id" \
-d sso_admin_email="it_sso_person@sso.client.com" \
-d organization_id="your_organization_id"

Please note you don't need to know the email of the SSO administrator of your customer. See the next Step to handle the interaction with the person in charge of the SSO at your Customer (Organization).

Step 4. Admin of the Organization

How the SSO configuration space for your customer works

  • Credentials
  • Certificate
  • Metadata XML
  • Step by step tutorial with progression

Precise or replace the Customer Admin email

Create the Admin Onboarding

This request will help you resend an email to the SSO administrator for the selected IDP ID. This only works if an email was set up previously

Query

curl -X POST https://${YOUR_CRYPTR_SERVICE_URL}/api/v2/sso-connections/${IDP_ID}/admin-onboarding


Invite the admin to the SSO Setup

Query

curl -X POST https://${YOUR_CRYPTR_SERVICE_URL}/api/v2/sso-connections/${IDP_ID}/invite-admin'


Get the Onboarding progress