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 IdpInfoFromCustomer required

Information to retrieve from your customer. See the IdP Info docs for more information.

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 string 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 string required

Your application's callback URL that handles the OIDC response and calls Complete OIDC Login. You provide this URL to your customer to register in their IdP.

displayName string

The user-facing display name for the OIDC client.

additionalScopes string[]

Additional scopes to request from the IdP.

scimMatchingDefinition ScimMatchingDefinition

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

emailDomainAllowlist string[]

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

Successful Response

clientId string

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 });

// For other IdP types, use idpType: "Generic" or "MicrosoftEntra"
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}`);
  // Check result.error.type to handle specific errors
}

from propelauth_byo.generated.idp_info_from_customer import IdpInfoFromCustomerOkta
from propelauth_byo.generated.scim_matching_definition import ScimMatchingDefinition

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

# For other IdP types, use IdpInfoFromCustomerGeneric or IdpInfoFromCustomerMicrosoftEntra
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")

PropelAuthClient client = PropelAuthClient.create(url, integrationKey);

// For other IdP types, use IdpInfoFromCustomer.Generic or IdpInfoFromCustomer.MicrosoftEntra
CreateOidcClientCommand command = CreateOidcClientCommand.builder()
    .idpInfoFromCustomer(IdpInfoFromCustomer.Okta.builder()
        .clientId("0oaulhbkt9YBiT3Pn697")
        .clientSecret("MHppDLafzd...")
        .ssoDomain("example.okta.com")
        .usesPkce(true)
        .build())
    .customerId("106ce124-108...")
    .redirectUrl("https://app.example.com/authorization-code/callback")
    .displayName("Okta OIDC Client")
    .additionalScopes(Arrays.asList("groups"))
    .emailDomainAllowlist(Arrays.asList("example.com"))
    .scimMatchingDefinition(ScimMatchingDefinition.builder()
        .strategy(ScimUserMatchingStrategy.OidcEmailUsernameToScimUsername)
        .build())
    .build();

try {
    CreateOidcClientResponse response = client.sso.management.createOidcClient(command);
    System.out.println("OIDC client created successfully");
    System.out.println("Client ID: " + response.getClientId());
} catch (CreateOidcClientException.InvalidFields e) {
    System.out.println("Invalid fields: " + e.getDetails());
} catch (CreateOidcClientException.ClientIdAlreadyTaken e) {
    System.out.println("Client ID already taken");
} catch (CreateOidcClientException.CustomerIdAlreadyTakenForEoidcClient e) {
    System.out.println("Customer already has an OIDC client");
} catch (CreateOidcClientException e) {
    System.out.println("Error: " + e.getMessage());
}

var client = new PropelAuthClient(new PropelAuthOptions { Url = url, IntegrationKey = integrationKey });

// For other IdP types, use IdpInfoFromCustomerGeneric or IdpInfoFromCustomerMicrosoftEntra
var command = new CreateOidcClientCommand
{
    IdpInfoFromCustomer = new IdpInfoFromCustomerOkta
    {
        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 = new List<string> { "groups" },
    EmailDomainAllowlist = new List<string> { "example.com" },
    ScimMatchingDefinition = new ScimMatchingDefinition
    {
        Strategy = ScimUserMatchingStrategy.OidcEmailUsernameToScimUsername
    }
};

try
{
    var response = await client.Sso.Management.CreateOidcClientAsync(command);
    Console.WriteLine("OIDC client created successfully");
    Console.WriteLine($"Client ID: {response.ClientId}");
}
catch (CreateOidcClientException.InvalidFields ex)
{
    Console.WriteLine($"Invalid fields: {ex.Details}");
}
catch (CreateOidcClientException.ClientIdAlreadyTaken)
{
    Console.WriteLine("Client ID already taken");
}
catch (CreateOidcClientException.CustomerIdAlreadyTakenForEoidcClient)
{
    Console.WriteLine("Customer already has an OIDC client");
}
catch (CreateOidcClientException ex)
{
    Console.WriteLine($"Error: {ex.Message}");
}

Response

{
  ok: true,
  data: {
    clientId: "0oaulhbkt9YBiT3Pn697"
  }
}

Result(
    data=CreateOidcClientResponse(
        client_id="0oaulhbkt9YBiT3Pn697"
    )
)

CreateOidcClientResponse(
    clientId="0oaulhbkt9YBiT3Pn697"
)

CreateOidcClientResponse
{
    ClientId = "0oaulhbkt9YBiT3Pn697"
}

Fetch OIDC Client

Retrieves the configuration details of an existing OIDC client.

Arguments

oidcClientId string

The OIDC client ID to fetch (use either this or customerId, not both)

customerId string

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

Successful Response

idpInfoFromCustomer.idpType string

The type of identity provider (Generic, Okta, or MicrosoftEntra)

idpInfoFromCustomer.clientId string

The client ID from the customer's IdP

idpInfoFromCustomer.usesPkce boolean

Whether PKCE is enabled for this OIDC client

idpInfoFromCustomer.ssoDomain string

The SSO domain (only present when idpType is Okta)

idpInfoFromCustomer.tenantId string

The tenant ID (only present when idpType is MicrosoftEntra)

idpInfoFromCustomer.authUrl string

The authorization URL (only present when idpType is Generic)

idpInfoFromCustomer.tokenUrl string

The token URL (only present when idpType is Generic)

idpInfoFromCustomer.userinfoUrl string

The user info URL (only present when idpType is Generic)

customerId string

The customer ID associated with this OIDC client

redirectUrl string

The configured redirect URL for this OIDC client

displayName string

The display name of the OIDC client

additionalScopes string[]

Additional OAuth scopes configured for this client

emailDomainAllowlist string[]

List of allowed email domains

scimMatchingDefinition string

The SCIM matching strategy (OidcSubToScimUsername, OidcSubToScimExternalId, OidcEmailToScimUsername, OidcEmailUsernameToScimUsername, or OidcPreferredUsernameToScimUsername)

scimConnection.connectionId string

The ID of the associated SCIM connection

scimConnection.customerId string

The customer ID of the SCIM connection

scimConnection.displayName string

The display name of the SCIM connection

scimConnection.scimApiKeyValidUntil number

Unix timestamp when the SCIM API key expires

scimConnection.userMapping object

The user mapping configuration for SCIM

Error Types

OidcClientNotFound

No OIDC client found for the provided oidcClientId or customerId

UnexpectedError

An unexpected error occurred during the operation

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

const result = await auth.sso.management.fetchOidcClient({
  customerId: "106ce124-108..."
});

if (result.ok) {
  console.log("OIDC client fetched successfully");
  console.log(`Client ID: ${result.data.idpInfoFromCustomer.clientId}`);
  console.log(`Display Name: ${result.data.displayName}`);
} else {
  console.log(`Error: ${result.error}`);
  // Check result.error.type to handle specific errors
}

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

result = await client.sso.management.fetch_oidc_client(
    customer_id="106ce124-108..."
)

if is_ok(result):
    print("OIDC client fetched successfully")
    print(f"Client ID: {result.data.idp_info_from_customer.client_id}")
    print(f"Display Name: {result.data.display_name}")
else:
    raise HTTPException(status_code=500, detail="Internal server error")

PropelAuthClient client = PropelAuthClient.create(url, integrationKey);

FetchOidcClientCommand command = FetchOidcClientCommand.customerId.builder()
    .customerId("106ce124-108...")
    .build();

try {
    FetchOidcClientResponse response = client.sso.management.fetchOidcClient(command);
    System.out.println("OIDC client fetched successfully");
    System.out.println("Client ID: " + response.getIdpInfoFromCustomer().getClientId());
    System.out.println("Display Name: " + response.getDisplayName());
} catch (FetchOidcClientException.OidcClientNotFound e) {
    System.out.println("OIDC client not found");
} catch (FetchOidcClientException e) {
    System.out.println("Error: " + e.getMessage());
}

var client = new PropelAuthClient(new PropelAuthOptions { Url = url, IntegrationKey = integrationKey });

try
{
    var response = await client.Sso.Management.FetchOidcClientByCustomerIdAsync(
        customerId: "106ce124-108..."
    );

    Console.WriteLine("OIDC client fetched successfully");
    Console.WriteLine($"Client ID: {response.IdpInfoFromCustomer.ClientId}");
    Console.WriteLine($"Display Name: {response.DisplayName}");
}
catch (FetchOidcClientException.OidcClientNotFound)
{
    Console.WriteLine("OIDC client not found");
}
catch (FetchOidcClientException ex)
{
    Console.WriteLine($"Error: {ex.Message}");
}

Response

{
  ok: true,
  data: {
    idpInfoFromCustomer: {
      idpType: "Okta",
      clientId: "0oaulhbkt9YBiT3Pn697",
      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"
    },
    scimConnection: {
      connectionId: "scim_conn_123...",
      customerId: "106ce124-108...",
      displayName: "Example SCIM Connection",
      scimApiKeyValidUntil: 1735689600,
      userMapping: {
        userSchema: [/* mapping fields */]
      }
    }
  }
}

Result(
    data=FetchOidcClientResponse(
        idp_info_from_customer=IdpInfoFromCustomerResponseOkta(
            client_id="0oaulhbkt9YBiT3Pn697",
            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"
        ),
        scim_connection=FetchScimConnectionResponse(
            connection_id="scim_conn_123...",
            customer_id="106ce124-108...",
            display_name="Example SCIM Connection",
            scim_api_key_valid_until=1735689600,
            user_mapping={...}
        )
    )
)

FetchOidcClientResponse(
    idpInfoFromCustomer=IdpInfoFromCustomerResponse.Okta(
        clientId="0oaulhbkt9YBiT3Pn697",
        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=ScimMatchingDefinition(
        strategy=OidcEmailUsernameToScimUsername
    ),
    scimConnection=FetchScimConnectionResponse(
        connectionId="scim_conn_123...",
        customerId="106ce124-108...",
        displayName="Example SCIM Connection",
        scimApiKeyValidUntil=1735689600,
        userMapping={...}
    )
)

FetchOidcClientResponse
{
    IdpInfoFromCustomer = IdpInfoFromCustomerResponseOkta
    {
        ClientId = "0oaulhbkt9YBiT3Pn697",
        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 = ScimMatchingDefinition
    {
        Strategy = "OidcEmailUsernameToScimUsername"
    },
    ScimConnection = FetchScimConnectionResponse
    {
        ConnectionId = "scim_conn_123...",
        CustomerId = "106ce124-108...",
        DisplayName = "Example SCIM Connection",
        ScimApiKeyValidUntil = 1735689600,
        UserMapping = {...}
    }
}

Patch OIDC Client

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

Arguments

oidcClientId string

The OIDC client ID to update (use either this or customerId, not both)

customerId string

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

idpInfoFromCustomer OptionalIdpInfoFromCustomer

Updated identity provider configuration. See the IdP Info docs for more information.

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.

displayName string

Updated display name for the OIDC client

redirectUrl string

Updated redirect URL for the OIDC client

additionalScopes string[]

Updated list of additional OAuth scopes to request

emailDomainAllowlist string[]

Updated list of allowed email domains

scimMatchingDefinition ScimMatchingDefinition

Updated SCIM matching strategy. Can equal OidcSubToScimUsername, OidcSubToScimExternalId, OidcEmailToScimUsername, OidcEmailUsernameToScimUsername, or OidcPreferredUsernameToScimUsername.

Successful Response

clientId string

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

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

const result = await auth.sso.management.patchOidcClient({
  customerId: "106ce124-108...",
  displayName: "Updated Okta OIDC Client",
  additionalScopes: ["groups"],
  emailDomainAllowlist: ["example.com", "company.com"],
  scimMatchingDefinition: {
    strategy: "OidcEmailToScimUsername"
  }
});

if (result.ok) {
  console.log("OIDC client updated successfully");
  console.log(`Client ID: ${result.data.clientId}`);
} else {
  console.log(`Error: ${result.error}`);
  // Check result.error.type to handle specific errors
}

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

result = await client.sso.management.patch_oidc_client(
    customer_id="106ce124-108...",
    display_name="Updated Okta OIDC Client",
    additional_scopes=["groups"],
    email_domain_allowlist=["example.com", "company.com"],
    scim_matching_definition=ScimMatchingDefinition(
        strategy="OidcEmailToScimUsername"
    )
)

if is_ok(result):
    print("OIDC client updated successfully")
    print(f"Client ID: {result.data.client_id}")
else:
    print(f"Error: {result.error}")

PropelAuthClient client = PropelAuthClient.create(url, integrationKey);

PatchOidcClientCommand command = PatchOidcClientCommand.customerId.builder()
    .customerId("106ce124-108...")
    .displayName("Updated Okta OIDC Client")
    .additionalScopes(Arrays.asList("groups"))
    .emailDomainAllowlist(Arrays.asList("example.com", "company.com"))
    .scimMatchingDefinition(ScimMatchingDefinition.builder()
        .strategy(ScimUserMatchingStrategy.OidcEmailToScimUsername)
        .build())
    .build();

try {
    PatchOidcClientResponse response = client.sso.management.patchOidcClient(command);
    System.out.println("OIDC client updated successfully");
    System.out.println("Client ID: " + response.getClientId());
} catch (PatchOidcClientException.OidcClientNotFound e) {
    System.out.println("OIDC client not found");
} catch (PatchOidcClientException.InvalidFields e) {
    System.out.println("Invalid fields: " + e.getDetails());
} catch (PatchOidcClientException e) {
    System.out.println("Error: " + e.getMessage());
}

var client = new PropelAuthClient(new PropelAuthOptions { Url = url, IntegrationKey = integrationKey });

try
{
    var response = await client.Sso.Management.PatchOidcClientByCustomerIdAsync(
        customerId: "106ce124-108...",
        displayName: "Updated Okta OIDC Client",
        additionalScopes: new List<string> { "groups" },
        emailDomainAllowlist: new List<string> { "example.com", "company.com" },
        scimMatchingDefinition: new ScimMatchingDefinition
        {
            Strategy = ScimUserMatchingStrategy.OidcEmailToScimUsername
        }
    );
    Console.WriteLine("OIDC client updated successfully");
    Console.WriteLine($"Client ID: {response.ClientId}");
}
catch (PatchOidcClientException.OidcClientNotFound)
{
    Console.WriteLine("OIDC client not found");
}
catch (PatchOidcClientException.InvalidFields ex)
{
    Console.WriteLine($"Invalid fields: {ex.Details}");
}
catch (PatchOidcClientException ex)
{
    Console.WriteLine($"Error: {ex.Message}");
}

Response

{
  ok: true,
  data: {
    clientId: "0oaulhbkt9YBiT3Pn697"
  }
}

PatchOidcClientResponse(
    client_id="0oaulhbkt9YBiT3Pn697"
)

PatchOidcClientResponse(
    clientId="0oaulhbkt9YBiT3Pn697"
)

PatchOidcClientResponse
{
    ClientId = "0oaulhbkt9YBiT3Pn697"
}

Delete OIDC Client

Permanently deletes an OIDC client.

Arguments

oidcClientId string

The OIDC client ID to delete (use either this or customerId, not both)

customerId string

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

OidcClientNotFound

No OIDC client found for the provided oidcClientId or customerId

UnexpectedError

An unexpected error occurred during the operation

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

const result = await auth.sso.management.deleteOidcClient({
  customerId: "106ce124-108..."
});

if (result.ok) {
  console.log("OIDC client deleted successfully");
} else {
  console.log(`Error: ${result.error}`);
  // Check result.error.type to handle specific errors
}

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

result = await client.sso.management.delete_oidc_client(
    customer_id="106ce124-108..."
)

if is_ok(result):
    print("OIDC client deleted successfully")
else:
    raise HTTPException(status_code=500, detail="Internal server error")

PropelAuthClient client = PropelAuthClient.create(url, integrationKey);

DeleteOidcClientCommand command = DeleteOidcClientCommand.customerId.builder()
    .customerId("106ce124-108...")
    .build();

try {
    DeleteOidcClientResponse response = client.sso.management.deleteOidcClient(command);
    System.out.println("OIDC client deleted successfully");
} catch (DeleteOidcClientException.OidcClientNotFound e) {
    System.out.println("OIDC client not found");
} catch (DeleteOidcClientException e) {
    System.out.println("Error: " + e.getMessage());
}

var client = new PropelAuthClient(new PropelAuthOptions { Url = url, IntegrationKey = integrationKey });

try
{
    await client.Sso.Management.DeleteOidcClientByCustomerIdAsync("106ce124-108...");
    Console.WriteLine("OIDC client deleted successfully");
}
catch (DeleteOidcClientException.OidcClientNotFound)
{
    Console.WriteLine("OIDC client not found");
}
catch (DeleteOidcClientException ex)
{
    Console.WriteLine($"Error: {ex.Message}");
}

Response

{
  ok: true,
  data: {}
}

Result(
    data=DeleteOidcClientResponse()
)

DeleteOidcClientResponse()

DeleteOidcClientResponse()

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 string[]

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. This prevents attackers from tricking users into logging in and then redirecting them to a malicious site.

{
    // When initiating an SSO login, you may specify a 'post_login_redirect_url'. Most commonly, this is used to
    // indicate where the user should be redirected after a successful login, and we return this URL back to you,
    // after the user has successfully authenticated.
    //
    // However, this can be a security risk if you allow arbitrary URLs to be specified here, as an attacker could
    // trick a user into logging in, and then redirect them to a malicious site.
    //
    // This configuration option allows you to specify a list of allowed origins (scheme + host + optional port)
    // that can be used in the 'post_login_redirect_url'. 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",
    ],
}