Hashboard supports using an Identity Provider (IdP) such as Okta to control authentication through single sign-on (SSO). It also supports provisioning and deprovisioning Hashboard users along with managing their custom Hashboard role assignments through SCIM (directory sync). This document describes how to integrate Hashboard into your IdP.
Contact Us- To initiate setup, contact us at firstname.lastname@example.org. We'll provide specific instructions and a test environment for setting up Hashboard with the IdP of your choice.
Hashboard supports the SAML protocol for single sign-on authentication. Once you reach out to us to initiate setup, we'll provide you with a link that will walk you through the necessary steps to perform in your IdP.
Upon completing this integration, users will no longer be able to log in with their previous Hashboard authentication method (username & password or Google). If they attempt to do so, they'll be redirected to a page that requires them to sign in through SSO. This page asks them to input their email and uses its domain to redirect to your IdP for sign-in.
Users will also of course be able to log in directly from your IdP by clicking on the Hashboard application integration that you set up.
Email constraints- It is required that the primary email of each user assigned to Hashboard in your IdP matches their Hashboard user's email. If this isn't the case, they won't be able to log in to their Hashboard account.
To reap the full power of managing users in your IdP, you can enable SCIM in addition to single sign-on. This will allow you to create and delete Hashboard users directly within your IdP. It will also enable updating your Hashboard users' personal information (including their email) and Hashboard roles.
Like SAML setup, we'll provide you with a link that will walk you through the necessary steps to perform in your IdP.
In addition to the standard
last_name attributes that we should receive automatically from your IdP on each
SCIM event for a user, Hashboard requires the following attribute to be provided as well:
roles custom attribute must map to a comma-separated list of Hashboard role names (either built-in or custom) to assign to the given user.
If a role is specified that doesn't exist in all of your Hashboard projects, SCIM will fail for that user.
Depending on your IdP, you might not be notified when this fails. We recommend working directly with Hashboard when setting up SCIM to ensure correct configuration.
Additional notes on
roles- 1. It must be non-empty. SCIM-enabled
projects do not have a concept of default roles, as all role assignments must
be explicitly managed through your IdP. 2. We treat these role names as
case-insensitive, so feel free to capitalize as you wish.
When you first initiate SCIM with Hashboard from your IdP, we'll use an IdP user's primary email to determine if there is an existing Hashboard user that should be overwritten by the IdP user's information. If we one, that Hashboard user will now be permanently tied to that IdP user and all updates (including those to primary email) will be reflected in Hashboard going forward. If we find no existing user with the given primary email on SCIM initiation, that IdP user will be provisioned a new Hashboard user.
When you assign users to Hashboard in your IdP, Hashboard will automatically be notified of these changes in real time through SCIM and will create or update the relevant Hashboard user appropriately. You don't need to perform any actions in Hashboard unless you're attempting to create a new role and assign users to it (see below). In fact, creating, editing, and deleting users in Hashboard is restricted for SSO-enabled projects.
Creating new Hashboard roles and editing existing roles must still be done in your Hashboard project. Hashboard
Owners can do this by default. However, if SSO is enabled for your
project, they won't be able to assign users to these roles in Hashboard. This must be done in your IdP by modifying the
roles custom attribute defined for those users.