Skip to Content

SAML Single Sign-On

Checkbook offers Security Assertion Markup Language (SAML) Single Sign-On (SSO) integration, enabling organizations to provide their users with a seamless and secure way to access the Checkbook platform using their existing corporate credentials. This eliminates the need for users to manage separate Checkbook usernames and passwords, enhancing security and streamlining the login process.

SAML is an open standard for exchanging authentication and authorization data between parties, specifically between an Identity Provider and a Service Provider.

Identity Provider (IdP): This is the system that manages user identities within your organization (e.g., Auth0, Azure AD, Okta). It’s responsible for authenticating users.

Service Provider (SP): This is the application or service that users want to access (in this case, Checkbook). It relies on the IdP to authenticate users.

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

Configuration

To set up SAML SSO with Checkbook, you will need to exchange configuration information between your IdP and Checkbook.

IdP Configuration

Entity ID or Audience URI: http://app.checkbook.io/web/v1/auth/saml/metadata

SSO URL or ACS URL: http://app.checkbook.io/web/v1/auth/saml/?acs

Name ID: The NameID format is emailAddress, and should contain the user’s email address

Checkbook Configuration

You’ll need to provide Checkbook with some information as well:

Identity Provider ID: The unique identifier assigned to your organization’s IdP

Identity Provider Certificate: The X.509 digital certificate used by your organization’s IdP to sign assertions

Single Sign-On URL: The URL on your IdP that handles the user authentication process

Signing In

Checkbook’s SAML Single Sign-On (SSO) integration offers flexibility in how users can initiate the login process, including Service Provider (SP)-initiated SSO, Identity Provider (IdP)-initiated SSO, and Just-In-Time (JIT) provisioning.

Service Provider (SP)-Initiated SSO

  1. User Accesses Checkbook: The user attempts to log in using the Checkbook login page 

  2. Checkbook Initiates SSO: Checkbook (the SP) identifies that SSO is enabled and redirects the user’s browser to the Identity Provider (IdP) SSO URL. This redirection includes a SAML authentication request.

  3. User Authenticates with IdP: The user is presented with the IdP’s login page and enters their corporate credentials (username and password) or uses other authentication methods supported by the IdP (e.g., multi-factor authentication).

  4. IdP Sends SAML Assertion: Upon successful authentication, the IdP generates a SAML assertion containing user information (including the NameID) and sends it back to Checkbook’s Assertion Consumer Service (ACS) URL.

  5. Checkbook Grants Access: Checkbook validates the SAML assertion and, if successful, establishes a session, allowing the user to access the platform.

Identity Provider (IdP)-Initiated SSO

  1. User Accesses IdP Portal: The user logs in to their organization’s Identity Provider portal (e.g., Azure AD portal, Okta dashboard).

  2. User Selects Checkbook.io: The user selects the Checkbook application from a list of available applications within the IdP portal.

  3. IdP Sends SAML Assertion: The IdP generates a SAML assertion and sends it directly to Checkbook’s ACS URL.

  4. Checkbook Grants Access: Checkbook validates the SAML assertion and grants the user access to the platform.

Just-In-Time (JIT) Provisioning

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

  1. User Initiates SSO (SP- or IdP-initiated): The user begins the SSO login process through either the SP-initiated or IdP-initiated flow described above.

  2. IdP Sends SAML Assertion: The IdP sends the SAML assertion to Checkbook.

  3. Checkbook Checks for Existing Account: Checkbook receives the assertion and checks if a corresponding user account already exists based on the NameID.

  4. Account Creation (If Necessary): If no account exists, Checkbook automatically creates a new user account using the firstName and lastName attributes from the SAML assertion

  5. Checkbook Grants Access: Checkbook grants the user access to the platform.

Last updated on