SSO Management Reference

Create OIDC Client

Creates a new OIDC client configuration for SSO authentication. This allows your customers to authenticate users through their identity provider.

Arguments

• idpInfoFromCustomer (required)

  • idpType: Can equal either Generic, Okta, or MicrosoftEntra.
  • clientId: The Client ID of the OIDC app in your customer's IdP.
  • clientSecret: The Client Secret of the OIDC app in your customer's IdP.
  • usesPkce: If the OIDC app uses PKCE.
  • ssoDomain: Only use when the idpType is set to Okta.
  • tenantId: Only use when the idpType is set to MicrosoftEntra.
  • authUrl: The Auth URL of the OIDC app in your customer's IdP.
  • tokenUrl: The Token URL of the OIDC app in your customer's IdP.
  • userinfoUrl: The User Info URL of the OIDC app in your customer's IdP.

• customerId (required)
  The ID of the user/group/organization that the OIDC client is getting created for. Each Customer ID is allowed only one OIDC connection. If using SCIM, this value should match the Customer ID of the customer's SCIM connection.

• redirectUrl (required)
  Your application's callback URL that handles the OIDC response and calls Complete OIDC Login.

• displayName
  The user-facing display name for the OIDC client.

• additionalScopes
  Additional scopes to request from the IdP.

• scimMatchingDefinition
  The SCIM linking strategy for the OIDC client. Can equal OidcSubToScimUsername, OidcSubToScimExternalId, OidcEmailToScimUsername, OidcEmailUsernameToScimUsername, or OidcPreferredUsernameToScimUsername.

• emailDomainAllowlist
  A list of email domains to allow for the OIDC client.

Successful Response

• clientId
  The ID of the created OIDC client

Error Types

• InvalidFields
  One or more provided fields contain invalid values
• ClientIdAlreadyTaken
  The specified client ID is already in use
• CustomerIdAlreadyTakenForEoidcClient
  This customer already has an OIDC client configured
• UnexpectedError
  An unexpected error occurred during the operation

const auth = createClient({ url, integrationKey });

const result = await auth.sso.management.createOidcClient({
  idpInfoFromCustomer: {
    idpType: "Okta",
    clientId: "0oaulhbkt9YBiT3Pn697",
    clientSecret: "MHppDLafzd...",
    ssoDomain: "example.okta.com",
    usesPkce: true,
  },
  customerId: "106ce124-108...",
  redirectUrl: "https://app.example.com/authorization-code/callback",
  displayName: "Okta OIDC Client",
  additionalScopes: ["groups"],
  emailDomainAllowlist: ["example.com"],
  scimMatchingDefinition: {
    strategy: "OidcEmailUsernameToScimUsername"
  }
});

if (result.ok) {
  console.log("OIDC client created successfully");
  console.log(`Client ID: ${result.data.clientId}`);
} else {
  console.log(`Error: ${result.error}`);
}

client = create_client(url=url, integration_key=integration_key)

result = await client.sso.management.create_oidc_client(
    idp_info_from_customer=IdpInfoFromCustomerOkta(
        client_id="0oaulhbkt9YBiT3Pn697",
        client_secret="MHppDLafzd...",
        sso_domain="example.okta.com",
        uses_pkce=True,
    ),
    customer_id="106ce124-108...",
    redirect_url="https://app.example.com/authorization-code/callback",
    display_name="Okta OIDC Client",
    additional_scopes=["groups"],
    email_domain_allowlist=["example.com"],
    scim_matching_definition=ScimMatchingDefinition(
        strategy="OidcEmailUsernameToScimUsername"
    )
)
if is_ok(result):
    print("OIDC client created successfully")
    print(f"Client ID: {result.data.client_id}")
else:
    raise HTTPException(status_code=500, detail="Internal server error")

Fetch OIDC Client

Retrieves the configuration details of an existing OIDC client.

Arguments

• oidcClientId
  The OIDC client ID to fetch (use either this or customerId, not both)
• customerId
  The customer ID associated with the OIDC client (use either this or oidcClientId, not both)

Successful Response

• idpInfoFromCustomer.idpType
  The type of identity provider (Generic, Okta, or MicrosoftEntra)
• idpInfoFromCustomer.clientId
  The client ID from the customer's IdP
• idpInfoFromCustomer.usesPkce
  Whether PKCE is enabled for this OIDC client
• idpInfoFromCustomer.ssoDomain
  The SSO domain (only present when idpType is Okta)
• idpInfoFromCustomer.tenantId
  The tenant ID (only present when idpType is MicrosoftEntra)
• idpInfoFromCustomer.authUrl
  The authorization URL (only present when idpType is Generic)
• idpInfoFromCustomer.tokenUrl
  The token URL (only present when idpType is Generic)
• idpInfoFromCustomer.userinfoUrl
  The user info URL (only present when idpType is Generic)
• customerId
  The customer ID associated with this OIDC client
• redirectUrl
  The configured redirect URL for this OIDC client
• displayName
  The display name of the OIDC client
• additionalScopes
  Additional OAuth scopes configured for this client
• emailDomainAllowlist
  List of allowed email domains
• scimMatchingDefinition
  The SCIM matching strategy
• scimConnection.connectionId
  The ID of the associated SCIM connection
• scimConnection.customerId
  The customer ID of the SCIM connection

Error Types

• OidcClientNotFound
  No OIDC client found for the provided oidcClientId or customerId
• UnexpectedError
  An unexpected error occurred during the operation

Patches and Deletions

Patch OIDC Client

Updates an existing OIDC client configuration. All fields are optional - only provide the fields you want to update.

Arguments

• oidcClientId
  The OIDC client ID to update (use either this or customerId, not both)
• customerId
  The customer ID of the OIDC client to update (use either this or oidcClientId, not both)
• idpInfoFromCustomer (optional)
  Updated identity provider configuration.
• displayName
  Updated display name for the OIDC client
• redirectUrl
  Updated redirect URL for the OIDC client
• additionalScopes
  Updated list of additional OAuth scopes to request
• emailDomainAllowlist
  Updated list of allowed email domains
• scimMatchingDefinition
  Updated SCIM matching strategy.

Successful Response

• clientId
  The ID of the updated OIDC client

Error Types

• OidcClientNotFound
  No OIDC client found for the provided oidcClientId or customerId
• InvalidFields
  One or more provided fields contain invalid values
• UnexpectedError
  An unexpected error occurred during the operation

Delete OIDC Client

Permanently deletes an OIDC client.

Arguments

• oidcClientId
  The OIDC client ID to delete (use either this or customerId, not both)
• customerId
  The customer ID of the OIDC client to delete (use either this or oidcClientId, not both)

Successful Response

Returns an empty response on success

Error Types

Configuring SSO Settings

You can configure SSO settings, such as allowed redirect origins, in the 'sso_config.jsonc' config file.

Arguments

• post_login_redirect_origin_allowlist
  A list of allowed origins (scheme + host + optional port) that can be used in the post_login_redirect_url parameter when initiating SSO login. If the URL specified in the login request does not match one of these origins, the login request will be rejected.

{
    "post_login_redirect_origin_allowlist": [
        // "https://example.com",
    ],
}