Authentication

Control Hub can authenticate users using the built-in Control Hub authentication method, a Security Assertion Markup Language (SAML) identity provider, or a Lightweight Directory Access Protocol (LDAP) provider.

Each authentication method requires that users have a Control Hub user account. To log in to Control Hub, users enter the user ID for their Control Hub account using the following format: 

<ID>@<organization ID>

If the organization uses Control Hub authentication, Control Hub requests the user's password, and then authenticates the user using their Control Hub credentials. The user is then successfully logged in to Control Hub or a Data Collector registered with the organization.

If the organization uses SAML authentication, Control Hub sends the authentication request to the SAML identity provider (IdP). If the user does not have an existing session, the SAML IdP authenticates the user using the credentials stored in the IdP. The IdP returns a SAML assertion back to Control Hub confirming that the user is authenticated. If the user does have an existing session, the IdP simply returns a SAML assertion back to Control Hub. When Control Hub receives a SAML assertion, it verifies that the authenticated user is a registered Control Hub user and then grants the user access to Control Hub or a Data Collector registered with the organization.

If a Control Hub installation uses LDAP authentication, Control Hub requests the user's LDAP password, and then sends the authentication request to the LDAP provider. If the LDAP provider authenticates the user account, the user is then successfully logged in to Control Hub or a Data Collector registered with the organization.

Control Hub Authentication

Control Hub authenticates user credentials using the username and password stored in Control Hub.

Control Hub authentication is the default authentication method. To use Control Hub authentication, simply create a Control Hub user account for each user that needs to access Control Hub.

SAML Authentication

If your company uses a SAML IdP, you can use the IdP to authenticate Control Hub users.

SAML authenticates a user using the credentials stored in the IdP. SAML uses single sign on authentication so that users can log in to Control Hub using the same credentials that they use for other web applications within your corporate network.

SAML provides single sign on for web applications. SAML single sign on transfers the user’s identity from one place (the identity provider or IdP) to another (the service provider or SP). Control Hub acts as the SAML service provider that works with the SAML IdP that you specify. The IdP can be in the cloud or on-premises. As the service provider, Control Hub does not directly access the IdP. Instead, all communication between Control Hub and the IdP is managed by the web browser.

When SAML authentication is enabled, users still require a Control Hub user account to log in to Control Hub. After users enter their user account name, Control Hub sends the authentication request to the SAML IdP.

Control Hub SAML integration supports SAML 2.0 and supports SAML sessions initiated by the service provider only. It does not support sessions initiated by the identity provider.

As a service provider, Control Hub sends SAML AuthnRequest messages to the IdP Single Sign On (SSO) endpoint using SAML HTTP-Redirect and HTTP-POST bindings. The Assertion Consumer Service (ACS) endpoint used by Control Hub supports SAML HTTP-POST binding.

Signed Messages and Assertions

Control Hub supports signed SAML messages and SAML assertions that are signed and encrypted. If the IdP is configured to use SAML message signing and SAML assertion signing and encryption, then Control Hub enforces them also.

SAML message signing is verified using the key information defined for the organization in Control Hub. Any key information that exists in the message is ignored.

By default, each Control Hub organization is configured to use SAML message signing and SAML assertion signing and encryption. If the IdP is not configured to use these, then you must disable message signing and assertion signing and encryption when you configure SAML authentication for your organization.

Tasks that Require Control Hub Credentials

When SAML authentication is enabled, the following tasks require that users be authenticated by Control Hub:

  • Update the SAML IdP configuration in the organization details if the SAML IdP is incorrectly configured in Control Hub.
  • Use the Data Collector command line interface.
  • Use the Control Hub REST API or the SDK for Python.
To complete these tasks when SAML is enabled, users must have one of the following roles:
  • Organization Administrator

    Users with the Organization Administrator role can complete all of these tasks.

  • Control Hub Authentication

    Users with the Control Hub Authentication role can complete all of the tasks except for updating the SAML IdP configuration, as long as they have all other required roles. For example, to delete jobs using the Control Hub REST API when SAML is enabled, a user must have the Control Hub Authentication role, Organization User role, and the Job Operator role.

Users with the Organization Administrator role or the Control Hub Authentication role can be authenticated by the SAML IdP using IdP credentials or by Control Hub using Control Hub credentials. In most cases, users with these roles will log in just like any other user in the organization and will be authenticated by the SAML IdP.

However, when needed, users with the Organization Administrator role or the Control Hub Authentication role can use the following page to log into Control Hub using Control Hub credentials:

https://<hostname>:18631/security/dpmlogin

For example, if the SAML IdP is incorrectly configured within Control Hub, users cannot log in using SAML authentication. Users with the Organization Administrator role can use their Control Hub credentials to log in using this URL to re-enable access to Control Hub.

Because users with the Organization Administrator role or the Control Hub Authentication role can be authenticated by Control Hub, users with these roles must define a password to use with their Control Hub user account. When a new user or an existing user is assigned one of these roles, Control Hub sends the user a password reset email.
Note: When needed, the Control Hub system administrator can configure an organization property to disable this SAML backdoor. However, disable the backdoor with caution. If disabled and the SAML IdP is incorrectly configured within Control Hub, you must work with StreamSets customer support to resolve the issue.

Enabling SAML Authentication

The process that you use to enable SAML authentication depends on the SAML IdP that you use. Refer to the IdP documentation for the detailed steps.

Complete the following general steps to enable SAML authentication:
  1. Register Control Hub as a service provider with the IdP of your choice.
  2. Within Control Hub, configure SAML authentication for your organization.
  3. Within Control Hub, map Control Hub user accounts to IdP user accounts.

Step 1. Register Control Hub as a Service Provider

To register Control Hub as a service provider with an IdP, download the Control Hub SAML metadata and keys, and then use that information to register Control Hub with the IdP.

  1. In the Control Hub Navigation panel, click Administration > Organizations.
  2. Hover over the organization name, and then click the Configuration icon: .
    The Organization Configuration window displays.
  3. Click the SAML IdP Metadata tab.
  4. Locate the Control Hub SAML Downloads section in the bottom of the window.

  5. Click the following links to download the Control Hub SAML metadata and keys:
    • Metadata
    • Signature Public Key
    • Encryption Public Key

    The information is saved to your default downloads directory. The metadata is saved as an XML file, while the keys are saved as PEM files.

  6. Log in to the IdP and use the required method for that provider to register Control Hub as a service provider.
    For the required steps, see the IdP documentation. If using Microsoft Entra ID (previously known as Azure Active Directory), OneLogin, Salesforce, or SSOCircle as the IdP, configure Control Hub as an application to register it as a service provider. If using Salesforce, be sure to grant the corresponding Salesforce users permission to access the Control Hub application in Salesforce.

    For some IdPs, you can simply upload the Control Hub SAML metadata and keys. For other providers, you must configure individual properties such as the service provider Entity ID or the Assertion Consumer Service URL. View the downloaded Control Hub SAML metadata file to find the values of these properties for Control Hub.

    For example, the service provider Entity ID for Control Hub is defined in the entityID attribute of the XML file as follows:
    <md:EntityDescriptor entityID="uri:https://cloud.streamsets.com/security" xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata">
  7. Within the IdP, download the IdP metadata XML file.
    For the required steps, see the IdP documentation.

    You'll use the IdP metadata XML file in our next step.

Step 2. Configure SAML Authentication for the Organization

To configure SAML authentication for the organization, upload the IdP metadata XML file to the organization and configure individual properties as required by the IdP. As a last step, enable SAML integration for the organization.

  1. In the Control Hub Navigation panel, click Administration > Organizations.
  2. Hover over the organization name, and then click the Configuration icon: .
    The Organization Configuration window displays.
  3. In the SAML IdP Metadata tab, upload the IdP metadata XML file that you downloaded from the IdP.

    Uploading the IdP metadata XML file configures most of the required properties that Control Hub needs to connect to the IdP. However, for some IdPs, you must configure individual properties in the SAML IdP Options tab.

  4. Click the SAML IdP Options tab and review the IdP documentation for the required properties.

    For example, if using one of the following IdPs, you might need to make the following configurations on the SAML IdP Options tab:
    IdP Required Configurations
    Microsoft Entra ID (previously known as Azure Active Directory)

    or

    Microsoft Active Directory Federation Services (AD FS)
    • Set the IdP AuthnContext Class property to:

      urn:oasis:names:tc:SAML:2.0:ac:classes:Password

    • Set the Assertion Element to Extract UserName From property to:

      http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress

    • Set the IdP AuthnContext Comparison property to:

      exact

    • Clear the Wants SAML Assertions Encrypted property.
    • Clear the Wants SAML Messages Signed property.
    Okta
    • Clear the Wants SAML Assertions Encrypted property.
    • Clear the Wants SAML Assertions Signed property.
    • Clear the Wants SAML Messages Signed property.
    OneLogin Clear the Wants SAML Assertions Signed property.
    SailPoint IdentityNow Clear the Wants SAML Assertions Encrypted property.
    Salesforce None
    SSOCircle
    • Clear the Wants SAML Assertions Encrypted property.
    • Clear the Wants SAML Messages Signed property.
    Note: When you use both tabs to configure the IdP, the properties configured on the options tab override any of the metadata uploaded to the metadata tab.
  5. Click Save.
  6. Click the organization name to display the organization details.
  7. Select the SAML Integration Enabled property.

    Tip: If you need to temporarily disable SAML authentication for the organization, you can simply clear this property.
  8. Click Save.

Step 3. Map Control Hub Users to Identity Provider Users

When you enable SAML authentication, users still require a Control Hub user account to log in to Control Hub. You must map each Control Hub user account to a SAML IdP user account.

Note: Control Hub user accounts require a password. However, when you enable SAML authentication, the Control Hub passwords are not used to authenticate the user. Instead, the SAML IdP authenticates the user.
  1. In the Navigation panel, click Administration > Users.
  2. Click the Add User icon to create a new user. Or, click the name of an existing user account to display the account details.
  3. In the SAML User Name property, enter the IdP user account to map to this Control Hub user account.
    Default is the email address associated with the user account:

  4. Click Save.
  5. Repeat for each user account.

Troubleshooting

Use the following tips for help with SAML authentication:

How do I review error messages to figure out why a user cannot log in using SAML authentication?
For security reasons, SAML messages include minimal information about login failures. As a result, to troubleshoot SAML login issues, you must review the logs or consoles of both the SAML identity provider (IdP) and Control Hub.
Control Hub reports SAML issues as failed logins in the Login Audit. The audit entries include the error code produced by the SAML IdP or Control Hub, and a reason for the failure.
To access the login audit entries, click Administration > Login Audit in the Navigation panel. Select one of the failed logins to view the details about the failure.
After we enabled SAML authentication for our organization, all users who try to log into Control Hub receive a 500 internal server error - even our organization administrator.
If the IdP is incorrectly configured within Control Hub, users will not be able to log in using SAML authentication. However, users with the Organization Administrator role can use their Control Hub credentials to log into the following page to re-enable access to Control Hub:
https://<hostname>:18631/security/dpmlogin

In the login page, enter your user ID and password for your Control Hub account.

After logging in, review and correct the IdP configurations made for the organization.

LDAP Authentication

If you have a Control Hub on-premises installation and your company uses Lightweight Directory Access Protocol (LDAP), you can use the LDAP provider to authenticate Control Hub users. LDAP authenticates a user using the credentials stored in the LDAP server.

LDAP authentication is configured by the default system administrator - the admin@admin user account - for the entire Control Hub installation. To use LDAP authentication, the Control Hub system administrator configures LDAP connection information for Control Hub and then maps organization administrator accounts to LDAP users.

Organization administrators then create Control Hub user accounts and groups and map these to LDAP users and groups.

When LDAP authentication is enabled, users still require a Control Hub user account to log in to Control Hub or a registered Data Collector. After users enter their Control Hub user account name and LDAP password, Control Hub sends the authentication request to the LDAP provider.

Mapping Control Hub Users to LDAP Users

Map each Control Hub user account to an LDAP user account. Users log in to Control Hub using their Control Hub user ID and their LDAP password.

  1. As the organization administrator, click Administration > Users in the Navigation panel.
  2. Click the Add User icon to create a new user. Or, click the name of an existing user account to display the account details.
  3. In the LDAP User Name property, enter the LDAP user account to map to this Control Hub user account.
    Tip: To more efficiently manage user accounts, clear all roles for the user, assign the user to one of the Organization roles, and then assign the appropriate roles to the Control Hub group mapped to the LDAP group that the user belongs to.
  4. Click Save.
  5. Repeat for each user account.

Mapping Control Hub Groups to LDAP Groups

To group users when LDAP authentication is enabled, create Control Hub groups, and then map the Control Hub groups to LDAP groups.

When LDAP authentication is enabled, you cannot assign Control Hub users to Control Hub groups. Control Hub retrieves the group memberships from the LDAP provider.

  1. As the organization administrator, click Administration > Groups in the Navigation panel.
  2. Click the Add Group icon to create a new group. Or, click the name of an existing group to display the details.
  3. In the LDAP Groups property, enter the names of the LDAP groups to map to this Control Hub group.

    LDAP group names are case sensitive.

    Tip: To more efficiently manage user accounts, assign roles to Control Hub groups rather than to individual user accounts.
  4. Click Save.
  5. Repeat for each group.

    When you view the details of Control Hub user accounts mapped to LDAP users, the details display any Control Hub groups mapped to LDAP groups that the LDAP user account belongs to.

    For example, let's say that you mapped the Control Hub user account rita@MyCompany to the LDAP user rita. You mapped the Control Hub group sales@MyCompany to the LDAP group sales. The LDAP user rita belongs to the LDAP group sales. So when you view the details of the Control Hub user account rita@MyCompany, the user belongs to the following two groups:
    • all@MyCompany - default Control Hub group that includes every user in the organization.
    • sales@MyCompany - Control Hub group mapped to the LDAP group that rita belongs to.