User Management

StackState for Kubernetes troubleshooting

Users of the SaaS tenants (StackState instances) are managed with Keycloak. Each customer (tenant) has a dedicated Keycloak realm. A link to the Keycloak console is sent in the welcome message when a user is created.

There are two levels of user management permissions: Basic (default) and Advanced.

Basic (default): Allows users to add new users and add them to Keycloak groups.
Advanced: Allows users to manage an entire Keycloak realm (configuring Identity Providers, Authentication/Authorization options, etc.). Available for Enterprise Edition only.

All SaaS tenants start with Basic mode. Paid customers can request an upgrade to Advanced mode by filing a support ticket to [email protected]. Users who are members of the realm-admin Keycloak group receive a link to the Keycloak Admin Console in the welcome message.

StackState redirects users to Keycloak for authentication. Users are expected to be members of one or more Keycloak groups.

The predefined Keycloak groups:

realm-admin: Members of this group can log in to the Keycloak realm console and perform operations allowed by their user management mode (Basic or Advanced).
stackstate-k8s-troubleshooter: Users in this group are assigned the stackstate-k8s-troubleshooter Keycloak client role, which maps to the StackState role with the same name. The role grants regular StackState permissions.
stackstate-k8s-admin: Users in this group are assigned the stackstate-k8s-admin Keycloak client role, which maps to the StackState role with the same name. The role grants privileged StackState permissions.

Basic user management

Manage users

In the left-hand menu, select Users under the Manage section.

Adding a new user

To add a new user click the Add user button. Enter the necessary user information (Username, Email, First Name, Last Name).

leave Required users actions empty.
add the user to the required groups.
click Save. The welcome message with the sign-up link and the links to the SaaS tenant, Keycloak Admin and Account consoles are emailed to the user.
To activate the account, which includes email confirmation and the password reset, the user must follow the sign-up link.

Updating user details

To edit user details, select the user by clicking on Username.

Change the details as needed.
Set one or more Required user actions, for example, to force users to update password or configure one time passwords.
Press Save button when done.

Deleting a user

To delete one or more users, select the required users and press Delete user button.

Group membership

Log in to the Keycloak Admin Console.
In the Groups section, search for the group you want to manage.
Click on the group name to open group details and go to the Members tab.
To add a new group member, press the Add Member button and select the required users.
To delete users from the group, select the users from the list, then from the menu that at the same line as the Add member button marked as "⋮", select Leave group.

Advanced user management

In Advanced User Management, users have full administrative permissions within their Keycloak realm. They can configure authentication, authorization, external identity providers, and more.

Refer to the official Keycloak documentation for more details.

A Keycloak realm comes with the initial configuration:

An OIDC client integrated with a SaaS tenant.
- A set of Keycloak client roles that map to StackState built-in roles.
  - stackstate-k8s-troubleshooter
  - stackstate-k8s-admin
A realm role to manage the Keycloak realm, realm-admin.
A set of Keycloak Groups with corresponding Keycloak client and realm roles assigned:
- realm-admin
- stackstate-k8s-troubleshooter
- stackstate-k8s-admin
SMTP server configuration to send email notifications generated by Keycloak.
A custom eventListener, stackstate-user-creation, which is responsible for generating a welcome message to new users.

Please avoid modifying the mentioned resources and the default realm's clients, since it might require resetting the Keycloak realm configuration.

Example: Using Azure Active Directory as an identity provider

⚠️ This guide is applicable for the Advanced User Management only.

Prerequisites

The user must be a member of the realm-admin Keycloak group.
Permissions to create App registrations in the Azure portal.
An ID of the Active Directory group to grant permissions to StackState. (found in the Groups section of the Azure portal).

Creating an app registration in Azure

Log in to the Azure portal and proceed to App registrations
Press New registration, fill in the name of the registration, select Accounts in this organizational directory only and leave all other fields as is.

Note the Application (client) ID for the created app registration; it will be used later to configure a Keycloak Identity Provider. The value of the secret is shown only once just after creation.
Press Add a certificate or secret and create a client secret. Note the value for the created secret; it will be used later to configure a Keycloak Identity Provider.

From the App registration page go to Endpoints and note the OpenID Connect metadata document link; it will be used later to configure a Keycloak Identity Provider.

Go to the Manifest section and ensure that the groupMembershipClaims setting of the App registration is set to All. This is required to map Active Directory Groups to the Keycloak Groups/Roles.

Adding an identity provider to Keycloak

Log in to the Keycloak Admin console.
In the left-hand menu, select Identity providers under the Configure section.
Choose OpenID Connect v1.0.
Fill in the Display name as required, and input the Client ID, Client Secret, and Discovery endpoint with the data from the App registration notes.

Note Redirect URI, which is needed to complete the App registration.
Press Add.
Scroll to the bottom the page and set Sync mode to Force.
Click Save to finalize the provider configuration.

Finalizing app registration

Return to the App Registration section of the Azure portal and click Add a Redirect URI

Click Add a platform and select Web from the right-hand frame.
Enter the Redirect URI from the Keycloak Identity Provider's configuration and click Configure.

Verifying Keycloak identity provider

Open your tenant URL in a browser. The Login page should now include an option to sign in with the configured IdentityProvider. If you have already logged into the tenant you must log out first.

Sign in with Azure Identity Provider.
If everything is configured correctly you should be logged into the tenant with the default StackState role, stackstate-guest.

Mapping Active Directory role to StackState role

This guide assumes an Azure Identity Provider was added as described earlier.

Log in to the Keycloak Admin console.
In the left-hand menu, select Identity providers under the Configure section and choose the Azure Identity Provider.
Navigate to the Mappers tab and press Add mapper.
Fill in the details as shown in the screenshot. For the Claim Value use the ID (⚠️ not a name) of the Active Directory Group.

Click Save to store the mapper settings.
Log in to the StackState tenant to verify if the stackstate-k8s-troubleshooter StackState role has been granted to your user. You should see additional items in the menu such as Monitors, Stackpacks, etc.

PreviousIngestion API Keys NextStackState Query Language (STQL)

Last updated 1 year ago