SSO Applications

If you want to view the SDK documentation for Application Management, click here.

Descope allows you to configure Applications within the Applications page. Within this page, you can configure your OIDC and SAML applications.

When using OIDC applications, Descope becomes the Federated Identity Provider allowing you to unify your user's login experience across multiple providers.

When using Descope SAML applications, Descope becomes the Identity Provider itself.

This page is an overview of the OIDC and SAML protocols that Application support.

It also highlights the difference between an IdP and SP as it relates to Applications, and how you can associate Applications with users.

You can learn more about creating new applications within Descope from the following documentation guides: SAML Applications or OIDC Applications

Note

Configuring custom applications is an Pro/Enterprise-tier feature.

Associating Users with Applications

Users can be associated with Applications when using Descope as a SAML/OIDC provider. If you wish to restrict the user's ability to sign up or in, with a specific Application, you can utilize this feature to do so. You can do this either in the Console or via the Management SDKs.

Managing Applications Using the Management SDK

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 clientyou can also configure the baseUrl ex: https://auth.company.com  - this is useful when you utilize CNAME within your Descope project.
    const descopeClient = DescopeClient({ projectId: '__ProjectID__', managementKey: managementKey });
} catch (error) {
    // handle the error
    console.log("failed to initialize: " + error)
}
 
// Note that you can handle async operation failures and capture specific errors to customize errors.
//     An example can be found here: https://github.com/descope/node-sdk?tab=readme-ov-file#error-handling

Load All Applications

Load all Applications.

const resp = await descopeClient.management.ssoApplication.loadAll()
if (!resp.ok) {
  console.log("Failed to load Applications.")
  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 Applications.")
  console.log(resp.data)
}

Load a Specific Application

Load an Application by ID.

// Args:
//  id (str): The ID of the sso application to load.
const id = "xxxxx"
 
const resp = await descopeClient.management.ssoApplication.load(id)
if (!resp.ok) {
  console.log("Failed to load Application.")
  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 Application.")
  console.log(resp.data)
}

Create OIDC Application

Create a new OIDC Application with the given name. Application IDs are provisioned automatically but can be explicitly configured if needed. Both the name and ID must be unique per project.

//  Args:
//    oidcApplicationOptions (OidcApplicationOptions): Options for the OIDC Application create and update
const oidcApplicationOptions = {
  "name": "My OIDC Application",
  "loginPageUrl": "https://my-idp-application.com/login",
  // "id": (optional),
  "description": "This is my OIDC Application",
  "logo": "https://my-idp-application.com/logo",
  "enabled": true
}
 
const resp = await descopeClient.management.ssoApplication.createOidcApplication(oidcApplicationOptions)
if (!resp.ok) {
  console.log("Failed to create OIDC Application.")
  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 created OIDC Application.")
  console.log(resp.data)
}

Update OIDC Application

Update an existing OIDC Application with the given parameters.

Note

All provided parameters are used as overrides to the existing application. Empty fields will override populated fields.

//  Args:
//    oidcApplicationOptions (OidcApplicationOptions): Options for the OIDC Application create and update
const oidcApplicationOptions = {
  "name": "My OIDC Application",
  "loginPageUrl": "https://my-idp-application.com/login",
  "id": "xxxxx",
  "description": "This is my OIDC Application",
  "logo": "https://my-idp-application.com/logo",
  "enabled": true
}
 
const resp = await descopeClient.management.ssoApplication.updateOidcApplication(oidcApplicationOptions)
if (!resp.ok) {
  console.log("Failed to update OIDC Application.")
  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 updated OIDC Application.")
  console.log(resp.data)
}

Create SAML Application

Create a new SAML Application with the given name. Application IDs are provisioned automatically but can be explicitly configured if needed. Both the name and ID must be unique per project.

//  Args:
//    samlApplicationOptions (SamlApplicationOptions): Options for the SAML Application create and update
const samlApplicationOptions = {
  "name": "My SAML Application",
  "loginPageUrl": "https://my-idp-application.com/login",
  // "id": (optional),
  "description": "This is my SAML Application",
  "logo": "https://my-idp-application.com/logo",
  "enabled": true,
  "useMetadataInfo": true,
  "metadataUrl": "https://myapp.com/metadata",
  // entityId?: (optional),
  // "acsUrl": (optional),
  // "certificate": (optional),
  // "attributeMapping": (optional),
  // "groupsMapping": (optional),
  // "acsAllowedCallbacks": (optional),
  // "subjectNameIdType": (optional),
  // "subjectNameIdFormat": (optional)
}
 
const resp = await descopeClient.management.ssoApplication.createSamlApplication(samlApplicationOptions)
if (!resp.ok) {
  console.log("Failed to create SAML Application.")
  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 created SAML Application.")
  console.log(resp.data)
}

Update SAML Application

Update an existing SAML Application with the given parameters.

Note

All provided parameters are used as overrides to the existing application. Empty fields will override populated fields.

//  Args:
//    samlApplicationOptions (SamlApplicationOptions): Options for the SAML Application create and update
const samlApplicationOptions = {
  "name": "My SAML Application",
  "loginPageUrl": "https://my-idp-application.com/login",
  // "id": (optional),
  "description": "This is my SAML Application",
  "logo": "https://my-idp-application.com/logo",
  "enabled": true,
  "useMetadataInfo": true,
  "metadataUrl": "https://myapp.com/metadata",
  // entityId?: (optional),
  // "acsUrl": (optional),
  // "certificate": (optional),
  // "attributeMapping": (optional),
  // "groupsMapping": (optional),
  // "acsAllowedCallbacks": (optional),
  // "subjectNameIdType": (optional),
  // "subjectNameIdFormat": (optional)
}
 
const resp = await descopeClient.management.ssoApplication.updateSamlApplication(samlApplicationOptions)
if (!resp.ok) {
  console.log("Failed to update SAML Application.")
  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 updated SAML Application.")
  console.log(resp.data)
}

Delete an Application

Delete an existing Application.

Note

This action is irreversible. Use carefully.

// Args:
//  id (str): The ID of the sso application to delete.
const id = "xxxxx"
 
const resp = await descopeClient.management.ssoApplication.delete(id)
if (!resp.ok) {
  console.log("Failed to delete Application.")
  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 Application.")
  console.log(resp.data)
}

Was this helpful?

On this page