SSO Reference

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");
  // Redirect user to result.data.sendUserToIdpUrl
  // Store result.data.stateForCookie in a cookie
  res.redirect(result.data.sendUserToIdpUrl);
} 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.initiate_oidc_login(
    oidc_client_id="0oaulhbkt9YBiT3Pn697",
    post_login_redirect_url="https://app.example.com/authorization-code/callback"
)

if is_ok(result):
    print("OIDC login initiated successfully")
    # Redirect user to result.data.send_user_to_idp_url
    # Store result.data.state_for_cookie in a cookie
    return RedirectResponse(url=result.data.send_user_to_idp_url)
else:
    print(f"Error: {result.error}")
    # Check result.error.type to handle specific errors

client, err := byo.NewClient(url, integrationKey)
if err != nil {
    log.Fatal(err)
}

result, err := client.Sso.InitiateOIDCLogin(ctx, &byo.InitiateOidcLoginCommandOIDCClientID{
    OIDCClientID:         "0oaulhbkt9YBiT3Pn697",
    PostLoginRedirectURL: byo.String("https://app.example.com/authorization-code/callback"),
})
if err != nil {
    log.Fatal(err)
}

// Store result.StateForCookie in a cookie, then
// redirect the user to result.SendUserToIdpURL
http.Redirect(w, r, result.SendUserToIdpURL, http.StatusFound)

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

InitiateOidcLoginCommand command = InitiateOidcLoginCommand.oidcClientId.builder()
    .oidcClientId("0oaulhbkt9YBiT3Pn697")
    .postLoginRedirectUrl("https://app.example.com/authorization-code/callback")
    .build();

try {
    InitiateOidcLoginResponse response = client.sso.initiateOidcLogin(command);
    System.out.println("OIDC login initiated successfully");
    // Redirect user to response.getSendUserToIdpUrl()
    // Store response.getStateForCookie() in a cookie
} catch (InitiateOidcLoginException.ClientNotFound e) {
    System.out.println("Error: Client not found");
} catch (InitiateOidcLoginException.RedirectUrlInvalid e) {
    System.out.println("Error: Redirect URL invalid");
} catch (InitiateOidcLoginException e) {
    System.out.println("Error: " + e.getMessage());
}

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

// You can also use InitiateOidcLoginByCustomerIdAsync(customerId, postLoginRedirectUrl)
try
{
    var response = await client.Sso.InitiateOidcLoginByOidcClientIdAsync(
        oidcClientId: "0oaulhbkt9YBiT3Pn697",
        postLoginRedirectUrl: "https://app.example.com/authorization-code/callback"
    );

    Console.WriteLine("OIDC login initiated successfully");
    // Redirect user to response.SendUserToIdpUrl
    // Store response.StateForCookie in a cookie
}
catch (InitiateOidcLoginException.ClientNotFound)
{
    Console.WriteLine("Error: Client not found");
}
catch (InitiateOidcLoginException.RedirectUrlInvalid ex)
{
    Console.WriteLine($"Error: Redirect URL invalid - {ex.Details.Message}");
}
catch (InitiateOidcLoginException ex)
{
    Console.WriteLine($"Error: {ex.Message}");
}

Response

{
  ok: true,
  data: {
    sendUserToIdpUrl: "https://example.okta.com/oauth2/v1...",
    stateForCookie: "NlTgYMWY2hiRmCV30kEPng"
  }
}

Result(
  data=InitiateOidcLoginResponse(
    send_user_to_idp_url="https://example.okta.com/oauth2/v1...",
    state_for_cookie="NlTgYMWY2hiRmCV30kEPng"
  )
)

byo.InitiateOidcLoginResponse{
    SendUserToIdpURL: "https://example.okta.com/oauth2/v1...",
    StateForCookie:   "NlTgYMWY2hiRmCV30kEPng",
}

InitiateOidcLoginResponse(
  sendUserToIdpUrl="https://example.okta.com/oauth2/v1...",
  stateForCookie="NlTgYMWY2hiRmCV30kEPng"
)

InitiateOidcLoginResponse
{
    SendUserToIdpUrl = "https://example.okta.com/oauth2/v1...",
    StateForCookie = "NlTgYMWY2hiRmCV30kEPng"
}

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. This is representative of whether the IdP thinks the email is verified, but not all IdPs are made equal when it comes to verifying. We recommend also using the domain allowlist as a precaution

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. Will be undefined if SCIM is not enabled

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 is set when initiating the OIDC login. It is up to you to handle the redirect yourself.

Must be allowed by your post_login_redirect_origin_allowlist setting.

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 auth = createClient({ url, integrationKey });

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

if (result.ok) {
  console.log("OIDC login completed successfully");
  // Access user information from result.data
  const { email, oidcUserId, customerId } = result.data;
  // Redirect to postLoginRedirectUrl if provided
  if (result.data.postLoginRedirectUrl) {
    res.redirect(result.data.postLoginRedirectUrl);
  }
} 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.complete_oidc_login(
    callback_path_and_query_params="/authorization-code/callback?code=1.AVEAOVh5sbKhzUa-5NiHtq5gP...",
    state_from_cookie="s8lXVPo8VGvLxOveST3HqQ"
)

if is_ok(result):
    print("OIDC login completed successfully")
    # Access user information from result.data
    email = result.data.email
    oidc_user_id = result.data.oidc_user_id
    customer_id = result.data.customer_id
    # Redirect to post_login_redirect_url if provided
    if result.data.post_login_redirect_url:
        return RedirectResponse(url=result.data.post_login_redirect_url)
else:
    print(f"Error: {result.error}")
    # Check result.error.type to handle specific errors

client, err := byo.NewClient(url, integrationKey)
if err != nil {
    log.Fatal(err)
}

result, err := client.Sso.CompleteOIDCLogin(ctx, byo.CompleteOidcLoginCommand{
    StateFromCookie:            byo.String("s8lXVPo8VGvLxOveST3HqQ"),
    CallbackPathAndQueryParams: "/authorization-code/callback?code=1.AVEAOVh5sbKhzUa-5NiHtq5gP...",
})
if err != nil {
    log.Fatal(err)
}

// Access user information from the result
fmt.Println(result.OIDCUserID)

// Redirect to postLoginRedirectUrl if provided
if result.PostLoginRedirectURL != nil {
    http.Redirect(w, r, *result.PostLoginRedirectURL, http.StatusFound)
}

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

CompleteOidcLoginCommand command = CompleteOidcLoginCommand.builder()
    .stateFromCookie("s8lXVPo8VGvLxOveST3HqQ")
    .callbackPathAndQueryParams("/authorization-code/callback?code=1.AVEAOVh5sbKhzUa-5NiHtq5gP...")
    .build();

try {
    CompleteOidcLoginResponse response = client.sso.completeOidcLogin(command);
    System.out.println("OIDC login completed successfully");
    // Access user information from response
    String email = response.getEmail();
    String oidcUserId = response.getOidcUserId();
    String customerId = response.getCustomerId();
    // Redirect to postLoginRedirectUrl if provided
    if (response.getPostLoginRedirectUrl() != null) {
        return ResponseEntity
            .status(HttpStatus.FOUND)
            .location(URI.create(response.getPostLoginRedirectUrl()))
            .build();
    }
} catch (CompleteOidcLoginException.InvalidLoginRequest e) {
    System.out.println("Invalid login request");
} catch (CompleteOidcLoginException.IdentityProviderError e) {
    System.out.println("Identity provider error");
} catch (CompleteOidcLoginException.LoginBlockedByEmailAllowlist e) {
    System.out.println("Login blocked by email allowlist");
} catch (CompleteOidcLoginException.ScimUserNotFoundWhereExpected e) {
    System.out.println("SCIM user not found where expected");
} catch (CompleteOidcLoginException.ScimUserNotActive e) {
    System.out.println("SCIM user not active");
} catch (CompleteOidcLoginException e) {
    System.out.println("Error: " + e.getMessage());
}

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

var command = new CompleteOidcLoginCommand
{
    StateFromCookie = "s8lXVPo8VGvLxOveST3HqQ",
    CallbackPathAndQueryParams = "/authorization-code/callback?code=1.AVEAOVh5sbKhzUa-5NiHtq5gP..."
};

try
{
    var response = await client.Sso.CompleteOidcLoginAsync(command);
    Console.WriteLine("OIDC login completed successfully");
    // Access user information from response
    var email = response.Email;
    var oidcUserId = response.OidcUserId;
    var customerId = response.CustomerId;
    // Redirect to PostLoginRedirectUrl if provided
    if (response.PostLoginRedirectUrl != null)
    {
        return Redirect(response.PostLoginRedirectUrl);
    }
}
catch (CompleteOidcLoginException.InvalidLoginRequest ex)
{
    Console.WriteLine($"Invalid login request: {ex.Details}");
}
catch (CompleteOidcLoginException.IdentityProviderError ex)
{
    Console.WriteLine($"Identity provider error: {ex.Details}");
}
catch (CompleteOidcLoginException.LoginBlockedByEmailAllowlist)
{
    Console.WriteLine("Login blocked by email allowlist");
}
catch (CompleteOidcLoginException.ScimUserNotFoundWhereExpected)
{
    Console.WriteLine("SCIM user not found where expected");
}
catch (CompleteOidcLoginException.ScimUserNotActive)
{
    Console.WriteLine("SCIM user not active");
}
catch (CompleteOidcLoginException ex)
{
    Console.WriteLine($"Error: {ex.Message}");
}

Response

{
  ok: true,
  data: {
    clientId: "11307bcd-8e4...",
    customerId: "106ce124-108...",
    oidcUserId: "c06f55c1-d8...",
    email: "example@propelauth.com",
    emailVerified: false,
    preferredUsername: "example@propelauth.com",
    dataFromSso: {
      sub: "c06f55c1-d8...",
      name: "Example User",
      email: "example@propelauth.com"
    },
    scimUser: {
      connectionId: "JsuI1wj...",
      scimUser: {
        meta: {
          createdAt: "2025-08-26T15:41:17.177028Z",
          lastModifiedAt: "2025-08-26T15:41:17.177028Z",
          resourceType: "User"
        },
        name: {
          formatted: "Example User",
          givenName: "Example",
          familyName: "User"
        },
        ...
      }
    },
    postLoginRedirectUrl: "https://app.example.com/authorization-code/callback"
  }
}

Result(
    data=CompleteOidcLoginResponse(
        client_id="11307bcd-8e4...",
        customer_id="106ce124-108...",
        oidc_user_id="c06f55c1-d8...",
        email="example@propelauth.com",
        email_verified=False,
        preferred_username="example@propelauth.com",
        data_from_sso={
            "sub": "c06f55c1-d8...",
            "name": "Example User",
            "email": "example@propelauth.com"
        },
        scim_user=CompleteScimUserResponse(
            connection_id="JsuI1wj...",
            scim_user={
                "meta": {
                    "createdAt": "2025-08-26T15:41:17.177028Z",
                    "lastModifiedAt": "2025-08-26T15:41:17.177028Z",
                    "resourceType": "User"
                },
                "name": {
                    "formatted": "Example User",
                    "givenName": "Example",
                    "familyName": "User"
                },
                ...
            },
            parsed_user_data={...},
            active=True
        ),
        post_login_redirect_url="https://app.example.com/authorization-code/callback"
    )
)

byo.CompleteOidcLoginResponse{
    ClientID:             "11307bcd-8e4...",
    CustomerID:           "106ce124-108...",
    OIDCUserID:           "c06f55c1-d8...",
    Email:                byo.String("example@propelauth.com"),
    EmailVerified:        false,
    PreferredUsername:    byo.String("example@propelauth.com"),
    DataFromSso:          json.RawMessage(`{"sub": "c06f55c1-d8...", "name": "Example User", "email": "example@propelauth.com"}`),
    PostLoginRedirectURL: byo.String("https://app.example.com/authorization-code/callback"),
}

CompleteOidcLoginResponse(
    clientId="11307bcd-8e4...",
    customerId="106ce124-108...",
    oidcUserId="c06f55c1-d8...",
    email="example@propelauth.com",
    emailVerified=false,
    preferredUsername="example@propelauth.com",
    dataFromSso={
        sub="c06f55c1-d8...",
        name="Example User",
        email="example@propelauth.com"
    },
    scimUser=CompleteScimUserResponse(
        connectionId="JsuI1wj...",
        scimUser={
            meta={
                createdAt="2025-08-26T15:41:17.177028Z",
                lastModifiedAt="2025-08-26T15:41:17.177028Z",
                resourceType="User"
            },
            name={
                formatted="Example User",
                givenName="Example",
                familyName="User"
            },
            ...
        },
        parsedUserData={...},
        active=true
    ),
    postLoginRedirectUrl="https://app.example.com/authorization-code/callback"
)

CompleteOidcLoginResponse
{
    ClientId = "11307bcd-8e4...",
    CustomerId = "106ce124-108...",
    OidcUserId = "c06f55c1-d8...",
    Email = "example@propelauth.com",
    EmailVerified = false,
    PreferredUsername = "example@propelauth.com",
    DataFromSso = {
        "sub": "c06f55c1-d8...",
        "name": "Example User",
        "email": "example@propelauth.com"
    },
    ScimUser = CompleteScimUserResponse
    {
        ConnectionId = "JsuI1wj...",
        ScimUser = {
            "meta": {
                "createdAt": "2025-08-26T15:41:17.177028Z",
                "lastModifiedAt": "2025-08-26T15:41:17.177028Z",
                "resourceType": "User"
            },
            "name": {
                "formatted": "Example User",
                "givenName": "Example",
                "familyName": "User"
            },
            ...
        },
        ParsedUserData = {...},
        Active = true
    },
    PostLoginRedirectUrl = "https://app.example.com/authorization-code/callback"
}