Skip to content
PropelAuth BYO Documentation

SSO Reference

Initiate OIDC Login

Section titled “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 to after successful login. 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
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"
  )
)
InitiateOidcLoginResponse(
  sendUserToIdpUrl="https://example.okta.com/oauth2/v1...",
  stateForCookie="NlTgYMWY2hiRmCV30kEPng"
)
InitiateOidcLoginResponse
{
    SendUserToIdpUrl = "https://example.okta.com/oauth2/v1...",
    StateForCookie = "NlTgYMWY2hiRmCV30kEPng"
}

Complete OIDC Login

Section titled “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 OIDC provider

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 successful login

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