Using Keycloak

This documentation is for Dash Enterprise.
Dash Enterprise is the fastest way to write & deploy Dash apps and
Jupyter notebooks.
10% of the Fortune 500 uses Dash Enterprise to productionize AI and
data science apps. Find out if your company is using Dash Enterprise.

Dash Enterprise 5 uses Keycloak, an open-source identity and access management solution.

The Keycloak admin console (or Keycloak) is where administrators can configure authentication settings, manage users, assign roles, and set up an identity provider. To access Keycloak, you’ll need special credentials. These credentials were obtained by the administrator who performed your Dash Enterprise installation and stored according to your organization’s best practices.

Creating Your Admin User

Administrators who handle user management typically create a Dash Enterprise user with the admin role for themselves. If you don’t already have a Dash Enterprise admin user, create one natively in Keycloak to be able to log in to Dash Enterprise with
admin privileges. Alternatively, skip to Choosing an Identity Provider Mode to use a user from your IdP (assigning the admin role after integrating the IdP).

To access Keycloak directly and create your admin user:

  1. Go to https://auth-<your-dash-enterprise-server>.
  2. Select Administration Console.
  3. Enter the Keycloak credentials that were stored as part of your Dash Enterprise installation; then select Sign In.

  4. Make sure Dash is selected in the realm list in the top left corner.

    Dash realm

  5. Select Users > Add User.

  6. In Username, enter the username you want to use.

Known issue: Usernames with capital letters cause Dash Enterprise to incorrectly apply certain permissions. Use full lowercase (for example, jenny) when creating users.

  1. Select Save. Additional settings become available.
  2. Go to Credentials.
  3. In Password and Password Confirmation, enter the password you want to use.
  4. Select Set Password; then set password again to confirm.
  5. Assign the admin role:
    1. Go to Role Mappings.
    2. In Client Roles, select dash.
    3. In Available Roles, select admin; then select Add selected. Note that if you intend on deploying Dash apps, you’ll also need the licensed_user role, and assigning this role consumes a license seat.

To log into Dash Enterprise with this user, go to https://<your-dash-enterprise-server> and enter the credentials you set in Keycloak. Dash Enterprise opens to the Portal. Go to the App Manager by selecting Apps > App Manager.

<img>

With the admin role, you have permission to access the Admin section of the App Manager. Users contains an overview of the user information in Keycloak,
and Settings contains useful links as well as the

Troubleshooting Identity and Access

Missing IdP Users or Groups

If you can’t find a user or group from an external IdP when adding co-owners or viewers to a Dash app, it may be because the user (or a member of the group) hasn’t logged in yet.

Users synced from an IdP are only available in Dash Enterprise once they log in, and IdP groups are only available once a member of the group logs in.

To be able to add a user as a viewer or co-owner on an app in Dash Enterprise before they log in, you can manually create an account for them in Keycloak and provide them with the password. When the user logs in for the first time using their IdP credentials, an “Account Already Exists” message will be displayed and they can select Add to existing account to merge the accounts. They’ll need to enter the credentials for the account that you manually created in Keycloak. The user will then be able to log in normally via the IdP for future sessions.

For details on how to create a new user, see Creating a New User. Make sure that the username you set in Keycloak matches the one in your IdP. Remember to share the credentials with the user, as they’ll need these to merge the accounts once they log in via the IdP.

Similarly, if you need an IdP group to be available in Dash Enterprise but none of its members have logged in yet, you can create a group in Keycloak with a name that matches the identifier mapped from your IdP.

For details on how to create a new group, see Creating Groups.