Skip to main content

🔌 Your SSO Connection settings

You can create or update SSO connection preferences for an Organization (usualy your Enterprise customer). Everything to setup, attach, create a redirection a end-user login or interact with administrator of the SSO.

Setup a SSO Connection

Create a new SSO Connection for B2B customer(Organization)

Handle redirections after login

Manage where your users will be redirected after successful authentication

Users policy & automations

Your authentication and user storage rules

SSO Administrator of your B2B customers

Features to welcome the Administrator of your client

Others

Cryptr supports the following SSO provider solutions :

  • Azure Active Directory
  • ADFS
  • Google
  • Okta
  • Ping Federate (Ping Identity)
  • Ping One (Ping Identity)
  • Auth0
  • One Login
  • Custom SAML

By default, user profile attributes provided by identity providers (the SSO solution of your customers) are not directly editable because they are updated from the identity provider each time the user logs in.

To be able to edit the name, nickname, given_name, family_name, or picture root attributes on the normalized user profile, you must configure your connection sync with Cryptr so that user attributes will be updated from the identity provider only on user profile creation.

You can add & edit root attributes individually or as a bulk import using the Management API. You'll find these attributes in the final JWT (Json Web Token) after the successfull SSO authentifcation.

  • A (User) represents an end user ofr your customer or partner in your Cryptr service.
note

Your Cryptr subscription plan could limit the number of users. See our pricing for more details.

The SSO Connection type

Each new SSO connection get an unique idp_id (identity provider identifier) generated from its Organization name. This identifier is impossible to update, because it's the immutable identifier of the connection.

ATTRIBUTES

idp_id UUID

The immutable identifier.


onboarding SsoAdminOnboarding

This refers to SsoAdminOnboarding type . At creation or when preloaded you'll have the nested structure, else only id reference will be given.

EXAMPLE
A User type

{
"__access__": "all_organizations_of:misapret",
"__domain__": "misapret",
"__managed_by__": "misapret",
"__type__": "SsoConnection",
"idp_id": "bank_of_lille_22RYkQ4vmT6PrtCmDhCXLc",
"inserted_at": "2022-02-21T10:47:46",
"metadata": [],
"onboarding": "c652374d-0cd0-4040-9fd0-ea144885259a",
"provider_type": "azure_ad",
"seats_limit": 0,
"sp_id": "misapret_AcJR5DAH65rLs8iDKsajeR",
"state": "it_admin_invitation_in_pending",
"updated_at": "2022-02-21T10:47:46",
"user_policy": "save_user_when_first_connection",
"update_user_new_connection": false,
"default_redirection": "c652374d-0cd0-4040-9fd0-ea144885259a"
}

The SsoAdminOnboarding type

When you have the email contact of the SSO manager of the organization you want to work with, an onboarding can be created to help this admin to configure the SSO on his side. The onboarding reflects progression, provider type choice, and allow metadata XML file upload.

When created you can also choose to send (or not) directly a magic link email to this onboarding.

ATTRIBUTES

sso_admin_email STRING EMAIL

Administrator's Email of the SSO


provider_type STRING

Chosen Provider type by the SSO administrator (Okta, Azure AD, ADFS, Google Workspace ...)


state ENUM

One value of below:

  • not_initialized Onboarding at first step (no provider type chosen, no XML provided)

  • provider_type_chosen SSO Administrator chose its Provider type and is currently in dedicated step-by-step provider type tutorial

  • xml_provided Tutorial step is done and SSO Administrator uploaded the SSO Connection metadata XML file

The Default Redirection type

To ensure direct mapping between Your front application, the SSO connection configured by the SSO admin and Cryptr, a default redirection can be created. This default redirection will redirect SSO users to your application with an OAuth process.

ATTRIBUTES

id UUID

The Default redirection unique identifier


app_id UUID

The Application unique identifier


uri URL

The target URI where SSO users will be redirected after successful SSO session.

Create a SSO Connection

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

Query

curl --request POST 'https://${YOUR_CRYPTR_SERVICE_URL}/api/v2/sso-connections' \
--header 'Authorization: Bearer your_api_key_generated_token' \
--header 'Content-Type: application/json' \
--data-raw '{
"application_id": "front_app_client_id",
"sso_admin_email": "it_sso_person@sso.client.com",
"organization_id": "organization_id"
}'

PARAMETERS

application_id UUID

The application ID where you want to redirect end-user after SSO success. (default redirection will be used)

If you do not provide an uri parameter either application's default_redirect_url value or first allowed_redirect_urls value will be used.


organization_id UUID REQUIRED

The organization ID for which you want to create this connection.


sso_admin_email STRING EMAIL OPTIONAL

The email of the SSO admin of the organization if you already know it.


send_email BOOLEAN OPTIONAL

⚠️ requires it_admin_email to be set if used

If set to true an invitation email to configure this SSO Connection will be automatically sent to the sso_admin_email.

RETURNS

Returns a SSO Connection if the creation succeed. Returns an error if create parameters are invalid (e.g specifying an invalid organization_id)

Retrieve a SSO Connection

Fetch an SSO Connection, usefull to known its configuration and also fetch nested object as default_redirection and onboarding.

curl --request GET 'https://${YOUR_CRYPTR_SERVICE_URL}/api/v2/sso-connections/:idp_id'
PARAMETERS
idp_id* UUID

The reference of the SSO Connection

preload_associations STRING ARRAY OPTIONAL

By default all nested resources are returned by their ids. If you would like the nested object returned in the body, you can set default_redirection and/or enterprise_connection_onboarding into this parameter.

RETURNS

Returns the SSO Connection

Update a SSO Connection

Fetch an SSO Connection, usefull to known its configuration and also fetch nested object as default_redirection and onboarding.


curl -X PUT 'https://${YOUR_CRYPTR_SERVICE_URL}/api/v2/sso-connections/:idp_id' \
--header 'Authorization: Bearer your_api_key_generated_token' \
--header 'Content-Type: application/json' \
--data-raw '{
"seats_limit": 99
}'

PARAMETERS

idp_id* UUID

The reference of the SSO Connection


active BOOLEAN

Change the state of the SSO Connection see Turn on/off requests


default_redirection_id UUID

Change the Default redirection for Sso Connection


metadata STRING

This should be the XML Metadata String content.

If you want to change the XML for the targetted Sso Connection.

For example if the SSO Administrator send you a new XML Metadata for the connection you can change it here.


provider_type STRING

Change the provider type (Okta, Google Workspace, ADFS ...) of targetted Sso Connection


seats_limit INTEGER

Change the limit of simultaneously possible sso sessions for the targetted Sso Connection

⚠️ Depending on user_security_type value


user_security_type INTEGER

Change the rule of end-user openning session for the targetted Sso Connection


preload_associations STRING ARRAY OPTIONAL

By default all nested resources are returned by their ids. If you would like the nested object returned in the body, you can set default_redirection and/or enterprise_connection_onboarding into this parameter.

RETURNS

Returns the updated SSO Connection

List all SSO Connections

List all your SSOConnection currently created, regardless of the progress of the configuration.

Query

curl -X GET https://${YOUR_CRYPTR_SERVICE_URL}/api/v2/sso-connections


PARAMETERS

page INTEGER

Precise the page of your listing, see how to paginate the Cryptr API.


per_page INTEGER

Precise the size of the pages of the pagination of the list. See how to paginate the Cryptr API.


preload_associations STRING ARRAY OPTIONAL

By default all nested resources are returned by their ids. If you would like the nested object returned in the body, you can set default_redirection and/or enterprise_connection_onboarding into this parameter.

RETURNS

Returns list of SSO Connection with nested objects if preload_associations set and paginated if related attributes

Redirections after Login

Precise the Default Redirection

If you want to create the Default Redirection for a specific SSO Connection.

If one already exists, this request will create a new one set as default. You will be able to manage these multiples redirection through SSO Connection update request.

Query

curl -X POST 'http://${YOUR_CRYPTR_SERVICE_URL}/api/v2/sso-connections/:idp_id/default-redirection' \
--header 'Authorization: Bearer your_api_key_token' \
--header 'Content-Type: application/json' \
--data-raw '{
"application_id": "81a81b21-93b9-441b-a861-a33dc8c06fea",
"organization_id": "1cad5a97-457c-4a7b-940c-07f5aa22b7f3",
"uri": "http://localhost:3000"
}'


PARAMETERS

application_id * UUID

The reference of application where you want your end-user redirected to.


organization_id * UUID

The reference of organization that owns the application and where your end-user will be stored in


uri URL

The target URI where SSO users will be redirected after successful SSO session. If you do not provide a value either application's default_redirect_url value or first allowed_redirect_urls value will be used.

RETURNS

Returns the created Default Redirection associated to the SSO Connection

Retrieve a Default Redirection

Query

curl -X GET 'http://{{YOUR_CRYPTR_SERVICE_URL}}/api/v2/sso-connections/:idp_id/default-redirection'

RETURNS

Returns the current Default Redirection for the SSO Connection ID provided (idp_idp)

User Policy Configuration

You can change the User policy Configuration with the below request. The User policy is the rule for user coming from the SSO Connection. Posibilities are multiple, if everyone can open a ssession, only ones you registered or only a limited number of seats.

Query

curl -X PUT 'https://${YOUR_CRYPTR_SERVICE_URL}/api/v2/sso-connections/:idp_id/sso-user-policy' \
--header 'Authorization: Bearer your_api_key_generated_token' \
--header 'Content-Type: application/json' \
--data-raw '{
"user_security_type": "user_registered"
}'


PARAMETERS

user_security_type * STRING

The value of User policy you want for this SSO Connection. Values are none, user_registered and user_provisionned

RETURNS

The updated SSO Connection with updated user_security_type value

Unstored users authentication

⚠️ (SOON)

Any successful SSO connection can access to your service independently of Organization users directory (no check of user in database)

User Provisioning automation

user_security_type none

Use the above settings when you want to let all users from the SSO to open a session to your service. When user is unknown in the Organization users' directory, it will be automatically created.

VARIANT:

seats_limit 12

When you define a seats_limit you only allow this quantity of users you want to allow to connect to your service.

Until the amount of users are under the defined value all users are allowed to open a session. When the limit is reached no more user can open a session, two solution are possible to do then, either:

  • a seat is removed (a user is deleted)
  • the value of seats_limit is incremented

Authorize only registered users

user_security_type user_registered

Use the above settings when you want only a specific list of users to open a session through the Sso Connection

When you want a new user to be able to access your service, create the associated user any other user will be blocked.

Admin Onboarding

See SsoAdminOnboarding type

Create the Admin Onboarding

Query

curl -X POST 'https://${YOUR_CRYPTR_SERVICE_URL}/api/v2/sso-connections/:idp_id/admin-onboarding' \
--header 'Authorization: Bearer your_api_key_generated_token' \
--header 'Content-Type: application/json' \
--data-raw '{
"sso_admin_email": "Mathew_Murazik92@yahoo.com"
}'


PARAMETERS

sso_admin_email * STRING EMAIL

The email of the SSO admin of your client that has access to the SSO tool.


provider_type STRING OPTIONAL

If you already know the Provider type (Okta, Azure AD, ADFS, Google Workspace ...) of your client you can preset that and SSO administrator won't have to choose . The SSO Administrator can still change this as soon as he wishes.

RETURNS

The updated SSOAdminOnboarding with proper attributes

Update the Admin Onboarding

This request will helps you update the Onboarding associated to the SSO Connection, for example if the SSO Administrator changed and it's a new email.

Query

curl -X PUT 'https://${YOUR_CRYPTR_SERVICE_URL}/api/v2/sso-connections/:idp_id/admin-onboarding' \
--header 'Authorization: Bearer your_api_key_generated_token' \
--header 'Content-Type: application/json' \
--data-raw '{
"sso_admin_email": "new_it_guy@sample.co",
"provider_type": "azure_ad"
}'

PARAMETERS

sso_admin_email STRING EMAIL

New desired email for the SsoAdminOnboarding.


provider_type STRING

New desired provider type (Okta, Google, Azure AD, ADFS ...) for the SsoAdminOnboarding.

RETURNS

The updated SsoAdminOnboarding with new values.

Send invitation

As soon as you created an SSOAdminOnboarding for a SSO Connection, you can use the following request to send immediately an email to the defined SSO Administrator. It could be useful if you want to do it live with him during a meeting.

It is also helpful when the SSO Administrator lost the configuration link and needs to do it.

⚠️ If no SSOAdminOnboarding nor sso_admin_email the request will fail.

Query

curl -X POST 'https://${YOUR_CRYPTR_SERVICE_URL}/api/v2/sso-connections/:idp_id/invite-admin' \
--header 'Authorization: Bearer your_api_key_generated_token'

RETURNS

An Email is sent to sso_admin_email while the current SSOConnection is rendered

Reset the Admin Onboarding

In some cases the best way to help the SSO Administrator with the configuration is to start from beginning.

This request will reset provider_type , reset tutorial to initial step but sso_admin_email won't be unset

Query

curl -X PATCH 'https://${YOUR_CRYPTR_SERVICE_URL}/api/v2/sso-connections/:idp_id/reset-onboarding' \
--header 'Authorization: Bearer your_api_key_generated_token'

RETURNS

The SSOConnection with reseted SsoAdminOnboarding

New IT admin

Reset the Onboarding

Turn ON/OFF a Connection

⚠️ These requests are in Early access and has for now no impact on Sso Connection availability

Activate the Connection

If you would like to activate the SSO Connection

Query

curl -X PATCH 'https://${YOUR_CRYPTR_SERVICE_URL}/api/v2/sso-connections/:idp_id/activate' \
--header 'Authorization: Bearer your_api_key_generated_token'

Disable the Connection

If you would like to disable the SSO Connection

Query

curl -X PATCH 'https://${YOUR_CRYPTR_SERVICE_URL}/api/v2/sso-connections/:idp_id/disable' \
--header 'Authorization: Bearer your_api_key_generated_token'


Users Signup Webhook

SOON