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 are:

ManageUsers - grants the ability to create, modify, and delete users. A user can not create or modify a user to have more permissions than they have.
ImpersonateUsers - grants the ability to impersonate other users. A user can only impersonate users that have fewer permissions than they.
ManageUserRoles - grants the ability to create, modify, and delete user roles. A user can not create or modify a role with more permissions than what they have.
ManagePasswords - grants the ability to reset user passwords.
ManageUserStates- grants the ability to unlock, disable, and enable users.
ConfigureLookAndFeel - grants the ability to see the Advanced tab in the Settings where certain look and feel related changes can be made.
ManageConnections - grants the ability to connect to databases from the Connections tab in the Settings.
ManageDatasets - grants the ability to access the Druid console.
AdministerDataCubes - grants the ability to see and modify all data cubes irrespective of their sharing and access configuration.
AdministerDashboards - grants the ability to see and modify all dashboards irrespective of their sharing and access configuration.
AdministerSavedQueries - grants the ability to see and modify all saved SQL queries
AdministerAlerts - grants the ability to see and modify all alerts
ChangeDataCubes - grants the ability to create, modify, and delete data cubes within the access granted via the individual configuration.
ChangeDashboards - grants the ability to create, modify, and delete dashboards within the access granted via the individual configuration.
ChangeAlerts - grants the ability to create, modify, and delete alerts within the access granted via the individual configuration.
SeeOtherUsers - grants the ability to see the names of the other users in the system, currently only used in the sharing.
AccessSQL - grants the ability to access the SQL tab. Note that users with SQL access can effectively perform arbitrary queries.
AccessVisualization - grants the ability to access the Visualize tab.
AccessDatasets - grants the ability to access the Data tab.
AccessAlerts - grants the ability to access the Alerts section.
QueryRawData - grants the ability to see the raw (unaggregated) data. Note that this permission is independent from the AccessSQL permission. A user without the QueryRawData could still query raw data via the SQL IDE if they have the AccessSQL permission.
DownloadData - grants the ability to export/download the data.
DownloadLargeData - grants the ability to download larger data sets. See data export for more info.
MonitorQueries - grants the ability to monitor the data base queries that Pivot is issuing under the hood.
ManageApiTokens - grants the ability to create and delete API tokens.
ManageAlertsWebhooks - grants the ability to modify an alert's webhooks.
SeeErrorMessages - grants the ability to see detailed error messages.

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:

Pivot can manage roles by itself
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.
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 Pivot will be used to manage the roles and LDAP will only be used for user authentication

userMode: ldap-authentication

roleAuthority: 'native' # Indicate that Pivot should be manging 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 hot 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 hot 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

Pivot can also be configured to use an OIDC identity provider to authenticate users and map identity provider groups to Pivot roles. When Pivot is configured to use an OIDC connection, each user will be created in Pivot when they first log in.

Once you have created an OIDC application with your identity provider, you should have a "Client secret" and "Client ID" available, which can be used to configure Pivot:

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

Note that the roleAuthority config can be used here in much the same way as when mapping LDAP roles to Pivot roles.

Also note that when adding groups to the oidcOptions scope, you may need to configure your identity provider application to expose the correct groups.

Once this is configured and Pivot is restarted, the Imply UI login screen will direct users to log in with your identity provider.

Tutorial

Deploy

Manage Data

Query Data

Visualize

Configure

Special UI Features

Imply Manager

Misc

User management in Pivot

Managing permissions and roles

Managing users

Users impersonation

Using LDAP in Pivot

Let Pivot manage the user roles

Translate Pivot roles from the LDAP user object

Translate Pivot roles from a separate LDAP query

Using OIDC in Pivot

Tutorial

Deploy

Manage Data

Query Data

Visualize

Configure

Special UI Features

Imply Manager

Misc