# Single Sign-On (SSO)



Overview [#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.

<span id="step-1-idp-registration" />

Step 1: Register Socotra as a New Application in Your Identity Provider [#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 [#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 <ApiLink name="addSAMLIdentityProvider">Add a SAML Identity Provider</ApiLink> 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](#step-1-idp-registration).

Sample request [#sample-request]

```javascript
{
    "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 [#step-3-receive-service-provider-sp-metadata-from-socotra]

After processing your <ApiLink name="addSAMLIdentityProvider">Add a SAML Identity Provider</ApiLink> 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 [#sample-response]

```javascript
{
    "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 [#step-4-configure-your-identity-provider-with-socotras-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 [#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.

<Callout>
  IdP-initiated SAML login is not yet supported. To authenticate, users must start the login process from Socotra.
</Callout>

Key SSO Capability Clarifications [#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](/api/business-accounts/user-management).

<Callout>
  Automated attribute mapping for user roles and permissions assignment is not yet supported.
</Callout>