Chalk supports Single Sign-On (SSO) and is compatible with any Identity Provider that supports SAML 2.0, such as:

​
Supported features

Chalk supports Identity Provider (IdP)-initiated login and Service Provider (SP)-initiated login. SP-initiated login uses the well-known email domains that your team submits.

Chalk also supports just-in-time provisioning, so users can access the dashboard even if an owner has not explicitly invited them. Users who log in through SSO with this provisioning have the Viewer role.

​
Air-gapped deployments

For air-gapped deployments, which include your own API server and dashboard installed with Helm, this page covers only part of the SAML setup. After completing this guide, refer to the Cloud Auth documentation to complete setup.

The examples on this page come from an example environment on the https://chalk.ai site. The values on your deployment’s Single Sign-On page differ from the examples. Use the values on your own page when you set up SAML applications.

​
Setup steps

Team owners configure SSO under Single Sign-On in the team settings. This page includes the details that your identity provider needs to set up a SAML application, the form to submit your SAML application’s certificate and other details to Chalk, and the section to register the well-known email domains that can access your SAML application.

​
Identity provider setup

The details that you need to set up a SAML application in your identity provider are in the SAML Setup Details section at the bottom of the page:

In your SAML application, configure the following:

  • The main assertion subject is the email.
  • Assertions are signed. Chalk requires signed assertions, but they do not need to be encrypted with the Chalk certificate.

For detailed steps for a specific identity provider, follow these guides:

​
Chalk setup

After you create a SAML application in your identity provider, submit its details to Chalk. In the SAML Configurations section, select Add configuration and enter the following details:

  • Name: A Chalk-internal name that you choose to reference this application. Your identity provider does not provide it.
  • Identity Provider Type: Okta, Azure AD, OneLogin, or Other.
  • Issuer
  • Login URL
  • Logout URL: Optional. This might be the same as the Login URL.
  • Certificate: The signing certificate from your identity provider.

To make a configuration the one that Chalk uses by default, select Use as the primary SSO configuration.

If your identity provider provides a metadata XML file, select Or upload metadata XML instead of entering the issuer, login URL, and certificate. The file contains all three.

After you submit the configuration, the SAML application is ready to use and you can test it from your identity provider. The configuration appears in the SAML Configurations list, where you can edit or delete it:

​
Sign in via SSO

Chalk supports sign in via SSO from the dashboard’s login page if your email domain is registered with Chalk. You can register email domains after you configure a SAML application for your team.

To register your domain with Chalk:

  1. Open your team’s Single Sign-On page.
  2. In the Email Domains section, select Add domain. Enter a domain that your team uses and select the SAML configurations that it redirects to. If you select multiple configurations, users choose which one to use from the login page.
  3. Follow the instructions in the Domain requires verification dialog to verify ownership.

​
Verify your email domain

Copy the Host and Value from the dialog into a new TXT record at your DNS provider. The host is chalk-domain-verification.<your-domain>. For example.com, use chalk-domain-verification.example.com. Providers that automatically append your domain, including Namecheap, use only chalk-domain-verification in the Host field.

Save the record, then select Refresh beside Add domain on the Single Sign-On page. Chalk checks pending domains and saves the approval when the TXT value matches. The check mark indicates approval; a clock indicates that verification is still pending. DNS caches can delay verification, so wait and refresh again if you recently added the record. When no approved provider exists, login lookups also check pending verification.

The dialog and the message box on the page both include copy buttons. Copy the value before leaving the page: Chalk stores only its hash, so you cannot retrieve it later. If you lose it, delete and register the domain again. Changing a domain issues a new challenge and requires verification again. For an existing pending domain registered before DNS verification was available, save it once to issue a challenge. Existing approved domains remain approved.

The login page has an email field and a Continue with your email button:

When you enter an email on a registered domain, the login page redirects you to your team’s SAML application. For a domain without SSO, Chalk emails you a 6-digit code to enter on the login page.