Keycloak authentication

NKP uses Keycloak for single sign-on across all cluster services. The Nebari Operator wires Keycloak up for you, so day to day you mostly manage users and groups, not client configuration.

Single sign-on

Single sign-on is wired into every app for you.

When a pack installs, NKP reads its NebariApp and sets up its login, so it appears on the Launchpad with platform-account sign-in.

In Keycloak you manage only users and groups. Per-app auth lives in the NebariApp.

Admin access

The admin account has full control over Keycloak: create and manage users, organize them into groups, and adjust realm settings. You'll use it for the rest of this guide.

To sign in to the admin console:

1. Get the Keycloak admin credentials:

   kubectl -n keycloak get secret keycloak-admin-credentials -o json | jq '.data | map_values(@base64d)'

2. Open https://keycloak.<your-domain>/auth/admin/ and sign in with those credentials.

3. Switch the realm dropdown (top-left) from master to nebari.

Create your first user

nic does not create an end-user account, so create one before you can sign in:

1. In the nebari realm, go to Users → Add user, set a username and email, and save.
2. On the user's Credentials tab, click Set password, enter one, and uncheck Temporary.
3. Visit https://<your-domain> and sign in with the new user. You should land on the Launchpad.

Users, groups, and access

Apps can restrict access to specific groups, enforced at the gateway from each user's groups claim. To let someone into a restricted app, add them to the group it requires.

Manage this in the nebari realm:

• Groups → Create group to add a group, then assign members on the group's Members tab (or from a user's Groups tab).
• An app that doesn't restrict by group is open to any signed-in user.

Customizing per app

You can define an app's access in its NebariApp manifest instead of the console. Because the manifest is in Git, the access rules are version-controlled and reviewed like code:

spec:
  auth:
    enabled: true
    provider: keycloak
    groups:
      - data-scientists          # groups allowed to use the app
    enforceAtGateway: true       # enforce group membership at the gateway
    keycloakConfig:
      groups:
        - name: data-scientists  # create the group in the nebari realm and add members
          members:
            - alice
            - bob

• groups lists the groups allowed to use the app.
• enforceAtGateway: true blocks users outside those groups at the gateway. Without it, group membership isn't enforced.
• keycloakConfig.groups creates those groups in the nebari realm and adds the listed members.

The operator reconciles all of this on the next deploy. For one-off changes, edit groups and memberships directly in the admin console.

For all spec.auth fields, see the NebariApp configuration reference.