SSO with Management SDKs

You must configure SSO for each tenant independently. These settings can be configured via the Descope Console, the SSO Setup Suite, the Management tenants SSO API, or the SDK as shown below.

To start an SSO login (redirect + code exchange), use the auth SSO API or SSO with Backend SDKs — that is separate from configuring a tenant's IdP connection.

These are all of the SDK functions you can use in your backend to configure and manage SSO for your tenants.

Install SDK

Terminal

npm i --save @descope/node-sdk

Import and initialize Management SDK

import DescopeClient from '@descope/node-sdk';

const managementKey = "xxxx"

try{
    //  baseUrl="<URL>" // When initializing the Descope client, you can also configure the baseUrl ex: https://auth.company.com  - this is useful when you utilize a custom domain within your Descope project.
    const descopeClient = DescopeClient({ projectId: '__ProjectID__', managementKey: managementKey });
} catch (error) {
    // handle the error
    console.log("failed to initialize: " + error)
}

Identity Provider (IdP) Details

You can either set the identity provider details using a metadata URL from the IdP or enter them in the console. The values for each field can be obtained from the admin console of the identity provider.

// Configure SSO setting for a tenant manually. Alternatively, `configure_via_metadata` can be used instead.
// Args:
//    tenantId (str): The tenant ID to be configured
const tenantId = "xxxxxx"
//    idpURL (str): The URL for the identity provider.
const idpURL = "https://example_idpURL.com"
//    entityId (str): The entity ID (in the IDP).
const entityId = "descope"
//    idpCert (str): The certificate provided by the IDP.
const idpCert = "xxxxxx"
//    redirectURL (str): An Optional Redirect URL after successful authentication.
const redirectURL = "https://example_descope_app.com/saml"
//    domain (str): An optional domain used to associate users authenticating via SSO with this tenant
const domain = "example_descope_app.com"

let resp = await descopeClient.management.sso.configureSettings(tenantId, idpURL, idpCert, entityId, redirectURL, domain)
if (!resp.ok) {
  console.log("Unable to configure tenant sso.")
  console.log("Status Code: " + resp.code)
  console.log("Error Code: " + resp.error.errorCode)
  console.log("Error Description: " + resp.error.errorDescription)
  console.log("Error Message: " + resp.error.errorMessage)
}
else {
  console.log("Successfully configured sso configuration for tenant manually.")
  console.log(resp.data)
}

// Configure SSO setting for am IDP metadata URL. Alternatively, `configure` can be used instead.
// Args:
//   tenantId (str): The tenant ID to be configured
const tenantId = "xxxxxx"
//   idpMetadataURL (str): The URL to fetch SSO settings from.
const idpMetadataURL = "https://example_idpURL.com/api/v1/apps/xxxxxxx/sso/saml/metadata?"
//    redirectURL (str): An Optional Redirect URL after successful authentication.
const redirectURL = "https://example_descope_app.com/saml"
//    domain (str): An optional domain used to associate users authenticating via SSO with this tenant
const domain = "example_descope_app.com"

let resp = await descopeClient.management.sso.configureMetadata(tenantId, idpMetadataURL, redirectURL, domain)
if (!resp.ok) {
  console.log("Unable to configure tenant sso.")
  console.log("Status Code: " + resp.code)
  console.log("Error Code: " + resp.error.errorCode)
  console.log("Error Description: " + resp.error.errorDescription)
  console.log("Error Message: " + resp.error.errorMessage)
}
else {
  console.log("Successfully configured sso configuration for tenant via metadata url.")
  console.log(resp.data)
}

Configure SSO Redirect URL

You can update only the redirect URLs for a specific SSO configuration without touching the rest of the IdP settings. Leave either URL unset (using whichever "no value" convention your chosen SDK uses, such as nil, None, or null) to leave it unchanged, but make sure to provide a valid URL for at least one of them.

// Args:
//    tenantId (str): The tenant ID to be configured.
const tenantId = "xxxxxx"
//    samlRedirectUrl (str): Optional redirect URL for SAML SSO. Leave undefined to leave unchanged.
const samlRedirectUrl = "https://example_descope_app.com/saml"
//    oauthRedirectUrl (str): Optional redirect URL for OAuth SSO. Leave undefined to leave unchanged.
const oauthRedirectUrl = "https://example_descope_app.com/oauth"
//    ssoId (str): Optional SSO configuration ID (only needed if the tenant has multiple SSO configs).
const ssoId = ""

let resp = await descopeClient.management.sso.configureSSORedirectURL(tenantId, samlRedirectUrl, oauthRedirectUrl, ssoId)
if (!resp.ok) {
  console.log("Unable to configure SSO redirect URL.")
  console.log("Status Code: " + resp.code)
  console.log("Error Code: " + resp.error.errorCode)
  console.log("Error Description: " + resp.error.errorDescription)
  console.log("Error Message: " + resp.error.errorMessage)
}
else {
  console.log("Successfully configured SSO redirect URL.")
}

Load SSO Configuration

Descope allows you to load the SSO config for a specified tenant.

// Args:
//    tenantId (str): The tenant ID to get the SSO configuration from.
const tenantId = "xxxxxx"
//    ssoId (str): The SSO ID to get the SSO configuration for if the tenant has multiple SSO configs
const ssoId = "xxxxxx"

// You can pass ssoId in case you want to load a specific SSO configuration
const ssoSettings = await descopeClient.management.sso.loadSettings('tenantId', 'ssoId');

// You can get all configured SSO settings for a specific tenant if the tenant has multiple SSO configs
const allSSOSettings = await descopeClient.management.sso.loadAllSettings('tenantId');

Delete SSO Configuration

Descope allows you to delete the SSO config for a specified tenant. Use caution with this SDK call as it will remove the configuration and is irreversible.

// Args:
//   tenantId (str): The tenant ID to delete the SSO configuration from.
const tenantId = "xxxxxx"

// You can optionally pass in the ssoId if the tenant has multiple SSO configs
let resp = await descopeClient.management.sso.deleteSettings(tenantId, ssoId)
if (!resp.ok) {
  console.log("Unable to delete the sso configuration from tenant.")
  console.log("Status Code: " + resp.code)
  console.log("Error Code: " + resp.error.errorCode)
  console.log("Error Description: " + resp.error.errorDescription)
  console.log("Error Message: " + resp.error.errorMessage)
}
else {
  console.log("Successfully deleted sso configuration from tenant.")
}

SSO Mapping

SSO User Attribute Mapping

In this section of the console, you can setup mapping for user attributes. After you set up the mapping, each user that signs into your application will get these attributes assigned from the IdP.

Note

Descope also allows you to map attributes from your IdP to custom user attributes when configuring your attribute mapping.

Groups Mapping

In this part of SSO configuration, you can map SSO groups from your IdP to roles defined in Descope service. The group-to-role mapping will automatically populate the user's roles at the time of sign-in. The roles are included in the session token after successful authentication. It is important to note, this function overrides any previous mapping (even when empty).

// Args:
//   tenantId (str): The tenant ID to be configured
const tenantId = "xxxxxx"
//    roleMappings (RoleMapping): A mapping between IDP groups and Descope roles.
const roleMapping = { groups: ['IDP_ADMIN'], roleName: 'Tenant Admin'}
//    attributeMapping (AttributeMapping): A mapping between IDP user attributes and descope attributes.
const attributeMapping = {name: "IDP_NAME", phoneNumber: "IDP_PHONE",}

let resp = await descopeClient.management.sso.configureMapping(tenantId, roleMapping, attributeMapping)
if (!resp.ok) {
  console.log("Unable to configured sso role and attribute mapping.")
  console.log("Status Code: " + resp.code)
  console.log("Error Code: " + resp.error.errorCode)
  console.log("Error Description: " + resp.error.errorDescription)
  console.log("Error Message: " + resp.error.errorMessage)
}
else {
  console.log("Successfully configured sso role and attribute mapping.")
}

SSO Group Management

The Descope SDKs make the SSO Groups available for being loaded. The below covers the available functions.

Load All Groups

Descopers can load all groups for a given tenant, the below covers examples of this.

// Args:
//  tenantId (str): Tenant ID to load groups from.
const tenantId = "xxxxx"

const resp = await descopeClient.management.group.loadAllGroups(tenantId)
if (!resp.ok) {
  console.log(resp)
  console.log("Unable to load all groups.")
  console.log("Status Code: " + resp.code)
  console.log("Error Code: " + resp.error.errorCode)
  console.log("Error Description: " + resp.error.errorDescription)
  console.log("Error Message: " + resp.error.errorMessage)
}
else {
  console.log("Successfully loaded all groups.")
  console.log(resp.data)
}

Load All Groups for Members

Descopers can load all groups for members based on login IDs and user IDs, the below covers examples of this.

// Args:
//  tenantId (str): Tenant ID to load groups from.
const tenantId = "xxxxx"
//  userIDs (List[str]): Optional List of user IDs, with the format of "U2J5ES9S8TkvCgOvcrkpzUgVTEBM" (example), which can be found on the user's JWT.
const userIds = []
//  loginIDs (List[str]): Optional List of login IDs, how the users identify when logging in.
const loginIds = []

const resp = await descopeClient.management.group.loadAllGroupsForMembers(tenantId, userIds, loginIds)
if (!resp.ok) {
  console.log(resp)
  console.log("Unable to load all groups for members.")
  console.log("Status Code: " + resp.code)
  console.log("Error Code: " + resp.error.errorCode)
  console.log("Error Description: " + resp.error.errorDescription)
  console.log("Error Message: " + resp.error.errorMessage)
}
else {
  console.log("Successfully loaded all groups for members.")
  console.log(resp.data)
}

Load All Group Members

Descopers can load all groups members based on tenant ID and group ID, the below covers examples of this.

// Args:
//  tenantId (str): Tenant ID to load groups from.
const tenantId = "xxxxx"
//  groupId (str): Group ID to load members for.
const groupId = "xxxx"

const res = await descopeClient.management.group.loadAllGroupMembers(tenantId, groupId)
if (!resp.ok) {
  console.log(resp)
  console.log("Unable to load all group members.")
  console.log("Status Code: " + resp.code)
  console.log("Error Code: " + resp.error.errorCode)
  console.log("Error Description: " + resp.error.errorDescription)
  console.log("Error Message: " + resp.error.errorMessage)
}
else {
  console.log("Successfully loaded all group members.")
  console.log(resp.data)
}

Generate SSO Configuration Link

Generate an SSO admin link for a tenant that allows a tenant administrator to configure SSO settings. The generated link can be sent to tenant administrators via email or displayed in your application. Once accessed, the link allows the administrator to configure their tenant's SAML or OIDC SSO settings through a guided interface.

The expiration parameter is a duration in seconds.

Therefore, to retrieve a link valid for 6 hours, pass 21600.

// Args:
//   tenantId (string): The ID of the tenant for which to generate the SSO configuration link.
const tenantId = "my-tenant-id";
//   expireDuration (number): Expiration duration in seconds. For a 6-hour link, use 21600.
const expireDuration = 21600; // 6 hours
//   ssoId (string, optional): SSO identifier for the tenant.
const ssoId = "my-sso-id";
//   email (string, optional): Email address associated with the admin.
const email = "admin@example.com";
//   templateId (string, optional): Template ID to use for the configuration page.
const templateId = "my-template-id";
//   actorId (string, optional): When provided, this id is recorded as the audit actor for actions
//     performed inside the SSO Setup Suite (instead of the temporary user). Used as-is for
//     audit attribution and is not validated.
const actorId = "my-admin-actor-id";

try {
  const resp = await descopeClient.management.tenant.generateSSOConfigurationLink(
    tenantId,
    expireDuration,
    ssoId,
    email,
    templateId,
    actorId
  );
  
  if (resp.ok) {
    console.log("Successfully generated SSO configuration link:");
    console.log(resp.data.adminSSOConfigurationLink);
  } else {
    console.log("Failed to generate SSO configuration link");
    console.log("Status Code: " + resp.code);
    console.log("Error: " + resp.error.errorMessage);
  }
} catch (error) {
  console.log("Failed to generate SSO configuration link: " + error);
}

Was this helpful?

On this page