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.
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.
