Configuring Single Sign-On

Single Sign-On

HeadSpin supports several different single sign-on types that can be configured in addition to (or in place of) email login. For Single Sign-On protocols, an organization will have some trusted Identity Provider (IdP for short) that is responsible for authenticating users for different service providers (SP for short). The way that this is done depends on the underlying protocol. For Single Sign-on, HeadSpin operates as a service provider and currently supports SAML 2.0 and OAuth 2.0 (preferably via OpenID Connect). This page will guide you through configuring these different login types, as outlined in the following sections:

To configure the different Single Sign-on login configurations, login as an organization administrator and click the "Org Dashboard" icon in the top portion of the navigation bar to the left.

Then, click the "SSO" tab on the top of the screen.

This page shows the current settings for the different login types that are supported by HeadSpin.

OAuth 2.0 and OpenID Connect

HeadSpin supports authentication via OAuth 2.0, preferrably using OpenID Connect (OIDC), an authentication protocol built on top of OAuth 2.0. The result from this flow is a JWT (JSON Web Token) which contains the information necessary to authenticate. Note that it is possible in some cases to use OAuth 2.0 without OIDC to login, but this is strongly discouraged; use OpenID Connect if it is supported.

Configuring an OAuth 2.0 Provider

To configure HeadSpin to work with an OAuth 2.0 Provider, take note of the several endpoints supplied by HeadSpin (as the Service Provider) and the endpoints supplied by the OAuth 2.0 Provider (as the Identity Provider).

The OAuth 2.0 Provider should define the following two endpoints for authorizing and exchanging authorization tokens as follows:

1. Authorization Endpoint -- Endpoint to visit in order to login with the OAuth 2.0 Provider to obtain an access token.
2. Token Endpoint -- Endpoint that the Service Provider visits to exchange access tokens it has received in order test their validity and acquire results from the token.

As the service provider in this setting, HeadSpin defines two endpoints for redirecting and processing OAuth 2.0 tokens for your organization:

1. Redirect Endpoint -- Endpoint the OAuth 2.0 Provider redirects the user to after giving out a token.
2. Login Endpoint -- Endpoint the user visits to start the login process. Some OAuth 2.0 providers use this so they can redirect internally for an IdP-Initiated login.

These endpoints will be needed later when configuring OAuth 2.0 with the IdP, though HeadSpin might help with some of these in common cases.

Google

To enable your organization to allow login with Google, you will need to create the app there. Visit here to get to the dashboard. On the left side of the page, click the Credentials option. You should see something like the screen below:

Click the Create Credentials button and click OAuth Client ID from the dropdown that appears. On the next page that loads, set the Application Type to Web Application, then fill in the name of the app. For the Authorized Redirect URIs field, use the value from the Redirect Endpoint on your HeadSpin SSO Settings page.

Note that you can set the Authorized JavaScript origins with the same domain as the Redirect Endpoint if desired.

When finished, click the Create button and a popup will appear that contains the Client ID and the Client Secret that will need to be set in the HeadSpin SSO Settings page.

GitHub

To enable your organization to login to HeadSpin via GitHub, you will need to create an OAuth 2.0 app there.

Login to GitHub as an administrator for your organization, then navigate to your organization settings. You should end up at a page that looks like what is shown below:

Navigate down to the left sidebar and click the OAuth Apps menu.

Then, click New OAuth App to create the HeadSpin app. This loads a new page, prompting for the settings for this app. The Homepage URL is a required argument, so you can set this to: "https://ui-dev.headspin.io".

For the Authorization callback URL field, input the Redirect Endpoint value from the HeadSpin SSO Settings page.

With all of the fields typed in, click Register application.

The app will be generated and you should be redirected to a page with the Client ID and secret. These will be needed later when configuring HeadSpin.

OneLogin

For now, it is easier to use the SAML 2.0 integration for OneLogin. This is described below with the SAML 2.0 configurations.

Auth0

To enable login through Auth0, login to your Auth0 account, then select Applications from the left sidebar.

From this page, click the button Create Application. This will spawn a popup dialog that let's you name the app, as well as identify the type of application it is. For our purposes here, set the application type to be Regular Web Applications, then click Create.

From this page, skip the Quick Start introduction and just click the Settings tab near the top. This loads the page where the client ID and client secret can be obtained when configuring things in HeadSpin. This page also allows for inputting the different OAuth 2.0 endpoints needed.

For the Allowed Callback URLs field, make sure to input the Redirect Endpoint from the HeadSpin SSO page. For the Allowed Web Origins field, make sure that domain from Redirect Endpoint is set here. For example, if the Redirect Endpoint is https://api-dev.headspin.io/v0/oauth/00000000-0000-0000-0000-000000000000/auth, then the Allowed Web Origins field should include https://api-dev.headspin.io

Remember to take note of the Domain field here, in addition to the client ID and secret; this can be used later to autoconfigure the endpoints in the HeadSpin settings pages.

Okta

To enable login through Okta, login to your Okta account, then select the Applications tab on the top window.

From the applications page, click Add Application to add HeadSpin.

For now, just select Create New App from this page. This should spawn a popup that prompts for the different application information. Select Web for the Platform and select OpenID Connect for the Sign on Method, then click Create.

In the next page, type in the app name as "HeadSpin" (or whatever else you'd like). For the Login Redirect URIs, add the Redirect Endpoint from the HeadSpin SSO Settings page, then click Save. Your app has been created.

The client ID and client secret should be available on this page (if not, navigate to the General tab for the app), which will be necessary to finish configuring things in HeadSpin. Remember your Okta domain as well to make autoconfiguring the endpoints in HeadSpin easier.

Other

Other OAuth 2.0 Providers that support OpenID Connect can still be configured with HeadSpin. They will need to supply the proper Client ID and Client Secret. They will also need to allow a scope that includes openid (standard for OpenID Connect) and email, such as: openid email.

Most IdPs will also require that you register HeadSpin's Redirect Endpoint URL as a valid redirection as an extra security precaution. For different providers, this field can be called:

• Allowed Callback URLs
• Authorized Redirect URIs
• Redirect URLs
• Login Redirect URLs
• etc.

Make sure that the Redirect Endpoint URL in from HeadSpin is included in the above fields as appropriate for your IdP.

The Authorization Method to use when HeadSpin authenticates with the IdP may also need to be set. By default, HeadSpin will use the Basic authorization method, which includes the authorization fields as a header in the request. It can also be configured to use POST, which sends the login information inside a request body. Most providers expect these to be the same.

Configuring OAuth 2.0 (and OpenID Connect) in HeadSpin

When configuring HeadSpin, the IdP will need to provide the following values for HeadSpin:

• Client ID -- The client ID to identify HeadSpin to the OAuth 2.0 provider.
• Client Secret -- The secret associated with the given client ID.

To configure these in HeadSpin, click the Edit button for the OAuth 2.0 table:

Then, input the client ID and secret in the applicable boxes below:

In addition to the client ID and client secret, you can name this login as it will appear on the organization's login page.

Once the client information is , the OAuth 2.0 endpoints will need to be configured. HeadSpin provides a few Preconfigured Endpoints that can be clicked to automatically fill in these parameters. Simply click on the OAuth 2.0 Provider you are using to set the endpoints.

Note that some of the OAuth 2.0 providers will require your organization's domain in order to complete. In these cases, HeadSpin will spawn a popup dialog asking for your organization's domain for that provider. For example, if you are using OneLogin, they will assign you a domain and the resulting URL might look like: your-org.onelogin.com, as shown below:

Auth0 and Okta do something similar.

If your OAuth 2.0 provider is not listed as one of the Preconfigured Endpoints, or if you are using a customized setup, don't worry! You can also click Autoconfigure, if your OAuth 2.0 provider supplies an OAuth 2.0 Discovery (or OpenID Connect Discovery) URL. This will spawn a dialog to submit this URL:

If successful, the Authorization Endpoint and Token Endpoint (as well as any advanced settings) will be automatically configured.

Finally, you can still fill in each of these fields manually. Remember that clicking Advanced will show more settings, if necessary.

Once finished, click "Save" to return to the SSO Settings page.

OAuth 2.0 Flows without OpenID Connect

It is possible to authenticate into HeadSpin via OAuth 2.0 without using OpenID Connect, if the OAuth 2.0 Provider does not support processing a scope of openid email. However, this flow is discouraged and should only be used if there are no other viable alternatives. Note that the primary reason for this flow is to support login with GitHub, and so it may not work at all with other use-cases.

Unlike the OpenID Connect flow where a code the user sends to HeadSpin is exchanged for an ID token with a JWT, this flow will instead receive a generic OAuth 2.0 access token from the server, which must be used to authenticate subsequent calls to get the user's relevant profile information. In HeadSpin, this endpoint to query after receiving an access token is labelled as the Query Endpoint, and it will depend on the configured scope parameter and the OAuth 2.0 Provider's API. The response from this query endpoint should be a JSON response that contains the user's email after they have logged in.

SAML 2.0

SAML 2.0 is a authentication protocol often used for enterprise authentication. To enable logging into HeadSpin via SAML 2.0, there are several endpoints to keep in mind that will be needed later to configure the IdP to accept requests and send responses to HeadSpin for authentication. These are displayed in the Service Provider Settings portion of the SAML 2.0 Settings table:

• Audience (Metadata Endpoint) -- Identifies who the response is for.
• Assertion Consumer Service (ACS) -- SP Endpoint that sends/receives SAML login requests and responses.
• Single Logout Service (SLS) -- SP Endpoint that receives SAML logout requests.

Note that these different endpoints are unique to your organization. For brevity, the URLs on the HeadSpin settings page for these respective fields will be referenced by their shorthand, as outlined in the table below:

Note that not all SAML Service Providers use their Entity ID or Audience as the metadata endpoint, but HeadSpin does for simplicity.

Generic SAML 2.0 Configuration

To edit the SAML configuration in the HeadSpin settings page, click Edit on the SAML 2.0 Settings table, which should load the edit page shown below:

SAML Service Provider Autoconfiguration (HeadSpin)

Many SAML 2.0 IdPs provide metadata to autoconfigure the SP more easily. If your IdP has given a URL to acquire the metadata URL or has otherwise given an autoconfigure metadata XML, click Autoconfigure... which spawns a popup dialog.

Now, copy-paste the relevant field (either the URL or the metadata XML) then click Submit. If everything was successful, the different fields of the edit page should automatically be populated with the relevant fields. Click Save which will save the settings and redirect back to the main SSO Settings page.

NOTE: The URL must be accessible by HeadSpin to work; if this is too difficult due to firewall rules or other issues, you can download this link externally as an XML file, then paste the contents of that XML file instead. (If the raw XML fails, you may need to delete the <code class"dcode"><?xml version="1.0" encoding="UTF-8"?></code> line, just in case.)

Example: OneLogin Autoconfiguration XML

If configuring SAML with OneLogin, you can obtain the metadata link for the Onelogin endpoint by logging in as an appropriately privileged administrator into OneLogin. Once logged in, go to the dropdown menu labelled More Actions, then select SAML Metadata. Clicking this link will download the metadata as an XML file. Alternatively, you can right-click SAML Metadata and select Copy Link Location to get the URL to the metadata.

SAML Service Provider (HeadSpin) Settings

If autoconfiguration fails or is not desired, you can manually enter the relevant fields instead. Navigate again to the HeadSpin settings page, then click Edit on the SAML 2.0 Settings table, which should load the edit page shown below:

On the HeadSpin side of things, you will need to configure the following:

1. Identity Provider (IdP) Issuer -- The Entity ID for the IdP.
2. Saml 2.0 IdP Endpoint -- The endpoint to send SAML 2.0 requests. Sometimes referred to as the Single Sign-On Endpoint, SSO, or similar.
3. IdP Certificate -- The certificate that the IdP signs its responses with. This must be an x509 certificate in .pem format.

SAML Identity Provider Settings

The Audience (Metadata Endpoint) can actually be fetched directly to get an XML file with the Service Provider information HeadSpin uses to authenticate users via SAML; this URL can potentially be used if your custom IdP supports autoconfiguring from the SP.

If not, then note the following fields should generally correspond to the following fields in the IdP configuration:

1. The Audience or Entity ID field should be equal to the Audience setting in HeadSpin.
2. the Recipient field (if needed) should be equal to the ACS setting in HeadSpin.
3. The ACS field should be equal to the ACS setting in HeadSpin. Remember that some IdPs may call this Login URL/Endpoint or similar.
4. For now, do not bother with the SLS field (some IdPs call this Logout URL/Endpoint), since it isn't supported by HeadSpin.

Autoprovisioning for SAML

HeadSpin also supports autoprovisioning users using passed attributes from the IdP's login response. The different settings are described below:

Regardless of the type of autoprovisioning enabled, HeadSpin will attempt to parse some of the following attributes to determine a username to use in the system:

• <code class="dcode">UserName</code>
• <code class="dcode">DisplayName</code>
• <code class="dcode">FirstName</code>
• <code class="dcode">LastName</code>

(Note that the email is implied by the NameID.)

Whenever autoprovisioning (of either type) is disabled, then no new users are created and only existing users can be authenticated.

If Provision By Login Attribute is selected (and autoprovisioning is enabled), then HeadSpin will attempt to parse the following attribute from the SAML 2.0 Login Response to provision a user into the applicable roles:

• Attribute Name: <code class="dcode">https://headspin.io/SAML/Attributes/Role</code> with any combination of the following values (multiple values allowed):
• <code class="dcode">urn:headspin:iam:role_id:<role_id></code> with <code class="dcode"><role_id></code> replaced with the actual Role ID for the role.
• <code class="dcode">urn:headspin:iam:role_name:<team name>@<role name></code> with <code class="dcode"><team_name></code> replaced with the team name, and <code class="dcode"><role name></code> replaced with the role name (usually <code class"dcode">Admin</code> or <code class="dcode">Team Member</code>)

An example of this attribute in the SAML Response XML looks like:

<saml:Attribute Name="https://headspin.io/SAML/Attributes/Role"
    NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
  <saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema"
               xsi:type="xs:string">
    urn:headspin:iam:role_name:Default@Admin
  </saml:AttributeValue>
</saml:Attribute>

This will allocate the user into the <code class="dcode">Default</code> team with the <code class="dcode">Admin</code> role.

SAML Provision Into Team

If <code class="dcode">Prune Nonprovisioned Roles</code> is also checked, then this will also prune out any roles the user has inside this organization that are not listed in the SAML Response. With this option enabled, it is possible to remove a user's access to the system by logging them in with the appropriate attribute name passed, but no (or invalid) values.

If Provision into Team is selected (and autoprovisioning is enabled), then HeadSpin will attempt to create users and autoprovision them directly into the configured team if they do not exist.

Enabling and Testing Single Sign-On

Once you've configured Single Sign-On, you will now need to enable it in order to use it. In the Login Settings table at the top of the page, make sure that the desired login types are enabled. If the corresponding checkbox is checked, then that login type is enabled. Note that several different login types can be enabled at any given time.

Once enabled, you should also test logging in to make sure it works. Whenever an SSO login type is enabled, a "Test" button should appear. Click the corresponding button to spawn a popup dialog, which contains a link to visit. Note that you should load this link in a Private or Incognito window to make sure that your current login settings are not automatically used. An example with SAML 2.0 is shown below:

Load the link and follow through with the login process. At the end of a successful login, you should be logged into HeadSpin. If there was a configuration error, you will be redirected to an error page that describes the problem. Otherwise, contratulations, your SSO login should now be working!

Once you have different SSO logins working, you can safely disable Email login, if desired. Note that it might be helpful to keep Email login enabled for a little while longer so all users in your organization can transition to using the new login type more smoothly.