> ## Documentation Index
> Fetch the complete documentation index at: https://metoro.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# OIDC Setup

> Provision an OIDC client, group claims, role mappings, and the client Secret before installing Metoro

export const usePlannerSelections = () => {
  const [selections, setSelections] = useState(defaultSelections);
  useEffect(() => {
    setSelections(readSelections());
    const handleChange = event => {
      setSelections({
        ...defaultSelections,
        ...event.detail
      });
    };
    window.addEventListener(eventName, handleChange);
    return () => window.removeEventListener(eventName, handleChange);
  }, []);
  return [selections, setSelections];
};

export const storageKey = "metoro-onprem-installation-planner-v1";

export const readSelections = () => {
  if (typeof window === "undefined") {
    return defaultSelections;
  }
  try {
    const stored = window.localStorage.getItem(storageKey);
    if (!stored) {
      return defaultSelections;
    }
    return {
      ...defaultSelections,
      ...JSON.parse(stored)
    };
  } catch {
    return defaultSelections;
  }
};

export const oidcCallbackUrl = selections => {
  return `${deploymentUrl(selections)}/api/v1/auth/oidc/callback`;
};

export const eventName = "metoro-onprem-installation-planner-change";

export const deploymentUrl = selections => {
  return `${deploymentScheme(selections)}://${deploymentHostname(selections)}`;
};

export const deploymentScheme = selections => {
  return selections.urlScheme === "http" ? "http" : "https";
};

export const deploymentHostname = selections => {
  return cleanHostname(selections.deploymentHostname) || "CHANGE_ME_METORO_HOSTNAME";
};

export const defaultSelections = {
  topology: "dedicated",
  network: "sharedHost",
  urlScheme: "https",
  tls: "publicCa",
  authentication: "oidcGroups",
  dependencies: "bundled",
  clickhouseStorage: "hotPvcObjectStorage",
  deploymentHostname: "",
  ingesterHostname: ""
};

export const cleanHostname = value => {
  return String(value || "").trim().replace(/^https?:\/\//, "").replace(/\/.*$/, "");
};

export const OidcValuesSnippet = () => {
  const [selections] = usePlannerSelections();
  const values = ["auth:", "  oidc:", "    enabled: true", "    displayName: OIDC", '    issuerUrl: "https://CHANGE_ME_IDP/realms/CHANGE_ME_REALM"', "    clientId: metoro", "    clientSecretName: metoro-oidc-client-secret", "    clientSecretKey: client-secret", "    organizationUUID: default-on-prem", `    redirectUrl: "${oidcCallbackUrl(selections)}"`, "    groupsClaim: groups", "    emailClaim: email", "    nameClaim: name", '    scopes: "openid profile email groups"', "    groupRoleMappings:", '      - oidcGroup: "/metoro-admins"', '        metoroRole: "default-metoro-admin"', '      - oidcGroup: "/metoro-users"', '        metoroRole: "default-metoro-user"'].join("\n");
  return <pre>
      <code>{values}</code>
    </pre>;
};

export const OidcCallbackUrl = () => {
  const [selections] = usePlannerSelections();
  return <pre>
      <code>{oidcCallbackUrl(selections)}</code>
    </pre>;
};

<Info>
  Using Keycloak? Use [Keycloak OIDC Setup](/docs/on-premises/10.x/installation/oidc-keycloak) for exact realm, client, group scope, and values settings.
</Info>

## Inputs

Start with the browser-facing deployment URL selected during planning. The OIDC callback URL is always:

<OidcCallbackUrl />

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:

```text theme={null}
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:

```yaml theme={null}
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](/docs/user-management/kubernetes-crds#metorogroup) on the hub cluster can carry their own OIDC mappings via `spec.oidcMappings`:

```yaml theme={null}
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.