Zoomdata Version

Configuring Zoomdata to Support SAML

overview

This article will guide you through the following steps to configure SAML Settings in Zoomdata:

  1. Obtain the XML metadata file from your organization's SAML  Identity Provider (IdP).
  2. Create a Key File using the Key Tool Generator program.
  3. Log into Zoomdata as the Supervisor and configure the SAML settings in the Security tab.
  4. Configure the service provider details in your IdP account that you want accessible by Zoomdata.
  5. Upload Identity Provider Metadata and add key files to Zoomdata.
  6. Configure the SAML mappings in Zoomdata.

In addition, there are optional configurations you can set up:

Prerequisites

Obtain Identity Provider Metadata File

To enable Zoomdata to support your organization's identity provider, first obtain the metadata content from your IdP and upload into Zoomdata. Your Security Administrator responsible for managing IdPs can provide this file. Save this metadata file to your local hard drive for uploading into Zoomdata. Refer to the configuration instructions provided below.

ACTION: Obtain the XML metadata file from your organization’s IdP (see Figure 1 for an example XML metadata file).


Figure 1

Generate a Key File and Configuring SAML with SSL

The Key File helps you manage a keystore of cryptographic keys and trusted certificates. Generate the Key File using the keytool program available from Oracle. After generating a key file, you will be able to import your SSL certificate into the keystore.

After installing the keytool program, take the following steps:

  1. Run the following command to generate your key:
keytool -genkey -alias localhost -keyalg RSA -keystore mykeystore .jks -keysize 2048
-validity 7000
  • Replace localhost with a unique alias (or name) for your Key. This name is used (in the 'Key' field) when you set up SAML in Zoomdata.
  • Replace mykeystore with a unique name for your Key Store file. This is the file that will be uploaded into Zoomdata.
  • The validity flag will set the expiration for the certificate for this key. This value can be changed accordingly based on how long your key will be valid before expiring.
  1. At the prompt, create the keystore password (yourKeyStorePassword) and press Enter.
  2. For the next prompt, create a key password (yourKeyPassword) and press Enter.
  3. Enter the following command to import your SSL certificate (valid x.509) into the keystore:
keytool -import -trustcacerts -alias yourAliasName -file yourcertr.cer -keystore mykeystore .jks

  • Replace yourAliasName with a unique name for your certificate.
  • Replace yourcertr.cer with the name of your SSL certificate.
  • Replace mykeystore with the Key Store filename that you created in Step 1 above.

The Key File is saved to your local hard drive. You will be uploading this Key File into Zoomdata in the configuration instructions provided below.

STEP-BY-STEP CONFIGURATION INSTRUCTIONS

Access Zoomdata and take the following steps to configure SAML Settings:

  1. Log in as Supervisor.
  2. Click Security from the menu bar and select the SAML Settings tab.


Figure 2

  1. Click Upload Identity Provider Metadata to upload the IdP's metadata file into Zoomdata.
  2. Click Add Key File to upload the Key File (that you generated from the Keytool program).
  3. Enter the following information related to the 'Key' fields:
    • Key (alias): the unique alias you created for the Key (for example, we used localhost )
    • Key Pass (word): your (yourKeyPassword)
    • Key Store Pass (word): your (yourKeyStorePassword)
    • Base URL : The Zoomdata URL that users will be logging into via SSO.
      If the base URL is changed after saving these SAML settings, update this field then reboot Zoomdata before downloading the metadata file.


Figure 3

ACTION: Return to your IdP account and configure the service provider information to allow Zoomdata access to the  desired attributes (these fields are explained in the next section below):
  • Required Attribute in Zoomdata: Username
  • Optional Attributes:
    • Groups
    • Account
    • Active account
    • Email
    • Full Name

Once you have configured the SAML attributes in your IdP account, you can update the SAML mappings in Zoomdata.

  1. Enter the attribute name for the Username Mapping field (as established in your IdP account).
    This is the name of the SAML attribute in your IdP account containing the list of usernames. This field is required so that users can be imported into and given access to Zoomdata. The imported values will be used as login names for Zoomdata users.


Figure 4

If using ADFS, make sure to add this attribute specified in the Username Mapping field as a claim rule name in ADFS. Otherwise, this attribute will not be sent by the identity provider and will cause the SAML login to fail. For more information, refer to Issue #4 in our commonly reported SAML issues.

The Group, Email, Account, Active Account and Full Name Mapping fields are optional. Use these fields if you are looking to automate the setup of user and group attributes in Zoomdata.

  • Groups (the name of the SAML attribute containing the multi-value list of group names identifying user memberships)
    By default, groups created in Zoomdata via SAML will not have any permissions or access to data sources. The Zoomdata Administrator must manually assign privileges to the group.
  • Account (SAML attribute which contains the multi-value list of account names to which a user should be added)
  • Active Account (SAML attribute of the default account for the user)
  • Email (the name of the SAML attribute containing user emails)
  • Full Name (the name of the SAML attribute containing the full name of users)
For information about the Mapping options, refer to the article Overview of How to Implement SSO in Zoomdata .
  1. Select the account that the user will be added from the Default Account list. If you do not want to assign a user to any account, from the Default Account list, select Disable Automatic Provisioning . The account, that you select from this list will be set as default only in case you have not specified Active account .
  1. Enable SAML.
  2. Click Save .

After you have set up all the necessary fields in the Zoomdata SAML Settings page and saved the configuration, the last step will be to have Zoomdata generate the metadata file that will be imported into your organization's IdP:

If you've already configured the SAML configuration and have made changes to the keystore, restart the Zoomdata server for these changes to take effect.
  1. Download the Metadata file by clicking the corresponding button.

The metadata file is an .xml file that you will upload to your IdP. Successfully enabling SSO in Zoomdata will result in a change to the Login screen (as shown in Figure 5).


Figure 5

You still have the option to log into Zoomdata without using single sign-on. Selecting the Show Zoomdata Authentication option lets you log in using your Zoomdata credentials. The first time that users log into Zoomdata via SAML, Zoomdata will automatically create the user profile in the Users and Groups administrative page. In addition, if the user is a member of one or more groups, the Group(s) will also be created (as long as the Group Mapping was provided during setup).

Key-Value Store

The Key-Value Store allows you to store additional attribute mappings that may be available in your IdP's SAML Assertions file (for example, Address, City, State and Zip Code). However, the current GA Program does not utilize any of these additional attributes. Future release versions will incorporate this capability in the Users and Groups function so that additional levels of security and access requirements can be established using these attributes.

If you want to encrypt specific custom attribute mappings, select the Secure checkbox for the required key-value pairs.


Figure 6

Optional Configurations

Configuring SAML behind a load balancer

You need to configure the settings to work with Zoomdata using SAML if there is unencrypted communication between the proxy and back-end servers and the load balancer is configured to use SSL.

The default configuration parameters are as follows:

saml.lb.enabled=false
saml.lb.scheme=https
saml.lb.serverName= www.myserver.com

For example, for the following front-end URL https:// myserver.com /zoomdata, configure the settings in the zoomdata. properties file as described below:

saml.lb.enabled=true
saml.lb.serverName= myserver .com

Customizing the Zoomdata Entity ID

If your identity provider already contains a service provider using the entity ID 'zoomdata', you can create a unique entity ID for Zoomdata. Also, this is applicable if you have two or more separate Zoomdata instances and your IdP requires unique instance identifiers. To do this, you create an alias in the zoomdata.properties file using:

saml.entityId= aliasZoomdataName

Make sure that Base URL, that you specified while configuring SAML settings, is the same that was used for generating the metadata file with the corresponding entityId .

For guidance on accessing and editing the zoomdata.properties file, refer to the article Managing Configurations in Zoomdata .

Configuring the Auto-Redirect to the IdP

SAML can be configured to automatically redirect to the identity provider without prompting you with the Zoomdata login.  To configure this, edit the zoomdata.properties file and add the following parameter:

login.page=/saml/login/**

You can still log into Zoomdata using credentials by navigating your browser to your_Zoomdata_URL /zoomdata/login .

For guidance on accessing and editing the zoomdata.properties file, refer to the article Managing Configurations in Zoomdata .

TROUBLESHOOTING

For basic SAML troubleshooting, refer to our SAML Troubleshooting documentation. If additional assistance is needed, feel free to reach out to our Technical Support team.