OIDC Single Sign-On

Checkbook supports OpenID Connect (OIDC) Single Sign-On (SSO), enabling organizations to provide their users with a seamless and secure way to access the Checkbook platform using their existing corporate credentials. OIDC is supported alongside SAML SSO and can be used as an alternative or in addition to SAML.

OIDC is an identity layer built on top of the OAuth 2.0 protocol. It is widely supported by modern identity providers and offers a simpler configuration process compared to SAML.

OpenID Provider (OP): This is the system that manages user identities within your organization (e.g., Okta, Azure AD, Google Workspace). It’s responsible for authenticating users and issuing ID tokens.

Relying Party (RP): This is the application that users want to access (in this case, Checkbook). It relies on the OpenID Provider to authenticate users.

SSO (Single Sign-On): This allows users to log in once with their OpenID Provider credentials and then access multiple applications (including Checkbook) without having to re-enter their credentials.

Configuration

To set up OIDC SSO with Checkbook, you will need to create an application in your OpenID Provider and exchange configuration information with Checkbook.

OpenID Provider Configuration

Create a new OIDC application in your OpenID Provider with the following settings:

Application Type: Web Application

Grant Type: Authorization Code

Redirect URI: https://app.checkbook.io/web/v1/auth/oidc/callback

Initiate Login URI: https://app.checkbook.io/web/v1/auth/lookup

Scopes: openid, email, profile

The ID token must include the following claims:

Claim	Required	Description
`email`	Yes	The user’s email address
`email_verified`	Recommended	Whether the email has been verified by the OpenID Provider
`given_name`	Yes	The user’s first name (used for account provisioning)
`family_name`	Yes	The user’s last name (used for account provisioning)

Checkbook Configuration

Provide the following to your Checkbook account representative:

Client ID: The client identifier assigned to the application by your OpenID Provider

Client Secret: The client secret assigned to the application by your OpenID Provider

Issuer URL: Your OpenID Provider’s issuer URL (e.g., https://acme.okta.com). This should serve a valid discovery document at {issuer}/.well-known/openid-configuration

Email Domain: The email domain to associate with this OIDC configuration (e.g., acme.com)

Security

Checkbook’s OIDC implementation includes the following security measures:

PKCE (S256): All authorization requests use Proof Key for Code Exchange to prevent authorization code interception attacks. No additional IdP configuration is required — most providers support PKCE by default.

Nonce Validation: A unique nonce is included in each authorization request and validated in the ID token to prevent token replay attacks.

Issuer and Audience Verification: The iss and aud claims in the ID token are verified against the stored configuration to ensure the token was issued by the expected OpenID Provider and intended for Checkbook.

Email Verification: If the OpenID Provider includes an email_verified claim set to false, authentication is rejected.

Signing In

Checkbook’s OIDC integration supports Relying Party (RP)-initiated SSO, Third-Party (IdP)-initiated SSO, and Just-In-Time (JIT) provisioning.

Relying Party (RP)-Initiated SSO

User Accesses Checkbook: The user attempts to log in using the Checkbook login page .
Checkbook Initiates SSO: Checkbook identifies that OIDC is enabled for the user’s email domain and redirects the user’s browser to the OpenID Provider’s authorization endpoint.
User Authenticates: The user is presented with the OpenID Provider’s login page and enters their corporate credentials or uses other authentication methods (e.g., multi-factor authentication).
OpenID Provider Redirects Back: Upon successful authentication, the OpenID Provider redirects the user back to Checkbook’s redirect URI with an authorization code.
Checkbook Exchanges Code: Checkbook exchanges the authorization code for an ID token and validates it.
Checkbook Grants Access: Checkbook establishes a session, allowing the user to access the platform.

Third-Party Initiated SSO

User Accesses OpenID Provider Portal: The user logs in to their organization’s OpenID Provider portal (e.g., Okta dashboard).
User Selects Checkbook: The user selects the Checkbook application from the portal. The OpenID Provider redirects to Checkbook’s initiate login URI with the iss parameter identifying the provider.
Checkbook Redirects to OpenID Provider: Checkbook identifies the provider and redirects the user to its authorization endpoint.
User Authenticates: The user authenticates with the OpenID Provider (this step may be skipped if the user already has an active session).
Checkbook Grants Access: Checkbook validates the ID token and grants the user access to the platform.

The initiate login URI supports the following query parameters:

Parameter	Required	Description
`iss`	Yes	The OpenID Provider’s issuer URL, used to identify the OIDC configuration
`login_hint`	No	The user’s email address, passed to the OpenID Provider to pre-fill the login form
`target_link_uri`	No	A relative path to redirect the user to after login (defaults to `/account/dashboard`)

Just-In-Time (JIT) Provisioning

JIT provisioning automates the creation of user accounts in Checkbook the first time a user logs in via OIDC SSO.

User Initiates SSO (RP or third-party initiated): The user begins the SSO login process through either flow described above.
Checkbook Validates ID Token: Checkbook receives and validates the ID token from the OpenID Provider.
Checkbook Checks for Existing Account: Checkbook checks if a corresponding user account already exists based on the email address in the ID token.
Account Creation (If Necessary): If no account exists and the user’s email domain matches the configured domain, Checkbook automatically creates a new user account using the given_name and family_name claims from the ID token.
Checkbook Grants Access: Checkbook grants the user access to the platform.