OIDC Setup - Metoro Documentation

Using Keycloak? Use Keycloak OIDC Setup for exact realm, client, group scope, and values settings.

Inputs

Start with the browser-facing deployment URL selected during planning. The OIDC callback URL is always: Use deploymentUrl from the hub values file. It already includes the scheme, so it can be https://... or http://.... The callback URL registered with the identity provider must match the hub values file exactly. You also need administrator access to the identity provider, the groups that should map to Metoro roles, and the namespace where the hub will be installed. Use metoro-hub unless your installation intentionally uses a different namespace.

Create The Client

Create a new OIDC application or client for Metoro in your identity provider. Use a confidential web application, authorization code flow, and a client secret. Do not configure implicit flow unless your provider requires it for a separate policy reason. Set the allowed redirect URI to the callback URL above. If your provider asks for allowed web origins, login URL, or post-login redirect origins, use the deployment URL without a path. Request these scopes:

openid profile email groups

Record the issuer URL, client ID, and generated client secret. The issuer URL must be reachable from browsers and from hub pods. If the issuer uses private PKI, prepare the trusted CA ConfigMap before installing.

Expose Groups

Configure the provider to include group membership in the ID token or userinfo response. The default claim name expected by the chart is groups. Use the exact group strings emitted by the provider. If the provider emits full paths such as /metoro-admins, use those full paths in the role mapping. If it emits simple names such as metoro-admins, map those exact names instead.

Map Groups To Roles

Metoro uses group-to-role mappings to grant access after login. A typical first deployment has an administrator group and a standard user group:

auth:
  oidc:
    groupRoleMappings:
      - oidcGroup: "/metoro-admins"
        metoroRole: "default-metoro-admin"
      - oidcGroup: "/metoro-users"
        metoroRole: "default-metoro-user"

Only users whose token contains a mapped group can receive access. Add at least one operator to the administrator group before the first OIDC login test.

Map Groups Declaratively With MetoroGroup CRDs

As an alternative (or in addition) to the static groupRoleMappings above, groups declared as MetoroGroup Kubernetes resources on the hub cluster can carry their own OIDC mappings via spec.oidcMappings:

apiVersion: rbac.metoro.io/v1alpha1
kind: MetoroGroup
metadata:
  name: sre-team
spec:
  oidcMappings:
    - /sre

At login, a user is granted access if either source matches: a groupRoleMappings entry or a MetoroGroup’s spec.oidcMappings. The union of all matched groups is assigned. If neither matches any of the user’s OIDC groups, access is denied and any previously IdP-assigned memberships are removed. Unlike groupRoleMappings, CRD mappings take effect without redeploying the hub — edits to MetoroGroup resources are synced automatically within about a minute and apply at the user’s next login. Notes:

The same exact-string matching applies: use the full group strings emitted by the provider, and matching is case-sensitive.
When all mappings are managed through CRDs, groupRoleMappings may be an empty list.
CRD mappings apply to the on-prem default organization; they require OIDC_ORGANIZATION_UUID to be the default on-prem organization, which is the standard on-prem setup.

​Inputs

​Create The Client

​Expose Groups

​Map Groups To Roles

​Map Groups Declaratively With MetoroGroup CRDs

Inputs

Create The Client

Expose Groups

Map Groups To Roles

Map Groups Declaratively With MetoroGroup CRDs