User management in Pivot

Managing permissions and roles

Every user within Imply can belong to one or more roles. A role is a collection of permissions that the user has access to. Some roles are created by default but the set of roles can be modified to fit specific use cases.

The roles can be managed from the settings view.

settings roles

You can edit an individual role and assign different permissions to it. It is not possible to edit the super-admin role which permits all actions.

settings role

Within a given role you can add and remove permissions that are granted to the users associated with that role. The permissions belonging to a given user is the superset of all the permissions from all the roles assigned to that user.

The possible permissions, grouped by category, are:

System permissions

Permission Description
ManageConnections Grants permission to manage database connections from the "Connections" tab in the Settings UI.
ManageApiTokens Grants permission to create and delete API tokens when API access is configured.
ConfigureLookAndFeel Grants permission to see the "Advanced" tab in the Settings UI where certain look and feel related changes can be made.

Users & Roles

Permission Description
ManageUsers Grants permission to create, modify, and delete users. Note that users cannot create or modify a user to have more permissions than they have.
ManageUserRoles Grants permission to create, modify, and delete user roles. Note that users will not be able to create or modify a role which grants additional permissions that they do not possess.
ImpersonateUsers Grants permission to impersonate other users. Note that users will not be able to impersonate users who have been granted permissions that the impersonating user does not have.
ManagePasswords Grants permission to reset user passwords.
ManageUserStates Grants permission to disable and lock user accounts.
SeeOtherUsers Grants permission to see the other users in the system when sharing.

Datasources

Permission Description
AccessDatasets Grants permission to access the Data tab.
ManageDatasets Grants permission to access the Druid console.

Data cubes & dashboards

Permission Description
AccessVisualization Grants permission to access the Visualize tab.
AdministerDataCubes Grants permission to view and manage all data cubes irrespective of their sharing and access configuration.
CreateDataCubes Grants permission to create and duplicate data cubes within the access granted via the individual configuration.
ChangeDataCubes Grants permission to modify and delete data cubes within the access granted via the individual configuration.
AdministerDashboards Grants permission to view and manage all dashboards irrespective of their sharing and access configuration.
ChangeDashboards Grants permission to create, modify, and delete dashboards within the access granted via the individual configuration.
QueryRawData Grants permission to see the raw unaggregated data behind a data cube visualization. Note that this permission is independent from the AccessSQL permission. A user without the QueryRawData permission can still query raw data via the SQL IDE if they have the AccessSQL permission.
DownloadData Grants permission to export/download data from a data cube.
DownloadLargeData Grants permission to download larger data sets. See data export for more info.
MonitorQueries Grants permission to monitor database queries that Pivot data cubes and dashboards issue under the hood.

SQL Queries

Permission Description
AccessSQL Grants permission to access the SQL tab. Note that users with SQL access can effectively perform arbitrary queries.
AdministerSavedQueries Grants permission to see and modify all saved SQL queries.

Alerts

Permission Description
AccessAlerts Grants permission to access the Alerts tab.
AdministerAlerts Grants permission to view and manage all alert configurations irrespective of their sharing and access configuration.
ChangeAlerts Grants permission to create, modify, and delete alerts within the access granted via the individual configuration.
ManageAlertsWebhooks Grants permission to configure alerts to send webhook notifications.

Reports

Permission Description
AccessScheduledReports Grants permission to access the Reports tab.
AdministerScheduledReports Grants permission to view and manage all report configurations irrespective of their sharing and access configuration.
ChangeScheduledReports Grants permission to create, modify, and delete reports within the access granted via the individual configuration.

Role visibility

When setting up a role, it is also possible to define how this role and users assigned to this role will appear when sharing system artifacts like data cubes, dashboards, alerts, or reports using access control lists.

The visibility of the role itself in access control lists is set by the "Role visibility" dropdown. The visibility of members of the role in access control lists is set by the "Member visibility" dropdown. For each of these, there are three possible options:

The SeeOtherUsers permission takes precedence over role visibility controls. Users with this permission will be able to see all roles and users in the system.

Role-level connection auth

It is also possible to set up a connection token associated with a role. This connection token will be used to communicate with the Druid cluster for all configured Pivot connections. This allows you to map Pivot roles to Druid basic-auth users, which can be set up to limit which datasources are exposed.

The auth token takes the form:

{
    "type" : "basic-auth",
    "username": <USERNAME>,
    "password": <PASSWORD>,
    "priority": <1-10>
}

The priority property is used to determine which auth token should be used when a user has multiple roles with auth tokens configured. The highest priority will take precedence. In the case of multiple auth tokens with matching properties, a deterministic alphabetic sort on the role name will be used to apply a match.

Managing users

You can manage users in the Users tab in the settings.

settings users

Here you can create new users and edit and assign roles to existing users.

Users impersonation

If you have the ImpersonateUsers permission you can impersonate users from the user menu

impersonation

Using LDAP in Pivot

Pivot can be configured to use an LDAP server to authenticate users and to map the LDAP group assignment to the Pivot roles. When Pivot is connected to an LDAP server each user is created in Pivot when they first login.

There are three principle approaches to translate LDAP user groups into Pivot roles:

  1. Pivot can manage roles by itself
  2. Pivot roles can be determined based on an attribute on the user object. This is simpler and performs only a single LDAP lookup per user login.
  3. Pivot roles can be determined by doing a second LDAP lookup after getting the user object from LDAP. This is more flexible and suitable when the LDAP directory is structured with the groups being a separate object from the user.

These two approaches are discussed in turn. The examples assume a LDAP server running on ldap://ldap_host:389 with a bind DN of cn=admin,dc=imply,dc=io (credentials JonSn0w). We will use the username scoops to test that everything is working.

Let Pivot manage the user roles

In this mode, LDAP authenticates users while Pivot manages roles (as determined by the roleAuthority property value of local). See roleAuthority for more information about this setting.

userMode: ldap-authentication

roleAuthority: 'native' # Indicate that Pivot should be managing roles

defaultRole: 'user' # The Pivot role externalId that the user will be mapped to

superAdminUser: 'james' # The username of a user that will always made super-admin, useful for bootstrapping.

ldapOptions:
  url: 'ldap://ldap_host:389' # Your LDAP server
  bindDN: 'cn=admin,dc=imply,dc=io' # The admin bind dn
  bindCredentials: 'JonSn0w' # The password for the admin bind dn
  searchBase: 'dc=imply,dc=io' # The search base where your users are located
  searchFilter: '(uid={{username}})' # The search filter that specifies how to find a specific user

Test this setup by running an ldapsearch command to search for an existing user scoops in this example (adjust as needed):

ldapsearch -x -h ldap_host -p 389 -D "cn=admin,dc=imply,dc=io" -w "JonSn0w" -b "dc=imply,dc=io" "(uid=scoops)"

Returns something like:

# extended LDIF
#
# LDAPv3
# base <dc=imply,dc=io> with scope subtree
# filter: (uid=scoops)
# requesting: ALL
#

# sheldon, people, imply.io
dn: cn=sheldon,ou=people,dc=imply,dc=io
givenName: Sheldon
sn: Cooper
objectClass: imAuthUser
uid: scoops
userPassword:: YmlnLmJhbmcudGhlb3J5
mail: sheldon@imply.io
description: super-admin
cn: sheldon

# search result
search: 2
result: 0 Success

# numResponses: 2
# numEntries: 1

You can set verbose: true to see the keys being returned and make sure that rolesKey is set appropriately.

Translate Pivot roles from the LDAP user object

In this mode Pivot will use a property on the LDAP user object to determine the Pivot role that the user should belong to. The ldapOptions.rolesKey indicates which key on the user object should map the external ID of the Pivot role.

# Setting verbose mode to true will log the user objects received from the LDAP server.
# This can be very helpful to tune properties like rolesKey (below)
verbose: false

userMode: ldap-authentication

superAdminUser: 'james' # The username of a user that will always made super-admin, useful for bootstrapping.
ldapOptions:
  url: 'ldap://ldap_host:389' # Your LDAP server
  bindDN: 'cn=admin,dc=imply,dc=io' # The admin bind dn
  bindCredentials: 'JonSn0w' # The password for the admin bind dn
  searchBase: 'dc=imply,dc=io' # The search base where your users are located
  searchFilter: '(uid={{username}})' # The search filter that specifies how to find a specific user
  rolesKey: 'description' # The key on the returned member object that represents group membership

Test this setup by running an ldapsearch command to search for an existing user scoops in this example (adjust as needed):

ldapsearch -x -h ldap_host -p 389 -D "cn=admin,dc=imply,dc=io" -w "JonSn0w" -b "dc=imply,dc=io" "(uid=scoops)"

Returns something like:

# extended LDIF
#
# LDAPv3
# base <dc=imply,dc=io> with scope subtree
# filter: (uid=scoops)
# requesting: ALL
#

# sheldon, people, imply.io
dn: cn=sheldon,ou=people,dc=imply,dc=io
givenName: Sheldon
sn: Cooper
objectClass: imAuthUser
uid: scoops
userPassword:: YmlnLmJhbmcudGhlb3J5
mail: sheldon@imply.io
description: super-admin
cn: sheldon

# search result
search: 2
result: 0 Success

# numResponses: 2
# numEntries: 1

You can set verbose: true to see the keys being returned and make sure that rolesKey is set appropriately. In this case the ldapOptions config will use description as the role to map to the Pivot roles via the External Role Name:

settings-role1

Translate Pivot roles from a separate LDAP query

For a separate group search set the ldapOptions as follows:

# Setting verbose mode to true will log the user objects received from the LDAP server.
# This can be very helpful to tune properties like rolesKey (below)
verbose: false

userMode: ldap-authentication

superAdminUser: 'james' # The username of a user that will always made super-admin, useful for bootstrapping.
ldapOptions:
  url: 'ldap://ldap_host:389'
  bindDN: 'cn=admin,dc=imply,dc=io'
  bindCredentials: 'JonSn0w'
  searchBase: 'dc=imply,dc=io'
  searchFilter: '(uid={{username}})'
  groupSearchBase: 'ou=groups,dc=imply,dc=io'
  groupSearchFilter: '(member={{dn}})'
  groupSearchAttributes: ['dn', 'cn']
  groupKeyAttribute: 'dn'

Test this setup by running an ldapsearch to get the user like below (adjust variables as needed).

ldapsearch -x -h ldap_host -p 389 -D "cn=admin,dc=imply,dc=io" -w "JonSn0w" -b "dc=imply,dc=io" "(uid=scoops)"

Returns something like:

# extended LDIF
#
# LDAPv3
# base <dc=imply,dc=io> with scope subtree
# filter: (uid=scoops)
# requesting: ALL
#

# sheldon, people, imply.io
dn: cn=sheldon,ou=people,dc=imply,dc=io
givenName: Sheldon
sn: Cooper
objectClass: imAuthUser
uid: scoops
userPassword:: YmlnLmJhbmcudGhlb3J5
mail: sheldon@imply.io
description: super-admin
cn: sheldon

# search result
search: 2
result: 0 Success

# numResponses: 2
# numEntries: 1

And then, using the dn from the result above cn=sheldon,ou=people,dc=imply,dc=io run a second ldapsearch to get the groups like below (adjust variables as needed).

ldapsearch -x -h ldap_host -p 389 -D "cn=admin,dc=imply,dc=io" -w "JonSn0w" -b "ou=groups,dc=imply,dc=io" "(member=cn=sheldon,ou=people,dc=imply,dc=io)"

Returns something like:

# extended LDIF
#
# LDAPv3
# base <ou=groups,dc=imply,dc=io> with scope subtree
# filter: (member=cn=sheldon,ou=people,dc=imply,dc=io)
# requesting: ALL
#

# boys, groups, imply.io
dn: cn=boys,ou=groups,dc=imply,dc=io
objectClass: groupOfNames
member: cn=jack,ou=people,dc=imply,dc=io
member: cn=sheldon,ou=people,dc=imply,dc=io
member: cn=marcel,ou=people,dc=imply,dc=io
cn: boys

# search result
search: 2
result: 0 Success

# numResponses: 2
# numEntries: 1

Then use the dn property of the returned groups to map to the Pivot roles via the External Role Name:

settings-role

For more info see the config-api documentation.

Using OIDC in Pivot

You can authenticate and authorize Pivot users using an external OIDC identity provider. Pivot relies on the external system to authenticate users and map identity provider groups to Pivot roles.

When Pivot is configured to use an OIDC connection, it creates an account for the user the first time the user logs in.

By default, Pivot uses the subject (sub) value returned in the UserInfo response as the user ID in Pivot. If you want to use an alternate value instead—say, for example, if sub values do not map to easily identifiable user names in your system—you can specify a custom value in the UserInfo response instead, using imply_alternative_sub. If
imply_alternative_sub appears in the UserInfo response and there's no user identified by the sub value, Pivot creates a new user with a user ID drawn from the imply_alternative_sub value.

After creating an OIDC application with your identity provider, you should have a "Client secret" and "Client ID" available. Configure those values as oidcOptions fields in the Pivot configuration, in the following format, where <YOUR_IDP_DOMAIN.COM> references the domain for your identity provider, e.g. "https://abc.okta.com" and <OIDC_APPLICATION_*> references your OIDC application settings:

userMode: oidc-authentication
defaultRole: '<DEFAULT_USER_ROLE>'
oidcOptions:
  issuer: 'https://<YOUR_IDP_DOMAIN.COM>'
  client_id: '<OIDC_APPLICATION_CLIENT_ID>'
  client_secret: '<OIDC_APPLICATION_CLIENT_SECRET>'
  app_base_url: '<OIDC_APPLICATION_BASE_URL>'
  scope: 'openid profile email groups'

You can use Pivot to authorize user roles while authenticating users by OIDC by setting roleAuthority to local, as described in mapping LDAP roles to Pivot roles.

The issuer value should be the base URL of the OpenID Provider Configuration Document for your identity provider. It is automatically concatenated with /.well-known/openid-configuration. If the provider configuration document in your environment is not available at that URL, you may provide a discoveryUrl parameter instead of issuer with the value set to a fully qualified URL to the discovery document.

If adding groups to the oidcOptions scope, you may need to configure your identity provider application to expose the correct groups. Refer to your identity provider documentation for information on how to make the groups scope available.

Once this is configured and Pivot is restarted, the Pivot login screen directs users to log in with the identity provider you have configured.

Overview

Tutorial

Deploy

Administer

Manage Data

Query Data

Visualize

Configure

Special UI Features

Misc