A SAML 2.0 authentication module lets you configure Hub as a SAML Service Provider (SAML SP). SAML supports single sign-on (SSO) across multiple domains.
When you enable an SAML 2.0 authentication module in Hub:
Your users log in to Hub with the credentials that are managed in a specified third-party identity provider (SAML IdP).
Your Hub users have fewer accounts and passwords to remember.
New users with accounts in the connected service can create their own accounts in Hub.
Hub can also be set up as a SAML IdP, however, the instructions for the identity provider setup are not described here. To learn how to use Hub as a SAML IdP, see SAML 2.0.
IdP-initiated SSO
The SAML 2.0 authentication module supports both service-provider (SP) and identity-provider (IdP) initiation for single-sign on (SSO). The login request is based on how the user signs in to Hub.
If the user signs in through an external login portal or access management provider (for example, OneLogin), the request is initiated by the IdP.
If the user signs in by clicking the button for the IdP in the Hub login page, the request is initiated by Hub as SP.
To support this behavior, the RelayState parameter for your SAML IdP must be empty. If you set a value for this parameter in the configuration for your IdP, the redirection to Hub results in a Can't restore state error.
Add a SAML2.0 Authentication Module
To add a SAML2.0 Authentication module:
In a service that you plan to use as a SAML identity provider for Hub, retrieve its parameters as the IdP.
If the IdP service does not provide a fingerprint of their certificate, create it applying SHA256. For example, you can use SAML Tool
In Hub, open the Administration > Auth Modules page.
Click the New module button, then select SAML 2.0 from the list.
In the dialog, specify the parameters for the IdP service, then click the Create button.
The SAML 2.0 authentication modules is created and enabled.
Configure the auth module by providing the names of the SAML attributes for user accounts in the Attributes section of the page.
General Settings
The first section of the page displays settings that identify the authentication module and let you manage the connection to the SAML service.
Setting
Description
Type
Displays the type of service that is enabled for authentication in Hub. Built-in Authorization means that this module is a part of Hub and is not installed separately.
Name
Stores the name of the authentication module. Use this setting to distinguish this module from other authentication modules in the Auth Modules list.
Button image
Displays the image used for the button that a user clicks to log in to Hub with a their account in the connected authorization service. You can upload a JPG, GIF or PNG file. The image is resized to 48 x 48 pixels automatically.
SAML SSO URL
The URL that Hub uses to redirect to the external identity provider. Hub only supports HTTP-redirect binding for sign-on.
IdP entity ID
The entity ID of the external identity provider.
Certificate fingerprint
The SHA-256 fingerprint of the identity provider SAML certificate. Use the SAML XML Metadata from your identity provider to generate the fingerprint.
SP entity ID
The URL that identifies Hub as a service provider.
SSL key
Selects an SSL key that can be used to verify the identity of your Hub installation to the authentication service. When used, all requests that are sent to the identity provider from Hub are signed using the corresponding SSL certificate.
This list displays only keystores that have been imported into Hub. For more information, see SSL Keys.
ACS URL
The assertion consumer service URL used by Hub as a service provider.
SP metadata
The URL that Hub uses to provide metadata to the external identity provider.
Contact user
The user who is responsible for the SAML 2.0 service provider configuration. The email address that is associated with this user account must be verified in Hub.
Attribute Mapping Settings
Settings in the Attributes section of the page let you map attributes for user accounts in the SAML service to fields that are stored in Hub accounts.
Option
Description
Login
The name of the SAML attribute that stores the login.
Email
The name of the SAML attribute that stores the email address.
Email verification state
Determines whether email addresses that are returned by the authentication service are stored as verified or unverified.
First name
The name of the SAML attribute that stores the first name of the user.
Last name
The name of the SAML attribute that stores the last name of the user.
Full name
The name of the SAML attribute that stores the full name of the user.
Additional Settings
The following options are located at the bottom of the page. Use these settings to manage Hub account creation and group membership, and to reduce the loss of processing resources consumed by idle connections.
Option
Description
User creation
Enables creation of Hub accounts for unregistered users who log in with an account that is stored in the connected authorization service. Hub uses the email address to determine whether the user has an existing account.
Auto-join groups
Adds users to a group when they log in with an account that is stored in the connected authorization service. You can select one or more groups. New users that auto-join a group inherit all of the permissions assigned to this group. We recommend that you add users to at least one group. Otherwise, a new user is only granted the permissions that are currently assigned to the All Users group.
Connection timeout
Sets the period of time to wait to establish a connection to the authorization service. The default setting is 5000 milliseconds (5 seconds).
Read timeout
Sets the period of time to wait to read and retrieve user profile data from the authorization service. The default setting is 5000 milliseconds (5 seconds).
Audit
Links to the Audit Events page in Hub. There, you can view a list of changes that were applied to this authentication module.
Sample Configurations
Use Okta as SAML Identity Provider in Hub
Configuring Okta as a SAML IdP in Hub is an easy but not a straight forward process. The trick is that to create an Auth module in Hub, you need to provide a unique URL for the IdP. However, in Okta, the IdP URL is specific for an application, and is generated when you create the application for the SAML SP. And to create an application for Hub as a SAML service provider in Okta, you need the unique URL that is generated in Hub only when you create the Auth module for Okta. This "URLs loop" results in the loop in the configuration procedure: You create an application in Okta with a fake URL for Hub to generate the IdP URL, then you create an auth module in Hub to generate the SP URL, and after that you can provide the actual SP URL from Hub in the Okta application.
When you created the application, click the View Setup Instructions button to open a page with the parameters of your Okta IdP:
Download the certificate of your Okta IdP.
Create a fingerprint for the Okta certificate applying SHA256. For example, you can use SAML Developer Tools.
In Hub, open Auth Modules page.
Click the New module button, then select SAML 2.0 in the drop-down list.
A New SAML 2.0 Auth Module dialog opens.
In the displayed dialog, specify the parameters of your Okta IdP, then click the Create button.
Configure the new module: Set up the SAML attributes.
Switch back to Okta. In Okta, edit the Hub application: Provide URLs that are generated during the creation of the new auth module.
Assign the Hub application to groups and users that should be able to log in to Hub with Okta credentials.
That's it. Now the users can log in to Hub and connected services with their Okta credentials.
Use Hub as SAML Identity Provider in Hub
If you have two Hub services, you can use one of them as a SAML Identity Provider and another one — as the service provider.
In the Hub installation that you use as the SAML IdP, open the Administration > SAML 2.0 page. For details about Hub as a SAML 2.0 Identity Provider, see SAML2.0 Identity Provider Parameters.
In Hub installation that you use as SAML service provider, open the Auth Modules page.
Click the New module button, then select SAML 2.0.
A New SAML 2.0 Auth Module dialog opens.
In the dialog, enter the parameters of the Hub service that you use as IdP:
Click the Create button.
The new module is created. You are navigated to the settings page the created module:
Configure SAML attributes:
In the IdP, open Admin menu > SAML 2.0 > Registered services tab. Register the Hub SAML service provider: As SAML Attributes, provide the same values that you have set up in the Attributes section of the auth module settings page. For more details, see Register a Service Provider.
You are all set! Now your users can log into the Hub SP with the credentials from the Hub service that you use as SAML IdP.
