Skip to main content
Version: 7.0.0

Console Initial Setup

Prerequisites​

note

SSO setup for tools that are disabled is not required.

Keycloak​

note

SmoothGlue can automatically configure this client and group out of the box. Please see the SmoothGlue auto-SSO feature. Skip to Create Console-Bot Admin User if not manually setting up the Keycloak client and group.

Create Keycloak Client​

  1. In the smoothglue realm, click on Clients under Manage in the left pane.
  2. Click Create client.
  3. Ensure the Client type is OpenId Connect.
  4. Enter a unique client name (e.g., console) for Client ID.
  5. Click on the Next button.
  6. Ensure Client authentication is toggled on, Standard flow is enabled, and Direct access grants is disabled
  7. Click on the Next button.
  8. Set Valid Redirect URIs to https://console.${DOMAIN}/login/generic_oauth.
  9. Set Valid post logout redirect URIs to https://console.${DOMAIN}.
  10. Click on the Save button.

Configure Dedicated Mapper​

  1. Go to the console client and click on the Client scopes tab.
  2. Click on the console-dedicated client scope.
  3. Click Configure a new mapper.
  4. Select Group Membership.
  5. Enter console-group-membership-mapper for Name,
  6. Enter groups for Token Claim Name.
  7. Click Save.

Configure _structsureAdmins Group​

Console assigns SmoothGlue admins configured in Console to the _structsureAdmins group in Keycloak. It is important that this group has the realm-admin role mapping so that admins can manage users in Keycloak via Console:

  1. In the smoothglue realm, click Groups in the left-hand panel.
  2. Select _structsureAdmins.
  3. Go to Role mapping tab.
  4. Click Assign role.
  5. Ensure the drop-down filter in the top left is set to Filter by clients.
  6. Search for and enable the realm-admin role.
  7. Click Assign.

Configure Console for Keycloak​

Console uses authservice to get a Java Web Token (JWT) from Keycloak that contains info about the currently logged-in user. Console uses the permissions of the logged-in user to interact with Keycloak APIs to manage user accounts.

If Keycloak is using non-publicly trusted or self-signed certificates, Console will need to be configured with additional CAs in order for Console to talk to Keycloak.

note

The following is automatically configured when using the SmoothGlue auto-SSO feature.

Add the following to bigbang-secrets.yaml:

addons:
  authservice:
    chains:
      console:
        callback_uri: https://console.<DOMAIN>/login/generic_oauth
        match:
          header: :authority
          prefix: console.<DOMAIN>
        client_id: console # the client name created above
        client_secret: <client_secret> # retrieve the client secret from the client's `Credentials` tab in Keycloak
packages:
  console:
    values:
      backend:
        keycloak:
          realm: smoothglue
          host: keycloak.<DOMAIN> # this value can be omitted but is required when setting a custom subdomain for Keycloak.
        caBundle: |
          -----BEGIN CERTIFICATE-----
          ...
          -----END CERTIFICATE-----

Create Console-Bot Admin User​

We recommend starting with an initial Keycloak bot-admin user with the realm-admin role in order to be responsible for downstream tool access tokens. This bot-admin will be used to set up access keys within tools that Console supports integrations for.

caution

Do not log in to Console UI with this user. It is recommended to remove the password for console-bot in Keycloak to reduce the chances of downgrading permissions.

  1. In the smoothglue realm, click Users in the left-hand panel.
  2. Click Add user.
  3. Fill in the following information for the initial user:
    1. Email verified: Enabled
    2. Username: console-bot
    3. Email: console-bot@<your-domain>.com
    4. First name: console
    5. Last name: bot
    6. Groups: _structsureAdmins
  4. Click Create.

Set a password for the console-bot user:

  1. From the smoothglue realm, go to Users > console-bot.
  2. Go to the Credentials tab.
  3. Click Set password.
  4. Disable Temporary.
  5. Enter a password.
  6. Click Save and Save password to confirm.
caution

Do not log in to Console UI with this user.

Configure Console Integrations​

Console has integrations with the following tools for managing users and access to resources:

  • GitLab
  • Mattermost
  • Jira

If Console is to be deployed without one or more of these tools, Console needs to be configured to disable the integration. The following is a bigbang-values.yaml example that could be used to disable any of the integrations:

packages:
  console:
    values:
      backend:
        mattermost:
          enabled: false
        gitlab:
          enabled: false
        jira:
          enabled: false
caution

Failing to disable unused integrations can lead to initialization failures.

GitLab​

Users are dynamically created upon logging in to GitLab, so the System Integrator needs to log in to GitLab as the console-bot user in order to create the user within GitLab.

After logging in as console-bot, log out of GitLab and log in as the default admin user for GitLab.

Assign admin privileges to the console-bot user:

  1. Go to the admin panel by clicking Admin near the bottom-left of the screen or by going to https://{{GitLab_Hostname}}/admin.
  2. Go to Users.
  3. Click Edit for the console-bot user.
  4. Change Access level to Administrator
  5. Click Save changes.

Create Personal Access Token:

  1. Log in to GitLab as console-bot.
  2. Click the user icon in the top-left corner, and select Preferences.
  3. Click Access Tokens on the left-hand panel.
  4. Click Add new token:
    1. Name: console-bot-admin-integration.
    2. Set an appropriate expiration date for the environment. This token will need to be manually rotated.
    3. Scopes: api and admin_mode.
    4. Click Create token.
  5. Save the value for the token.
caution

Removing or altering permissions in GitLab for console-bot after access tokens have been set could lead to unexpected issues.

To configure Console to use the access token, the following configuration should be placed into the bigbang-secrets.yaml:

packages:
  console:
    values:
      backend:
        gitlab:
          accessToken: '<Personal Access Token Value>'
          host: 'gitlab.<DOMAIN>' # this value can be omitted but is required when setting a custom subdomain for GitLab.

Jira​

Users are dynamically created upon logging in to Jira, so the System Integrator needs to log in to Jira as the console-bot before proceeding.

Assign admin privileges to console-bot user:

  1. Log in to Jira with an admin-level account.
  2. Click on the Settings gear icon in the top-right corner.
  3. Click User management.
  4. Edit user groups for console-bot by clicking the kebab icon (3 vertical dots) to add the following groups:
    1. jira-administrators

Create Jira Personal Access Token:

  1. Log in to Jira as console-bot.
  2. Click the user icon in the top-right corner, and go to Profile.
  3. Click Personal Access Tokens in the left-hand panel.
  4. Click Create token:
    1. Token name: console-bot-admin-integration.
    2. Disable Automatic expiry.
  5. Click Create.
  6. Save token value.
caution

Removing or altering permissions for console-bot in Jira after access tokens have been set could lead to unexpected issues.

To configure Console to use the access tokens, the following configuration should be placed into the bigbang-secrets.yaml:

packages:
  console:
    values:
      backend:
        jira:
          host: 'jira.<DOMAIN>' # this value can be omitted but is required when setting a custom subdomain for Jira.
          accessToken: '<Jira Access Token Value>'
        envs:
          JIRA_USERNAME: 'console-bot'

Mattermost​

Users are dynamically created upon login to Mattermost, so the System Integrator needs to login to Mattermost as the console-bot before proceeding.

Enable Personal Access Tokens for Admins:

  1. Log in to Mattermost with an admin-level account.
  2. The user will be prompted to create a team. This can be named/configured to the user's preference.
  3. Click the 9 dot icon in the top-left corner (left of the Mattermost logo).
  4. Click System Console.
  5. Click Integration Management in the left-hand panel.
  6. Enable Personal Access Tokens: True.
  7. Click Save.
  8. Leave System Console by clicking Back to <team name>.

Enable Admin for console-bot:

  1. Log in using a Mattermost admin-level account.
  2. Click the 9 dot icon in the top-left corner (left of the Mattermost logo).
  3. Click System Console.
  4. Navigate to User Management -> Users.
  5. Find console-bot, and in the Actions column, select Manage Roles and set to System Admin.
  6. Click Save.

Create Personal Access Token:

  1. Log in to Mattermost as console-bot.
  2. Click the profile icon in the top-right corner.
  3. Click Profile.
  4. Click Security.
  5. Click Edit for Personal Access Tokens.
  6. Click Create Token:
    1. Token Description: console-bot-admin-integration.
    2. Click Yes, Create.
  7. Save Access Token value.
  console:
    values:
      backend:
        mattermost:
          host: 'chat.<DOMAIN>' # this value can be omitted but is required when setting a custom subdomain for Mattermost.
          accessToken: '<Mattermost Access Token Value>'
caution

Removing or altering permissions in Mattermost for console-bot after access tokens have been set could lead to unexpected issues.

Create Admin User​

Now that the console-bot user access tokens have been set up, the next step is to create the initial admin user that will serve as the first user in Console UI.

  1. First, navigate to Keycloak and follow the same steps to set up an admin user in Keycloak:
note

This user will serve as the initial first admin and user within Console UI. The naming convention is up to the user; however, avoid the username admin, as it is reserved in some tools.

  1. In the smoothglue realm, click Users in the left-hand panel.
  2. Click Add user.
  3. Fill in the following information for the initial user:
    1. Email verified: Enabled
    2. Username: <your-desired-admin-username>
    3. Email: <your-desired-admin-username>@<your-domain>.com
    4. First name: <your-desired-admin-first-name>
    5. Last name: <your-desired-admin-last-name>
    6. Groups: _structsureAdmins
  4. Click Create.

Set a password for the admin user:

  1. From the smoothglue realm, go to Users > your-desired-admin-username.
  2. Go to the Credentials tab.
  3. Click Set password.
  4. Disable Temporary.
  5. Enter a password.
  6. Click Save and Save password to confirm.

Adopt User and Promote to Admin​

Now that the user account has been created in Keycloak, we can log in to Console UI and it will be adopted by the system.

  1. Navigate to Console UI and log in using your-desired-admin-username and password set up in Keycloak.

  2. Once successfully logged in, the user will exist in Console but not have admin privileges.

  3. Get the console-backend pod name from the cluster: kubectl get pod -n console | grep "console-backend".

  4. Get a shell on the backend pod: kubectl exec -it <console-backend-pod-name> -n console -- sh.

  5. Promote the user to platform admin by using the create_platform_admin script.

    1. Enter django-admin create_platform_admin.
    2. When prompted, enter the username for <your-desired-admin-username> that was created in Keycloak.
    3. Console UI should update automatically, but the session might require a refresh and/or a relogin, using the same credentials.

  6. Once the user is updated, at the top right of the screen where the username is located, there should be a drop-down that will have an option to toggle between admin and user mode. Select the Admin Panel view:

    Admin Panel

  7. Navigate to the Users view on Console UI:

    Platform Users View

  8. Repair the initial admin user created for Console use:

    note

    Repairing a user in Console UI will create the user in the following downstream tools:

    1. GitLab
    2. Mattermost
    3. Jira

    Repair User

Upon successfully repairing, the user will fully setup.

info

To learn more about Console's capabilities, continue reading our Introduction to SmoothGlue Console.

More information on available configuration options and technical descriptions of Console actions can be found in the Console Technical Manual.