Console Initial Setup

Prerequisites

• Access to Keycloak Master Realm
• SSO has been setup for:
  • GitLab
  • Mattermost
  • Jira
  • Confluence

note

SSO setup for tools that are disabled is not required.

Keycloak

note

SmoothGlue will automatically configure this client and group out of the box. This serves primarily as reference if opting out of the auto-SSO feature. Skip to Create Initial 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. Leave Client authentication toggled off, and ensure Direct access grants is unchecked.
7. Click on the Next button.
8. Set Valid Redirect URIs to https://console.${DOMAIN}/api/auth/callback/keycloak.
9. Set Valid post logout redirect URIs to https://console.${DOMAIN}.
10. Click on the Save button.
11. In the Settings tab and in the Capability config section, ensure Standard flow is enabled.
12. In the Advanced tab and in the OpenID Connect Compatibility Modes section, ensure Use refresh tokens is On.
13. Click Save at the bottom of the screen.

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 User Attribute.
5. Enter tools for Name, User Attribute and Token Claim Name.
6. Set Claim JSON Type to String.
7. Ensure Add to ID token is OFF.
8. Ensure Add to access token and Add to userinfo is ON.
9. Ensure Multivalued and Aggregate attribute values is ON.
10. 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.

Create Initial Admin User

Console needs an initial Keycloak user with the realm-admin role in order to be able to fully initialize. This initial Keycloak user will be able to create other users and admin users with Keycloak. This user will also be used to setup access keys and permissions within tools Console supports integrations for.:

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

Set a password for the console-initial-admin user:

1. From the smoothglue realm, go to Users > console-initial-admin.
2. Go to the Credentials tab.
3. Click Set password.
4. Enter a password.
5. Disable Temporary.

caution

It is recommended to remove the password for this user once the initial setup is complete for Console.

Configure Console for Keycloak

Console uses the permissions of the logged-in user to interact with Keycloak. As such, a client secret is not required. However, Console will need be configured with a client ID.

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.

Add the following to bigbang-values.yaml:

packages:
  console:
    values:
      keycloak:
        host: keycloak.<DOMAIN>
      envs:
        # Keycloak Client ID configured above
        KEYCLOAK_ID: console
      extraCACerts: |
        -----BEGIN CERTIFICATE-----
        ...
        -----END CERTIFICATE-----

Configure Console Integrations

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

• GitLab
• Mattermost
• Jira
• Confluence

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

packages:
  console:
    values:
      mattermost:
        enable: false
      gitlab:
        enable: false
      confluence:
        enable: false
      jira:
        enable: false

caution

Failing to disable unused integrations can lead to initialization failures.

GitLab

Users are dynamically created upon login to GitLab, so the System Integrator needs to login to GitLab as the console-initial-admin user in order to create the user within GitLab.

After logging in as console-initial-admin logout of GitLab and log in as the default admin user for GitLab.

Assign admin privileges to the console-initial-admin 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-initial-admin user.
4. Change Access level to Administrator
5. Click Save changes.

Create Personal Access Token:

1. Impersonate or log in as the console-initial-admin user.
2. Click the user icon in the top-left corner, and select Preferences.
3. Click Access Tokens on the left-hand panel.
4. Click a Add a new token:
   1. Name: console-admin-integration.
   2. Remove the expiration date.
   3. Scopes: api and admin_mode.
   4. Click Create personal access token.
5. Save the value for the token.

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

packages:
  console:
    values:
      gitlab:
        accessToken: '<Personal Access Token Value>'
        host: 'gitlab.<DOMAIN>'

Jira/Confluence

Users are dynamically created upon login to Jira, so the System Integrator needs to login to Jira as the console-initial-admin before proceeding.

Assign admin privileges to console-initial-admin 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-initial-admin by clicking the kebab icon (3 vertical dots) to add the following groups: a. jira-administrators b. confluence-users c. confluence-administrators

Create Jira Personal Access Token:

1. Log into Jira as the console-initial-admin user.
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-admin-integration.
   2. Disable Automatic expiry.
5. Click Create.
6. Save token value.

Create Confluence Personal Access Token:

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

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

packages:
  console:
    values:
      jira:
        host: 'jira.<DOMAIN>'
        accessToken: '<Jira Access Token Value>'
      confluence:
        host: 'confluence.<DOMAIN>'
        accessToken: '<Confluence Access Token Value>'
      envs:
        JIRA_USERNAME: 'console-initial-admin'

Mattermost

Enable Personal Access Tokens for Admins:

1. Login to Mattermost with an admin-level account
2. Click the 9 dot symbol in the top-left (left of the Mattermost logo).
3. Click System Console.
4. Click Integration Management in the left-hand panel.
5. Enable Personal Access Tokens: True
6. Click Save.
7. Leave System Console by clicking Back to <team name>.

Create Personal Access Token

1. Login to Mattermost with an admin-level account
2. Click profile icon in the top-right.
3. Click Profile.
4. Click Security.
5. Click Edit for Personal Access Tokens.
6. Click Create Token:
   1. Token Description: console-admin-integration.
   2. Click Yes, Create.
7. Save Access Token value.

packages:
  console:
    values:
      mattermost:
        host: 'chat.<DOMAIN>'
        accessToken: 'Access Token Value'

Initialize Console

After a fresh installation of SmoothGlue Console, the application needs to perform some initialization of its database. This initialization needs to be triggered by a Keycloak user within the smoothglue realm and the user needs to have realm-management roles/permissions in Keycloak. Assuming the steps above have been followed for Creating the Initial Admin User, the console-initial-admin should be used for the following steps:

1. Visit the {console-url}/api/initialize endpoint in a browser to initialize the database with the necessary tools.
2. Visit {console-url} in a browser and log in as the console-initial-admin user.
3. Visit {console-url}/api/initialize again. This time, you will be established properly in SmoothGlue Console as a SmoothGlue Admin.
4. Restart the smoothglue console processes.

note

The first user to complete these initialization steps will become the default admin within SmoothGlue Console.

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.