Single Sign-On (SSO)

Overview

Setting up Single Sign-On (SSO) with Socotra involves a multi-step process that integrates your Identity Provider (IdP) with Socotra’s user authentication service. This guide outlines the necessary steps to configure SAML-based SSO, ensuring a seamless and secure authentication experience for your users.

Step 1: Register Socotra as a New Application in Your Identity Provider

Begin by configuring your IdP to recognize Socotra as a trusted service provider. This setup allows your IdP to authenticate users attempting to access Socotra services.

Access Your IdP’s Administration Console: Log in to the administrative interface of your IdP (e.g., Azure AD, Auth0, Google SAML).
Add a New Application: Initiate the process to register a new application. This option is typically labeled as “Add Application” or “Register App.”
Capture the Single Sign-On Service URL: Early in the app registration process, your IdP will create an SSO URL that needs to be registered with Socotra.

Step 2: Add your Identity Provider to Socotra

Next, you’ll need to share your IdP’s SAML metadata with Socotra to establish a trust relationship between the two systems.

To do so, use the Add a SAML Identity Provider endpoint, providing the following in the request body:

id: A string that will uniquely identify the IdP in the context of your Socotra business account.

displayName: (Optional) A string that will be used when viewing the IdP setup via the System Manager UI.

SSO URL: The URL captured during the initial app registration process in Step 1 above.

Sample request

{
    "id": "my-test-idp",
    "displayName": "Google SAML Test",
    "singleSignOnServiceUrl": "https://accounts.google.com/o/saml2/idp?idpid=XXXXXXXX"
}

Step 3: Receive Service Provider (SP) Metadata from Socotra

After processing your Add a SAML Identity Provider in the previous step, Socotra will generate and respond with its own Service Provider (SP) metadata, which you’ll need to configure within your IdP. From this response, grab the following details:

Entity ID: Socotra’s unique identifier within your IdP.
Assertion Consumer Service (ACS) URL: The endpoint on Socotra’s side that will receive SAML assertions from your IdP.

Sample response

{
    "id": "my-test-idp",
    "displayName": "Google SAML Test",
    "type": "saml",
    "acsUrl": "https://kern-dev-idp.socotra.com/auth/realms/XXXX/broker/my-test-idp/endpoint",
    "entityId": "https://kern-dev-idp.socotra.com/auth/realms/XXXX",
    "singleSignOnServiceUrl": "https://accounts.google.com/o/saml2/idp?idpid=XXXXXXXX"
}

Step 4: Configure Your Identity Provider with Socotra’s SP Metadata

Integrate Socotra’s SP metadata into your IdP to finalize the SSO setup.

Access IdP’s Application Settings: Navigate to the application configuration section within your IdP’s administrative console and update the following SAML settings:
- ACS URL: Input Socotra’s Assertion Consumer Service URL.
- Entity ID: Enter Socotra’s Entity ID as provided in their SP metadata.
- Single Logout URL: If applicable, configure the Single Logout URL as specified by Socotra.

Step 5: Test the SSO Integration

Verify that the SSO configuration functions correctly before rolling it out to all users.

Initiate SSO Login: When attempting to log in to Socotra using the SSO option, the login screen will present options to sign in via your IdP. Look for the Or sign in with section.
Verify Authentication: Ensure that the authentication process redirects you to your IdP for login and subsequently grants access to Socotra upon successful authentication.

Key SSO Capability Clarifications

Once the IdP App Registration and setup is complete, you control Socotra access for users belonging to that authentication realm within the IdP itself.
Depending on the IdP, the default may be that none, or all, of the users are initially granted access.
The SSO process defers to the IdP for user authentication only. Roles, permission and tenant scope is still controlled within the Socotra User Management Service.

Note

Automated attribute mapping for user roles and permissions assignment is not yet supported.