Managing SAML Authentication

Applies to: IBM StreamSets as a Service

After enabling SAML authentication, you can complete the following tasks to manage the draft configuration:
You can complete the following tasks to manage the production configuration:

After you enable SCIM provisioning, you use the IdP to manage provisioned users and groups.

Testing the Draft Configuration

When SP-initiated logins are enabled, you can test that the draft SAML configuration is set up correctly with your identity provider (IdP). Test the draft configuration after modifying the configuration and before publishing it to production.

Note: Testing the draft SAML configuration is not supported when SP-initiated logins are disabled. Instead, you must publish your SAML draft configuration and then use your IdP to test the configuration or to test a login to IBM StreamSets.
  1. In the Control Hub Navigation panel, click Manage > My Organization.
  2. Click Configure SAML.
  3. Click the Draft tab.
  4. Modify the draft configuration as needed.
  5. In the Organization SAML Settings section, click Test.

    The SAML debug console displays, indicating whether IBM StreamSets is able to successfully send a request to your identity provider and receive a response. In case of a failure, use the listed errors to help you troubleshoot issues.

Resetting the Draft Configuration

To discard your edits to the draft configuration, you can reset the draft to override changes in the draft configuration with the published production configuration.

Note: You can reset the draft configuration only when you have a published production configuration.
  1. In the Control Hub Navigation panel, click Manage > My Organization.
  2. Click Configure SAML.
  3. Click the Draft tab.
  4. In the Organization SAML Settings section, click Reset Draft.
  5. Click Confirm.

    Control Hub overrides changes in the draft configuration with the published production configuration.

Publishing the Draft Configuration

After completing the draft configuration, you publish it to production.

The production configuration is read-only. To edit the SAML settings, you must edit the draft configuration and then publish that modified draft.

  1. In the Control Hub Navigation panel, click Manage > My Organization.
  2. Click Configure SAML.
  3. Click the Draft tab.
  4. In the Organization SAML Settings section, click Publish.
  5. Click Confirm.

    Control Hub publishes the configuration, displaying the Production tab in your organization SAML settings.

    If your organization has an enabled production configuration, Control Hub automatically enables the newly published configuration.

    If your organization has a disabled production configuration, the newly published configuration is also disabled. You must enable the production configuration to activate it.

Rotating the Service Provider Certificate

IBM StreamSets generates a unique service provider certificate for your organization. Each service provider certificate has an expiration date. You can create a new certificate and then rotate the certificate in your identity provider (IdP) when the expiration date approaches.

Note: As a best practice, upload the certificate to your IdP. For more information, see Service Provider Certificates.

You can find the expiration date for your certificate in the List of SAML Certificates section, as follows:

Certificate expiration date in list of SAML certificates

Note: If you create multiple certificates and then download the IBM StreamSets SAML metadata XML file when the Require Encryption on Assertion property is enabled, the metadata file automatically includes all certificates. When you upload the file to your IdP, the IdP uses the most recent certificate included in the file.
  1. In the Control Hub Navigation panel, click Manage > My Organization.
  2. Click Configure SAML.
  3. Click the Draft tab.
  4. In the List of SAML Certificates section, click Add Another.

    The New Certificate dialog box appears.

  5. Optionally, modify the default expiration date and key length for the certificate.
  6. Click Save.
  7. In the Actions column for the newly added certificate, click the Download icon: Download icon.

    The certificate is saved to your default downloads directory.

  8. Log in to your IdP and upload the new service provider certificate.

    The steps to upload the certificate depend on the IdP that you use. See your IdP documentation for instructions.

  9. In your Control Hub organization SAML settings, test that the new certificate works successfully.
    1. On the Draft tab, verify that the SP Initiated Login property is enabled.

      If the property is disabled, enable it temporarily so that you can test the draft SAML configuration.

    2. Click Test.

      The SAML debug console displays, indicating whether IBM StreamSets is able to successfully send a request to your identity provider and receive a response. In case of a failure, use the listed errors to help you troubleshoot issues.

    3. If you temporarily enabled SP-initiated logins for the test, disable the SP Initiated Login property.

    After a successful test, you can delete the outdated certificate.

  10. In the List of SAML Certificates section, click the Delete icon (Delete icon) in the Actions column for the outdated certificate.

Enabling the Production Configuration

After you publish a draft configuration to production, you enable the production configuration to activate it. When enabled, all organization users must log in using SAML authentication.

  1. In the Control Hub Navigation panel, click Manage > My Organization.
  2. Click Configure SAML.
  3. In the Production tab, click Enable.
  4. Click Confirm.

    You are logged out of IBM StreamSets. To log in again, use SAML authentication. Or as a user with the Organization Administrator role, you can log in using local or public identity provider authentication to access the Control Hub organization SAML configuration page only.

Disabling the Production Configuration

You can disable the production configuration to disable SAML authentication for your organization. When disabled, all organization users must log in using local or public identity provider authentication.

  1. In the Control Hub Navigation panel, click Manage > My Organization.
  2. Click Configure SAML.
  3. In the Production tab, click Disable.
  4. Click Confirm.

    You are logged out of IBM StreamSets. To log in again, use local or public identity provider authentication.

Logging In when SAML is Incorrectly Configured

If SAML authentication is enabled but the IdP or the SAML configuration in Control Hub is incorrectly configured, no organization users can log in to IBM StreamSets using SAML authentication. In this case, a user with the Organization Administrator role can log in using local or public identity provider authentication to access the Control Hub organization SAML configuration page only.

  1. Enter the following URL in the address bar of your browser:
    https://cloud.login.streamsets.com
  2. Log in as a user with the Organization Administrator role using one of the following authentication methods:
    • Local - Enter your email address and password.
    • SSO with a public identity provider - Continue with a public identity provider account, such as Google or Microsoft.
  3. Select the organization to use, and then click Configure SAML.

    Logging in to access the organization SAML configuration page

    The organization SAML configuration page displays.

  4. Use the following tabs to resolve the issues:
    • Production tab - You can temporarily disable SAML authentication so that users can log in using local or public identity provider authentication until you can resolve the SAML issues.
    • Draft tab - Edit, test, and publish an updated SAML configuration.

Managing Provisioned Users and Groups

If SCIM provisioning is enabled for your organization, then you manage users and groups within your identity provider (IdP). All changes made in the IdP are automatically synchronized to IBM StreamSets.

When SCIM provisioning is enabled, you cannot use Control Hub to perform the following actions:
  • Invite, activate, deactivate, or delete users.
  • Create or delete groups.
  • Update user or group details.
  • Update your display name or leave the organization in your account settings.

Although the default all group is not provisioned from the IdP, you also cannot update the display name or update the users that belong to the all group.

You do use Control Hub to assign roles and permissions to provisioned users and groups.