SSO Reference

Initiate OIDC Login

Kick off the login process for a user with an OIDC client.

Arguments

• oidcClientId string
  The OIDC client ID to use for login (use either this or customerId, not both)

• customerId string
  The customer ID to use for login (use either this or oidcClientId, not both)

• postLoginRedirectUrl string
  The URL to redirect the user to after they have successfully logged into your app. This is not the same as the redirect URL used when creating the OIDC client.
  This value will be returned in the response after successfully completing the OIDC login. It is up to you to handle the redirect yourself.
  Must be allowed by your post_login_redirect_origin_allowlist setting.

Successful Response

• sendUserToIdpUrl string
  The URL to redirect the user to for authentication with their OIDC provider

• stateForCookie string
  A state value that you should store as a cookie. We'll read this value in the Complete OIDC Login function to protect against CSRF attacks

Error Types

• ClientNotFound
  The provided oidcClientId or customerId does not match any configured OIDC client
• RedirectUrlInvalid
  The provided postLoginRedirectUrl is not allowed or invalid
• UnexpectedError
  An unexpected error occurred during the operation

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

const result = await auth.sso.initiateOidcLogin({
  oidcClientId: "0oaulhbkt9YBiT3Pn697",
  postLoginRedirectUrl: "https://app.example.com/authorization-code/callback"
});

if (result.ok) {
  console.log("OIDC login initiated successfully");
  res.redirect(result.data.sendUserToIdpUrl);
} else {
  console.log(`Error: ${result.error}`);
}

Complete OIDC Login

Finish the login process for a user with an OIDC client and get the user information.

Arguments

• callbackPathAndQueryParams string required
  The path and query parameters of the callback URL. Get this from the URL where the user was redirected back to after logging in through their OIDC provider.

• stateFromCookie string
  The state value from the Initiate OIDC Login response. This is specifically the one that we asked you to store in a cookie

Successful Response

• clientId string
  The unique identifier of the OIDC client

• customerId string
  The customer ID associated with this OIDC client

• oidcUserId string
  The unique identifier of the user from the OIDC provider

• email string
  The user's email address from the OIDC provider

• emailVerified boolean
  Whether the user's email address has been verified by the IdP.

• preferredUsername string
  The user's preferred username from the OIDC provider

• dataFromSso object
  Raw claims data from the OIDC provider

• scimUser object
  SCIM user information if SCIM is enabled for this customer.

• postLoginRedirectUrl string
  The URL to redirect the user to after they have successfully logged into your app.

Error Types

• InvalidLoginRequest
  The login request is invalid (e.g., missing or invalid CSRF state parameter)
• IdentityProviderError
  An error occurred with the identity provider (e.g., missing authorization code)
• LoginBlockedByEmailAllowlist
  The user's email is not allowed to log in
• ScimUserNotFoundWhereExpected
  SCIM is enabled but the user is not provisioned through SCIM
• ScimUserNotActive
  The SCIM user exists but is not active
• UnexpectedError
  An unexpected error occurred during the operation

const result = await auth.sso.completeOidcLogin({
  stateFromCookie: "s8lXVPo8VGvLxOveST3HqQ",
  callbackPathAndQueryParams: "/authorization-code/callback?code=1.AVEAOVh5sbKhzUa-5NiHtq5gP..."
});

if (result.ok) {
  const { email, oidcUserId, customerId } = result.data;
  if (result.data.postLoginRedirectUrl) {
    res.redirect(result.data.postLoginRedirectUrl);
  }
} else {
  console.log(`Error: ${result.error}`);
}