Single Sign-On

Single Sign-On

Gateway UIHeadless

How to choose your integration strategy?

Accelerate adoption of your application for your larger B2B customers. With this headless SSO implementation, you embbed Cryptr's SSO solution in your code.
SSO allows organizations to authenticate their users on third-party applications with their own solution. Cryptr supports standard SSO protocols SAML and OIDC.

Watch the video guide

• Quickstart
• 15 min

View example

In this guide we'll help you learn Cryptr's SSO

The fallback content to display on prerendering

from

The fallback content to display on prerendering

setup to authentication integrated in your application for your first user.

Before you start

There are a few essential elements to consider:

• Cryptr Account: Create your free Cryptr account now 🔥. With a Cryptr account you'll get your API Key, which is a prerequisite for this guide (a public client_id with a private client_secret). You can see how to take advantage of your API Key here.

• Organization: An organization that represents your customer. Follow this link to learn more about Organization.
• Redirection: A redirection also called redirect_uri is the URL to which your user will be redirected after authentication.

How to use your Client ID & Client Secret

You can take advantage of your client_id & client_secret by using the following request:

curl -X POST '${cryptr_service_url}/oauth/token' \
  -d grant_type="client_credentials" \
  -d client_id="${cryptr_client_id}" \
  -d client_secret="${cryptr_client_secret}" \
  -d audience="communitiz-app" \

This request will give you an Access Token that you can use to authenticate your API calls.

To do so, proceed as follow:

curl -X POST '${cryptr_service_url}/api/v2/organizations' \
  --header 'Authorization: Bearer eyJ...' \
  -d name='New company' \
  -d 'allowed_email_domains[]'='company.co'

1. Create an SSO Connection

To handle SSO communications between Cryptr and your customer's

The fallback content to display on prerendering

. You'll need to create an SSO

The fallback content to display on prerendering

.

All you have to do is go to your Dashboard. Once connected to the Cryptr platform, go to the page dedicated to the Organization for which you wish to activate the SSO Connection. You can select an Organization via the User Directory Sidebar Navigation on the left of your screen.

Once you are on your Organization page, click on the TRY FOR FREE button in the SSO Connection section at the top right of your dashboard to activate SSO for this Organization.

2. Experiment admin onboarding for SSO configuration

You need a fully-configured SSO to test the authentication, that means you have to act as your own Customer administrator, and finalize the setup yourself. This is the occasion to understand your future delightful customer experience 😎:

First you will need an account with an identity provider.

Create your Identity Provider account

At Cryptr you have access to several identity providers and you can choose the ones that suit you best based on the needs of your customers. However, if you want to test your authentications we recommend you create an Okta account. Okta is a popular SSO provider for enterprises which offers a free account for developers.

Next, on your Cryptr Dashboard, you'll have to invite yourself with your own email address.

You can invite yourself by going to your Organization page in the same way as above. Once on this page, you can invite the administrators (in this case yourself) by clicking on the button at the top left of the page.

Once this is done you should receive an email, after clicking on it you should arrive on the Onboarding space of your Organization, this space is reserved for the administrators of your clients who will be in charge of configuring the SSO.

Access onboardings later

If you have already started your configuration and want to access it again later, you can simply go to the link: onboarding.{your_cryptr_domain}. This link will be the same for all your customers.

You will land on a page offering you several options, choose the first one (SSO), a list of identity providers will be available to you. Choose the provider you use to carry out this test but if you followed our recommendations your provider should be Okta. Follow the instructions and your SSO will be ready 👌. If you want to know more about Onboardings, you can learn more.

3. Integrate the authentication in your app

SSO Challenge

Please note that until you have finished configuring your SSO it will be impossible to complete a Challenge as an end-user. You must have completed the try-login step of your Onboarding to make the challenges usable.

There are 3 steps to complete an SSO Challenge process for one employee of your customer:

1. Request to Cryptr an authorization URL to give to the user with the desired redirect_uri where you want us to redirect the user after SSO authentication
2. User consumes the URL to authenticate through the Organization's SSO Identity provider
3. User is redirected to the redirect_url and you can complete the process and retrieve user session
   The fallback content to display on prerendering

On your side you just have two operations to manage: create the SSO Challenge and consume the response to generate a session for the user. This is what the next two paragraphs will deal with.

Here is the process in a detailed process.

1. Request SSO Challenge

To request an SSO Challenge you'll need

• to identify the SSO
  The fallback content to display on prerendering
  - basically using
  The fallback content to display on prerendering
  's email
• the redirect_uri where you want Cryptr to redirect user after their SSO authentication

Here are the related requests:

cURL

curl -X POST '${cryptr_service_url}/api/v2/sso-saml-challenges' \
  -d user_email="john@misapret.com" \
  -d redirect_uri="https//example-of_url.com/welcome-back-user"

Kotlin

val createSsoSamlChallengeResponse = cryptr.createSsoSamlChallenge(
  redirectUri = "http://localhost:8080/callback", 
  userEmail = "toto@misapret.com"
)

info

You can also target the proper SSO Connection using

The fallback content to display on prerendering

's

The fallback content to display on prerendering

Request SSO Challenge using

The fallback content to display on prerendering

's

The fallback content to display on prerendering

cURL

curl -X POST '${cryptr_service_url}/api/v2/sso-saml-challenges' \
  -d org_domain="misapret" \
  -d redirect_uri="https//example-of_url.com/welcome-back-user"

Kotlin

val createSsoSamlChallengeResponse = cryptr.createSsoSamlChallenge(
  redirectUri = "http://localhost:8080/callback", 
  orgDomain = "misapret"
)

2. Allow the user to consume the Challenge

The above request will provide you an authorization_url that your user should continue to to authenticate through your identity provider before being redirected to your desired redirect_uri. You can find an example of a payload below:

  {
    "__environment__": "sandbox",
    "__type__": "SsoChallenge",
    "authorization_url": "https//your-cryptr-service-url.com/org/loirama/oauth2/saml?request_id=8d814d02-35d8-48a9-a033-291fd5959a0c",
    "expired_at": 1684774623,
    "redirect_uri": "https://loirama.com/welcome-back-user",
    "request_id": "8d814d02-35d8-48a9-a033-291fd5959a0c",
    "sso_connection_id": "loirama_VqiFf3Y5ogaYRbyEyazDWn"
  }

This authorization_url is only valid for a short period of time so the best practice is to redirect the user yourself as soon as the challenge is generated or to generate the challenge only when the user is ready to login.

3. Get tokens after redirection & user authentication success

After the User successfully authenticated through the SSO Connection, they will be redirected to the provided redirect_uri where we will provide you a code to retrieve User's

The fallback content to display on prerendering

JWTs.

To do so, please request as follows:

cURL

# ... your user finishes its SSO authentication, 

# On your app, the user is redirected on your service, 
# via the "redirect_uri" when you start the challenge that we see before ("/callback")
# with the query params "code" that we need to fetch the tokens

curl -X POST '${cryptr_service_url}/oauth/token' \
  -d code={code}

# if result.success is true, then

# 1. you get the result.access_token
# 2. and result.id_token where you get signed user data

# else 

# your user is unauthorized

Kotlin

val callbackResp = cryptr.validateSsoChallenge(call.parameters.get("code"))
if (callbackResp is APISuccess) {
    val challengeResponse = callbackResp.value
    // Handle the response as you want
} else {
    // Error occurend while validating
}

We will respond to this request with User's

The fallback content to display on prerendering

to let you open a session for this user. You must verify the token before using it, to do this you can use our guide: How to validate a JWT

Redirections

To use Cryptr authentication strategies you probably had to create Redirects from your Dashboard. To use a Redirect URI during an SSO Challenge, it is mandatory that the URL you specify in your Challenge is a URL known to Cryptr. If you do not provided Redirection in your Challenge request, the default redirection will be used.

What's next

Invite the Customer's SSO Admin
You've already self-onboarded using your own email; now, you can dive deeper into admin onboarding with the aforementioned guide.
How to validate a JWT
Learn how to validate your Oauth JWTs

More:
You can also consult our API Ref to perform these actions via the

The fallback content to display on prerendering

or if you wish to go further.