For the complete documentation index, see llms.txt. Markdown versions of all docs pages are available by appending .md to any docs URL.

Review how the Solo UI authenticates users with an OpenID Connect identity provider, and how it maps user groups to roles.

About

The Solo UI authenticates every user through an OpenID Connect (OIDC) identity provider (IdP). You have the following provider choices.

An external OIDC provider gives you the following capabilities.

• Single sign-on: Users log in to the Solo UI with the credentials that you already manage in your IdP.
• Role-based access control: The Solo UI reads a group claim from the access token and maps those groups to the global.Admin, global.Writer, and global.Reader roles.
• Token expiry and refresh: You control how long an access token stays valid, and the UI refreshes it with a refresh token.

How the Solo UI selects the provider

The oidc.issuer Helm value in the management chart selects the provider.

Because the setting is a single value, you switch from the auto provider to your own IdP by upgrading the management chart, and you switch back by setting oidc.issuer to an empty string again.

Authentication and authorization flow

The following diagram shows how your IdP, the UI frontend, and the UI backend interact when a user logs in and then calls a Solo UI API. Follow the arrows from the User at the top to see which component holds the token at each stage.

    sequenceDiagram
    participant U as User
    participant F as UI frontend
    participant I as Your IdP
    participant B as UI backend

    Note over U,B: Authentication
    U->>F: 1. Open the Solo UI
    F->>I: 2. Redirect to the IdP login page
    U->>I: 3. Enter credentials
    I->>F: 4. Return an authorization code
    F->>I: 5. Exchange the code for tokens (PKCE)
    I->>F: 6. Return an access token and a refresh token

    Note over U,B: Authorization
    F->>B: 7. Call the API with the access token
    B->>B: 8. Validate the token and read the group claim
    B->>B: 9. Map groups to roles with the RBAC ConfigMap
    B->>F: 10. Return the API response, or deny the request

    Note over U,B: Token refresh
    F->>I: 11. Exchange the refresh token for a new access token
  

Read the flow in three stages.

• Authentication, steps 1 to 6. The UI frontend redirects the user to your IdP. Because the frontend is a public client, it uses the Proof Key for Code Exchange (PKCE) flow to exchange the authorization code for tokens, which avoids holding a client secret in the browser.
• Authorization, steps 7 to 10. The UI backend validates the access token and reads the group claim from it. The backend maps those groups to Solo UI roles, then allows or denies the request.
• Token refresh, step 11. When the access token expires, the frontend exchanges the refresh token for a new access token, and the user stays logged in.

Role-based access control

The UI backend maps groups from the access token to Solo UI roles. The management chart writes the mapping to the rbac-config-management ConfigMap in the namespace where you install the chart.

The following snippet shows the default configuration of the ConfigMap.

apiVersion: v1
kind: ConfigMap
metadata:
  name: rbac-config-management
  namespace: solo-enterprise
data:
  config: |
    {
      "roleMapper": "has(claims.Groups) ? claims.Groups.transformList(i, v, v in rolesMap, rolesMap[v]) : []",
      "roleMappings": {"admins":"global.Admin","readers":"global.Reader","writers":"global.Writer"},
      "defaultRoles": ["global.Authenticated"]
    }

Set the following Helm values to change the mapping.

For every available value, see the management chart reference.

Authorization modes

The rbac.mode Helm value selects how the UI backend authorizes each management API call. The default value, coarse, checks the global roles that rbac.roleMapping.roleMappings defines. The fine-grained value instead evaluates built-in catalog defaults and EnterpriseAgentgatewayRBACPolicy grants. These grants scope access to individual Solo Enterprise for agentgateway resources, including Budgets, Budget entries, HTTPRoutes, and VirtualKeys.

Fine-grained mode covers Solo Enterprise for agentgateway resources only. Istio mesh views such as the Fleet Graph, Global Services, and Dashboard keep the global role checks in both modes, so a user sees the same mesh resources either way.

When rbac.mode is set to fine-grained, the UI backend builds the policy subject from two verified JWT claims, which you can point at different claim names than the defaults.

For the policy shape and a worked example, see Fine-grained management RBAC in the Solo Enterprise for kagent documentation.

Client IDs

The Solo UI needs one OIDC client for the UI backend and one for the UI frontend, because the two components have different security requirements. The backend is a confidential client that validates tokens server-side, and the frontend is a public client that runs in the browser.

Next steps

Set up your provider with the external OIDC provider guide. The guide applies to any OIDC-compliant provider.