SmoothGlue Console Technical Manual

Summary

SmoothGlue Console is a web application implemented using the Node.js framework, Next.js. Users directly access the SmoothGlue Console user experience through a web browser. Many user interactions result in REST-based API calls to SmoothGlue Console’s REST API. The REST API, offered by SmoothGlue Console, enumerates actions that users can take to effect change in both the console and the platform tools that are integrated with the console.

note

SmoothGlue Console requires a dedicated Postgres database and Keycloak instance.

Configuration

SmoothGlue Console takes configuration largely in the form of environment variables consumed by the Node.js process. Here are those environment variables|

Environment Variable	Description
ARGOCD_BASE_URL	The URL for Argo CD. SmoothGlue Console currently supports only one Argo CD instance
CONFLUENCE_BASE_URL	The URL for Confluence.
CONFLUENCE_PERSONAL_ACCESS_TOKEN	PAC smoothglue-console uses for auth for all Confluence API interactions
DB_HOST	hostname of database server, like localhost (not required if DATABASE_URL is set)
DB_PORT	network port for database server, like 5432 (not required if DATABASE_URL is set)
DB_USER	username that the smoothglue-console server will authenticate as when communicating with the database (not required if DATABASE_URL is set)
DB_PASS	password that the smoothglue-console server will authenticate as when communicating with the database (not required if DATABASE_URL is set)
DB_NAME	the name of the logical database containing smoothglue-console's data (not required if DATABASE_URL is set)
ENABLE_CONFLUENCE	“true” or “false” to denote whether Confluence support is enabled
ENABLE_GITLAB	“true” or “false” to denote whether GitLab support is enabled
ENABLE_JIRA	“true” or “false” to denote whether Jira support is enabled
ENABLE_MATTERMOST	“true” or “false” to denote whether Mattermost support is enabled
DATABASE_URL	database connection url, like postgres://db_user:db_pass@db_host:1234/db_name?schema=public (this is the default method used for database connection url, you can use this or the deconstructed variables above)
GITLAB_BASE_URL	The URL for GitLab. Should not include anything to the right of the complete hostname and optionally the port GITLAB_LOGO The logo presented in the UX for GITLAB_PERSONAL_ACCESS_TOKEN
JIRA_BASE_URL	The URL for Jira.
JIRA_PERSONAL_ACCESS_TOKEN	The PAC SmoothGlue Console will use to authenticate all comms with JIRA
JIRA_USERNAME	The Username of the user owning the JIRA_PERSONAL_ACCESS_TOKEN.
KEYCLOAK_BASE_URL	Note that it should always end in /auth
KEYCLOAK_ID	The Client ID for the Structsure Console client configured in Keycloak
KEYCLOAK_REALM	The realm name where Structsure users will exist.
MATOMO_SITE_ID	The site id to be communicated to Matomo if using Matomo analytics. Must also specify MATOMO_URL.
MATOMO_URL	The URL where Matomo is running, as seen by the Console user's browser. Must also specify MATOMO_SITE_ID.
MATTERMOST_BASE_URL	The URL for Mattermost.
MATTERMOST_PERSONAL_ACCESS_TOKEN	Personal access token with admin privileges
NEXTAUTH_SECRET	A random string is used to hash tokens, sign/encrypt cookies and generate cryptographic keys

Initialization

Please see the Console Initial Setup page for more information.

Authentication

SmoothGlue Console defers authentication to an OpenID Connect provider (OIDC provider). More specifically, SmoothGlue Console relies on an integration with a Keycloak instance in order to authenticate users. NextAuth.js is used for the OIDC interactions with Keycloak. When processing a subsequent request, SmoothGlue Console will use the resulting JWT from a successful authentication to determine who the current actor is.

Authorization

SmoothGlue Console has a fine-grained enumeration of possible user actions. Each of those user actions has corresponding application logic to determine if an actor is allowed to perform the action. The list of actions, along with their associated logic, comprises the internal Authorization Service for SmoothGlue Console.

For some user actions, SmoothGlue Console benefits from Keycloak as a redundant validation of action authorization.

Platform Tool Integration

As mentioned, SmoothGlue Console interacts with other tools in the platform using HTTP-based APIs offered by those tools.

Example Action Execution

Many actions performed by a SmoothGlue Console user trigger these integrations between SmoothGlue Console and one-or-more platform tools. The following example shows how SmoothGlue Console handles the Create User action, which can be performed by a SmoothGlue Admin. Note that each numbered step happens sequentially.

1. Create the user in Keycloak using the Keycloak Admin API.
   1. If unsuccessful, fail.
2. Create the user in the application database.
3. In parallel, create the user in each Platform Tool.
   1. If the action fails in any of the platform tools, do not fail the overarching action.
4. Respond to the client (web browser) appropriately based on success of the action.

There are no attempts to retry any failed actions at any level in the above flow. In the case of partial success, SmoothGlue Console offers some features like “Repair Organization” and “Repair User” to address partial failures (please see the User Manual).

Keycloak

As mentioned earlier, SmoothGlue Console relies on Keycloak to provide authentication via the OIDC protocol. However, SmoothGlue Console also uses Keycloak’s admin REST API to represent SmoothGlue concepts.

Concept Mapping

SmoothGlue Concept	Keycloak Concept
Organizations	Top-level groups
Roles	Subgroups with specific names
Users	Users

GitLab

SmoothGlue Console integrates with GitLab to define permissions boundaries for Organizations, Teams, and Users. GitLab’s REST API is used for this integration.

Concept Mapping

SmoothGlue Concept	GitLab Concept
Organizations	Top-level groups
Teams	Subgroups
Roles	Roles
Users	Users

Jira

In addition to user management, SmoothGlue Console uses Jira’s REST API to create Projects with proper scoping and permissions. Such Jira Project creation can be invoked in the Project Tools user experience. Note that the Jira integration supports the SmoothGlue Admin role (assigning a user that role would give them Jira admin privileges).

Concept Mapping

SmoothGlue Concept	Jira Concept
Organizations	Couplings of a User group with a Permission Scheme
Users	Users

Confluence

SmoothGlue Console implements a very minimal integration with Confluence. Confluence is only supported when Jira is deployed and Confluence must be configured to sync users from Jira. The Confluence integration supports the SmoothGlue Admin role; assigning a user the SmoothGlue Admin role gives them Confluence admin privileges.

Concept Mapping

SmoothGlue Concept	Confluence Concept
Organizations	Spaces (no automation of permissions today)

Mattermost

Concept Mapping

SmoothGlue Concept	Mattermost Concept
Organizations	Teams
Users	Users

Argo CD

Argo CD relies entirely on its configured identity provider to determine users and permissions. Therefore, Console does not need to implement any automation related to user management. SmoothGlue Console will query Argo CD for projects and applications to present to users within Console's Projects user experience. Console relies on some naming conventions for the integration to work properly.

Concept Mapping

SmoothGlue Concept	Argo CD Concept
Applications	Applications
Organizations	User groups claimed in JWT
Projects	Projects
Users	Users

Identity

SmoothGlue Console interacts with Argo CD on behalf of the authenticated actor. More specifically, SmoothGlue Console presents the current session's access token to the Argo CD REST api whenever such an interprocess communication is necessary. For this integration to work, a few things need to be configured properly in SmoothGlue's Keycloak.

1. The access token's content must include the actor's group memberships.
2. Specify that Argo CD is an intended consumer of SmoothGlue Console's access tokens.

Configuring SmoothGlue Console's Access Tokens:

1. Log in to the Keycloak Admin Console, in the smoothglue realm.
2. Click Clients in the left menu.
3. Find SmoothGlue Console's client, and click on it.
4. Click on the Client scopes tab.
5. Click on the ...-dedicated client scope in the list.
6. Click the Add mapper button, then By configuration.
7. Find Group Membership, and click on it.
8. In the Name field, enter groups.
9. In the Token Claim Name, enter groups.
10. Toggle on Full group path.
11. Confirm that Add to lightweight access token is toggled off (this should be off by default).
12. Click Save.
13. Navigate back to ...-dedicated client scope.
14. Click the Add mapper button, then By configuration.
15. Click the Audience entry in the list.
16. In the Name field, enter argocd.
17. In the Included Client Audience field, select argocd.
18. Toggle Add to ID token to On.
19. Toggle Add to access token to On.
20. Click Save.

Conventions

SmoothGlue Console currently relies on SmoothGlue Admins to create projects and applications in Argo CD by whatever means they prefer. However, some naming conventions are necessary in order to associate Argo CD projects with SmoothGlue Projects. The naming convention is as follows:

<organization name>-<project-name>

For any Argo CD project created that corresponds to a SmoothGlue project, the Argo CD project should be named by the convention above. The project name should be lowercase and kebab case, so that if we have an organization named SmoothGlue, and a project named SmoothGlue Console, the associated Argo CD project name should be:

smoothglue-smoothglue-console

This convention supports discovering and associating applications at runtime. Note that the current SmoothGlue Console user must have permission to access the relevant project within Argo CD in order to see the applications in Console.

RBAC

The following two basic policies are enabled for Argo CD:

• A global policy that gives members of the _structsureAdmins group administrative privileges in Argo CD
• A policy that gets set upon creating an Argo CD AppProject from Console, which gives read-only access to the project and applications associated with the project to members of the organization