Docs

Identity Mapping

Connect a platform identity to a NetBox account on NetBox Enterprise, what a connection grants, and how to get back in when your SSO provider breaks

NetBox Enterprise knows who signed in through your identity provider. It does not know which NetBox account belongs to that person. Something has to connect the two, and in this release an administrator does it by hand, one user at a time.

This page covers making and undoing those connections, what a connection actually grants, and how to recover when your identity provider stops working.

Before you start

Identity mapping only exists on an install where the authorization server is running and reachable. All of these must hold, and none of them is on by default:

RequirementWhy
spec.idp.enabled is trueDeploys the bundled Keycloak identity provider
Routing is in Gateway mode, spec.gateway.enabled is true, and at least one Gateway listener names a concrete hostnameThe bundled provider is served through a Gateway listener, and the authorization server needs its sign-in address. Listeners that are all wildcards, or that declare no hostname at all, leave nothing to build that address from
The install is cluster-scopedThe bundled identity provider creates cluster-scoped roles
spec.pas.enabled is trueDeploys the authorization server that stores the connections
On external PostgreSQL, spec.pas.postgres is setThe authorization server keeps its own database. With external PostgreSQL and no spec.pas.postgres, the operator does not deploy it, and the PasDatabase condition reports NotConfigured
spec.ui.enabled is true, and spec.ui.hostname is a hostname a Gateway listener admitsThe authorization server is served only on the platform interface's hostname

If the identity provider or routing requirements are not met, the operator deploys no authorization server and reports IdentityProviderRequired on the NetBoxEnterprise resource. If the platform interface hostname is missing, the authorization server runs, but nothing routes to it and nobody can sign in.

Platform Single Sign-On covers the identity provider requirements in more detail.

Where these settings live

Set them where your install's configuration lives, not by editing the NetBoxEnterprise resource by hand. The resource is rendered from your configuration, so a hand edit either gets overwritten by the next deploy or, where the deploy applies server-side, makes that deploy fail with a field-manager conflict. Embedded Cluster deploys apply server-side. The resource's SpecManuallyEdited condition names any field edited this way and how to release it.

  • Helm: set them under netboxEnterprise.spec in your values file and run helm upgrade.

  • Embedded Cluster: set them in the Admin Console. Tick Enable the Platform UI, and set the Platform UI Hostname and the NetBox Hostname. The tick also turns on the bundled identity provider and the authorization server, unless you turned either of them off yourself. The platform hostname must be a subdomain such as ui.example.com, not a bare domain such as example.com or an IP address. It must also differ from the NetBox hostname. Put each administrator in Initial Platform Administrators, one sub per line, as described below.

    On external PostgreSQL, a database administrator must prepare the server first. The authorization server needs two roles and two databases, and the NetBox database user needs CREATEROLE. The Admin Console shows the statements under the external PostgreSQL settings.

    To script the same settings, use the KOTS config API with the items ui_enabled, ui_hostname and pas_initial_admin_subs. Run this on a controller node, from the directory that holds the installer:

    sudo ./netbox-enterprise shell -c "kubectl -n kotsadm exec deploy/kotsadm -c kotsadm -- \
      /kots set config netbox-enterprise -n kotsadm \
      ui_enabled=1 ui_hostname=<platform-hostname> --deploy"

    The same command with pas_initial_admin_subs=<sub> sets a single administrator, described below. The item takes one sub per line. To list several, write them to a config values file, for example admin-subs.yaml:

    apiVersion: kots.io/v1beta1
    kind: ConfigValues
    spec:
      values:
        pas_initial_admin_subs:
          value: |-
            <first sub>
            <second sub>

    Then pass it on standard input. The command runs inside the Admin Console's container, which cannot read a file on the node:

    sudo ./netbox-enterprise shell -c "kubectl -n kotsadm exec -i deploy/kotsadm -c kotsadm -- \
      /kots set config netbox-enterprise -n kotsadm --config-file /dev/stdin --merge --deploy" \
      < admin-subs.yaml

An Admin Console install on an existing cluster routes through Ingress rather than a Gateway, so identity mapping is not available there in this release.

Installs with no identity provider

You can use the platform without your own identity provider. People then sign in with local accounts in the bundled Keycloak. NetBox Enterprise creates no such account, and people cannot register themselves, so a cluster administrator creates each account.

  1. Open the Keycloak admin console. Follow Read the break-glass Keycloak administrator for the credentials and the port-forward.
  2. Select the netbox realm. Do not create people in the master realm: it holds the console's own administrator.
  3. Open Users and add a user. Fill in the username, email, first name and last name. The realm requires all four.
  4. On the user's Credentials tab, set a password. Keep Temporary on, so that the person sets a new password at first sign-in.
  5. To make the person a platform administrator, copy the user's ID from the Details tab into the initial administrators. See Who can administer connections.

People sign in on the platform interface hostname with their username or email and that password. Then connect each person to their NetBox account, as the rest of this page describes.

Why connections are made by hand

Email cannot carry the connection on its own. NetBox treats a user's email as optional and does not require it to be unique, so an email does not reliably identify one NetBox account.

NetBox Enterprise also ships no mail server and supports air-gapped installs, so there is no emailed invitation to fall back on. Every connection is made deliberately by an administrator.

What a connection grants

A connection grants two things:

  • Platform interface access to that NetBox. The platform reaches a NetBox instance only for people connected to an account there. For anyone else, that instance's data stays out of reach in the platform interface.
  • NetBox sign-on for API requests. The platform signs the person on to NetBox's REST API as the connected account, so every request it makes for them runs as that NetBox user.

It is not a NetBox web interface sign-on. Someone with a connection still signs in to the NetBox web interface the way they always did.

What the person may do once authenticated is unchanged: NetBox's own groups and object permissions decide that, exactly as for a session login.

Who can administer connections

There is no administrator until you name one, and a fresh install has none. The authorization server promotes the identity-provider sub claims listed in spec.pas.initialAdminSubs, which is empty by default and deliberately carries no default value — a default there would be an administrator grant landing on every install. Leave it empty and nothing on this page works: people sign in to the platform successfully, and every administrative action is refused.

Know these before you set the field:

  • Each value is a user's ID in the bundled Keycloak's netbox realm, not the subject your corporate provider issues. Find it in the Keycloak admin console under Users, on the user's Details tab. Someone who signs in through your corporate provider gets a Keycloak user, and so an ID, at their first sign-in. A value that matches no user is still granted administrator and logged as a success, to a platform user nobody can sign in as, so copy the ID rather than typing it.
  • On Helm, set netboxEnterprise.spec.pas.initialAdminSubs in your values. On Embedded Cluster, set Initial Platform Administrators in the Admin Console, one sub per line. See Where these settings live.
  • Promotion runs when the authorization server starts, not at first login. Saving the field re-runs the server's database migration and then restarts it, so the change lands once the new pod is ready rather than at once.
  • A sub containing a comma is silently dropped: no error, event, or log line reports it. The list reaches the authorization server as comma-separated text, so passing it through would split one subject into two. If someone you listed was never promoted, check their sub for a comma.
  • An administrator promoted this way is protected while their sub stays in the list: the platform interface and the API refuse to deactivate them or change their role. Disabling their account in the bundled Keycloak still deactivates them. See Deactivate and reactivate access.

Removing an administrator

Removing a sub from the list removes the protection, not the administrator role. Nothing revokes a role automatically. To take administrator access away from someone promoted this way:

  1. Confirm another administrator can still sign in. Nothing stops you demoting the last one, and an install with none can only get one back through the sub list and a restart.
  2. Remove their sub from the list and wait for the authorization server to restart.
  3. Deactivate them, or change their role to Viewer through the API. See Change a platform role.

Managing connections in the platform interface

Administrators manage people and their NetBox accounts under Settings in the platform interface:

  • Users lists platform users by status: Active (shown first), Deactivated, or Pending. From here you connect a person to NetBox accounts, deactivate or reactivate them, and rescind a pending invite.
  • User mapping lists the NetBox accounts in every connected environment, one row per account, filtered by All, Linked, or Unlinked. From here you connect an account to a platform user, remove a connection, and invite someone who has not signed in yet.

Both tabs appear once the authorization server is running and the platform interface has a hostname, and they replace the Administrators tab. Every signed-in user sees the tabs, but only an administrator can open them. Anyone else sees "You do not have access to this page".

Do not use Invite user(s) on the Users tab. It depends on a NetBox Labs cloud service that is not part of a NetBox Enterprise install, and it does not create a pending user. Invite people from User mapping instead. See Connecting someone who has not signed in yet.

Working in User mapping

  • To connect an account, pick a platform user in its Link Platform user column. The account whose email matches is suggested first, but nothing is picked for you. To remove a connection, pick Not linked.
  • The picker lists only active platform users. Pending and deactivated users do not appear in it.
  • Changes are not saved as you make them. Select Save changes at the bottom of the page to apply them, or Cancel to discard them. Leaving the page discards unsaved changes.
  • Changes are applied one at a time. If one fails, the changes before it are kept and the rest are not applied.

Connecting someone who has not signed in yet

On User mapping, find the person's NetBox account and select the invite button (the paper plane) on its row, then select Save changes. The platform connects that NetBox account to the account's email address. The NetBox account must have an email address, and it must be the address the person signs in with.

What happens next depends on whether the bundled Keycloak already has an account with that email:

  • If it has, the person is added as an ordinary platform user straight away, even if they have never signed in to the platform.
  • If it has not, the person is added as a pending user. Their connections carry a pending flag.

A pending user stops being pending when someone first signs in with that email, or when an administrator opens the Users or User mapping tab after a Keycloak account with that email exists.

Nothing is sent to the person: NetBox Enterprise has no mail server. Tell them to sign in.

This means you can prepare connections ahead of an onboarding date rather than waiting for each person to sign in first.

Warning: A pending user is claimed by whoever first signs in with that email. The platform does not check whether the identity provider verified the address, and the bundled Keycloak lets people change their own email address by default. Anyone who sets their address to an invitee's would take over that invite and its connections. Before you invite anyone:

  1. In the Keycloak admin console, open the netbox realm, then Realm settings, then the User profile tab.
  2. Open the email attribute and, under Who can edit, leave only Admin. Save.

NetBox Enterprise leaves that setting alone on later reconciles. Also make sure people cannot change their own email address at your corporate provider, and pre-create connections only for addresses that provider controls.

Deactivate and reactivate access

Deactivating a person turns off their platform access without deleting their connections, and ends their platform sessions. Prefer it to deleting a connection when someone is on leave or their access is under review, because reactivating is then one action rather than a rebuild.

A NetBox API token already issued on their behalf stays valid until it expires, which takes up to 60 seconds. The same applies when you remove a connection.

A pending user has no Deactivate action. Their row offers Rescind invite instead, which deletes the pending user together with their connections.

Disabling someone's account in the bundled Keycloak also deactivates them here, including an administrator protected by spec.pas.initialAdminSubs. The operator looks for disabled accounts on each reconcile pass, every 300 seconds unless spec.reconcileInterval sets another value, so a disabled account is normally deactivated within one interval. That is the best case, not a guarantee: a pass is skipped while Keycloak is unhealthy, at most 25 accounts are deactivated per pass, and a failed attempt is retried on later passes.

Disabling someone at your corporate identity provider does not deactivate them here. Their account in the bundled Keycloak stays enabled, so nothing is deactivated, and their existing platform session keeps working for up to 24 hours, or 1 hour if idle. When someone leaves, deactivate them here, or also disable their account in the bundled Keycloak. Deactivate them here whenever access has to stop at once.

The sync runs one way only. Enabling the account again in Keycloak does not restore platform access; reactivate them here. Reactivating someone here whose Keycloak account is still disabled sticks: the operator does not deactivate them again.

Two kinds of disabled account are not deactivated automatically:

  • An account with no email address. The operator has no way to name the person to the platform. Deactivate them here, or give them an email address in Keycloak.
  • An account locked by Keycloak's brute-force protection. Failed logins alone must not revoke someone's access, so the operator leaves these accounts alone. Clear the lockout in Keycloak, and deactivate the person here if the lockout was intended.

Accounts with no email address, and accounts whose deactivation failed three times, are reported in a PasSuspensionIncomplete warning event on the NetBoxEnterprise resource. The event lists Keycloak user ids, not emails or usernames. It names up to ten and counts the rest. Look each id up in the Keycloak admin console under Users.

Scripting connections through the API

Everything the two tabs do is also available from the authorization server's API, served on the same hostname as the platform interface. Use it to script a bulk onboarding.

The examples need the NetBox and platform hostnames to serve a certificate the machine running them trusts. An install still on its default certificate serves a self-signed placeholder, which curl refuses. Install a certificate that covers both hostnames first: see Default certificate behavior.

The API is Connect RPC rather than REST, so each call is a POST to a procedure path of the form /{package}.{Service}/{Method}, and every call must send the header Connect-Protocol-Version: 1. Without it the server answers 400.

Only the authorization server's own service paths reach it. Any other path on that hostname is served by the platform interface, so a POST to a REST-shaped or misspelled service path comes back 405 Not Allowed rather than an API error, and a GET returns the interface's HTML with a 200. A misspelled method under the correct service path does reach the authorization server and returns 404.

The service is:

netboxlabs.platform_authorization.admin_ui.v1.AdminUiService

so the full base is https://<your-platform-hostname>/netboxlabs.platform_authorization.admin_ui.v1.AdminUiService/.

Getting a token

Calls carry up to two tokens from the same administrator sign-in:

HeaderValue
Authorization: Bearer <platform identity token>Issued by the authorization server in exchange for your Keycloak ID token. It lasts 60 seconds
X-Forwarded-User-Token: <Keycloak access token>Your Keycloak access token from the same sign-in. CreateLink and ListNetBoxInstances refuse a request without it

The account must be a platform administrator. Anyone else gets permission_denied.

The platform's Keycloak client, platform, supports only the browser sign-in flow: an authorization code with PKCE. It has no password grant and no service account. A script gets its tokens by driving that sign-in against a local Keycloak account in the netbox realm, so create a local account for scripting, sign it in once, and give it the administrator role with Change a platform role using PLATFORM_ROLE_ADMIN. Do not list it in spec.pas.initialAdminSubs: an account listed there cannot be deactivated or demoted while it stays listed. An account that signs in only through your corporate provider cannot be scripted this way.

Changing a role needs an administrator's token, and only a local account can get one. If no local account is an administrator yet, list the scripting account in spec.pas.initialAdminSubs once, wait for the authorization server to restart, then remove it from the list. It keeps the administrator role and loses only the protection, as Removing an administrator describes.

Keycloak is served on the NetBox hostname under /sso. The redirect URI must be the platform interface's origin, exactly. Run the script in bash. On macOS, start bash first: zsh, the default shell there, runs pasted # comment lines as commands. Run this first, and type the password at the prompt:

NB=https://<your-netbox-hostname>
UI=https://<your-platform-hostname>
KC_USER=<local administrator username>
printf 'Password for %s: ' "$KC_USER"; IFS= read -rs PASS; echo

Run the prompt on its own. Pasted together with the lines after it, it takes the next line as the password, and the password you then type runs as a command and lands in your shell history. Then run:

# The cookie jar holds a session that can mint new tokens. The trap deletes it when this shell exits.
JAR=$(mktemp)
trap 'rm -f "$JAR"' EXIT
VERIFIER=$(python3 -c 'import secrets,base64; print(base64.urlsafe_b64encode(secrets.token_bytes(40)).decode().rstrip("="))')
CHALLENGE=$(python3 -c 'import hashlib,base64,sys; print(base64.urlsafe_b64encode(hashlib.sha256(sys.argv[1].encode()).digest()).decode().rstrip("="))' "$VERIFIER")

# 1. Open the sign-in page and read the form's action URL.
FORM=$(curl -s -c "$JAR" "$NB/sso/realms/netbox/protocol/openid-connect/auth?client_id=platform&response_type=code&scope=openid&redirect_uri=$UI&code_challenge=$CHALLENGE&code_challenge_method=S256&state=script" \
  | grep -oE 'action="[^"]*"' | head -1 | sed 's/action="//;s/"$//' \
  | python3 -c 'import sys,html; print(html.unescape(sys.stdin.read().strip()))')

# 2. Submit the credentials. The authorization code comes back in the redirect.
CODE=$(printf %s "$PASS" | curl -s -b "$JAR" -c "$JAR" -o /dev/null -D - -X POST "$FORM" \
    --data-urlencode "username=$KC_USER" --data-urlencode password@- \
  | tr -d '\r' | sed -n 's/^[Ll]ocation: .*[?&]code=\([^&]*\).*/\1/p')
unset PASS
[ -n "$CODE" ] || echo "Sign-in failed: check the username and password." >&2

# 3. Redeem the code. Keep both tokens.
TOKENS=$(curl -s -X POST "$NB/sso/realms/netbox/protocol/openid-connect/token" \
  -d grant_type=authorization_code -d client_id=platform -d "code=$CODE" \
  -d "redirect_uri=$UI" -d "code_verifier=$VERIFIER")
ID_TOKEN=$(echo "$TOKENS" | python3 -c 'import json,sys; print(json.load(sys.stdin)["id_token"])')
ACCESS_TOKEN=$(echo "$TOKENS" | python3 -c 'import json,sys; print(json.load(sys.stdin)["access_token"])')

# 4. Exchange the ID token for a platform identity token.
PIT=$(curl -s -c "$JAR" -X POST "$UI/netboxlabs.platform_authorization.tokens.v1.TokensService/Exchange" \
  -H "Authorization: Bearer $ID_TOKEN" -H "Content-Type: application/json" \
  -H "Connect-Protocol-Version: 1" -d '{}' \
  | python3 -c 'import json,sys; print(json.load(sys.stdin)["platformIdentityToken"])')

Exchange the ID token. The access token is refused there with unauthenticated, and only belongs in the X-Forwarded-User-Token header.

The platform identity token expires after 60 seconds, so do not cache it across a long script. Get a fresh one before each call or short group of calls. The exchange also sets a session cookie, and TokensService/Refresh returns a new platform identity token from that cookie alone, for up to an hour idle and 24 hours in all:

PIT=$(curl -s -b "$JAR" -X POST "$UI/netboxlabs.platform_authorization.tokens.v1.TokensService/Refresh" \
  -H "Content-Type: application/json" -H "Connect-Protocol-Version: 1" -d '{}' \
  | python3 -c 'import json,sys; print(json.load(sys.stdin)["platformIdentityToken"])')

The examples below use the UI, PIT, and ACCESS_TOKEN variables the script set, so you never paste a token into the shell.

Find the NetBox instance id

CreateLink names the NetBox instance by its id, not its URL. ListNetBoxInstances returns it:

curl -X POST \
  "$UI/netboxlabs.platform_authorization.admin_ui.v1.AdminUiService/ListNetBoxInstances" \
  -H "Authorization: Bearer $PIT" \
  -H "X-Forwarded-User-Token: $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Connect-Protocol-Version: 1" \
  -d '{}'

On NetBox Enterprise the id is <name of your NetBoxEnterprise resource>-netbox. It is compared exactly.

Find the NetBox user id

The NetBox account is named by its numeric id, not its username. ListNetBoxUsers looks it up, with an optional username_filter or email_filter:

curl -X POST \
  "$UI/netboxlabs.platform_authorization.admin_ui.v1.AdminUiService/ListNetBoxUsers" \
  -H "Authorization: Bearer $PIT" \
  -H "Content-Type: application/json" \
  -H "Connect-Protocol-Version: 1" \
  -d '{"netbox_instance": "<instance id>", "username_filter": "jsmith"}'

You can also read the id from the NetBox admin interface, or from GET /api/users/users/?username=<name> on the NetBox instance itself.

Create a connection

CreateLink takes three values:

FieldWhat it is
emailThe person on the platform side. An email no Keycloak account holds creates a pending user
netbox_instanceThe NetBox instance id from ListNetBoxInstances
netbox_user_idThe NetBox account's numeric user id. The account must exist and be active on that instance
curl -X POST \
  "$UI/netboxlabs.platform_authorization.admin_ui.v1.AdminUiService/CreateLink" \
  -H "Authorization: Bearer $PIT" \
  -H "X-Forwarded-User-Token: $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Connect-Protocol-Version: 1" \
  -d '{
        "email": "person@example.com",
        "netbox_instance": "<instance id>",
        "netbox_user_id": 42
      }'
ResponseCause
not_found, "netbox_instance not found"netbox_instance is not the instance id. Use the value from ListNetBoxInstances
not_found, "netbox user not found or inactive on instance"No active NetBox account has that id
not_found, "no user found for email in this org"The email belongs to a platform user outside your organization
already_exists, "user or netbox account is already linked on this instance"That person or that NetBox account already has a connection on this instance. Remove the old one first
invalid_argument, "missing X-Forwarded-User-Token"The Keycloak access token header was not sent
failed_precondition, "platform cannot read this environment"The platform cannot read NetBox as the NetBox Enterprise superuser. CheckSuperusers diagnoses it
failed_precondition, "forwarded token is for a different organization"The Keycloak access token is from a sign-in to another organization, usually a stale session. Sign in again
permission_deniedThe caller is not a platform administrator

Read the existing connections

ListLinks returns the connections in your organization, each with the platform user's id (pas_user_id) and its pending flag. Read the flag from here rather than assuming a new connection is already live.

Remove a connection

DeleteLink removes one connection, identified by the platform user's id (pas_user_id) and the NetBox instance. Use it when the wrong NetBox account was connected.

Deactivate and reactivate people

BatchDeactivateUsers and BatchReactivateUsers each take a list of platform user ids (pas_user_ids) and behave as described in Deactivate and reactivate access. Both follow these rules:

  • A call takes at most 10 ids, with no duplicates.
  • A call applies to all of its ids or to none. If one id is unknown, the call fails with not_found and nothing changes.
  • BatchDeactivateUsers refuses your own id (failed_precondition) and any administrator protected by spec.pas.initialAdminSubs (permission_denied). On a pending user it rescinds the invite.
  • BatchReactivateUsers refuses a pending user (failed_precondition), because there is nothing to reactivate.

Change a platform role

BatchUpsertPendingUsers sets the platform role for each email it is given, and also changes the role of an existing user. To remove someone's administrator access, send their email with the Viewer role:

curl -X POST \
  "$UI/netboxlabs.platform_authorization.admin_ui.v1.AdminUiService/BatchUpsertPendingUsers" \
  -H "Authorization: Bearer $PIT" \
  -H "Content-Type: application/json" \
  -H "Connect-Protocol-Version: 1" \
  -d '{"users": [{"email": "person@example.com", "platform_role": "PLATFORM_ROLE_VIEWER"}]}'

An administrator protected by spec.pas.initialAdminSubs is refused with permission_denied.

An email that matches nobody is not an error: the call creates a new pending user with that role and succeeds. Check that each email in the response is the one you meant. If a typo created a pending user, rescind it by the id in the response.

People who cannot be connected

CreateLink identifies the person only by email, so a platform user whose Keycloak account has no email address cannot be connected. Give the account an email address in Keycloak first: the connection then attaches to the person's existing platform user.

Do not connect such a person under some other email address. An email no Keycloak account holds creates a separate pending user, and the first person to sign in with that email gets the connection.

Recovering when your identity provider breaks

Two separate things protect an install whose SSO has stopped working. They are easy to confuse because both get called "the local administrator", so they are named apart here.

Why a broken provider does not lock you out

A broken provider leaves the realm's own username-and-password form working beside it: see What is managed, and what is left alone. That keeps the login path, not an account to use it with. NetBox Enterprise does not create any local account in that realm. If you want a local fallback account there, create one deliberately, before you need it.

Read the break-glass Keycloak administrator

Separately, NetBox Enterprise generates a Keycloak administrator for the admin console itself when the bundled Keycloak first deploys, and stores it in a secret named <cluster>-keycloak-admin:

kubectl -n <namespace> get secret <cluster>-keycloak-admin \
  -o jsonpath='{.data.username}' | base64 -d; echo
kubectl -n <namespace> get secret <cluster>-keycloak-admin \
  -o jsonpath='{.data.password}' | base64 -d; echo

The admin console is not reachable through your public hostname: the gateway refuses /sso/admin and the master realm. Port-forwarding to the Keycloak service is the only way in. The service exposes two ports. Use 8443, which serves HTTPS; 9000 serves health checks and metrics only.

Opening the console in a browser takes one extra step. The console builds its sign-in addresses from the NetBox hostname, so https://localhost:<port>/sso/admin/ redirects you to the public hostname, where the gateway refuses it. Make the NetBox hostname point at the forward instead:

  1. On the machine running the browser, add a hosts-file entry that maps the NetBox hostname to the local machine:

    127.0.0.1  <netbox-hostname>
  2. Forward local port 443 to the service. Binding a port below 1024 needs administrator rights on most systems, and sudo does not read your own kubeconfig, so name it:

    sudo kubectl --kubeconfig "$HOME/.kube/config" -n <namespace> \
      port-forward svc/<cluster>-keycloak-service 443:8443

    On Embedded Cluster, kubectl runs on a controller node, so the forward listens on that node. Run it there on port 8443 instead, from sudo ./netbox-enterprise shell, and tunnel it to the machine running the browser. sudo drops your SSH agent unless told to keep it:

    sudo --preserve-env=SSH_AUTH_SOCK ssh -L 443:127.0.0.1:8443 <user>@<controller-node>
  3. Open https://<netbox-hostname>/sso/admin/ and sign in with the credentials above. The certificate is issued for in-cluster use, so expect a browser warning.

  4. Remove the hosts-file entry when you are done. While it is in place, that machine cannot reach NetBox through the gateway.

The bundled realm is named netbox.

Rotate the break-glass administrator

The secret is written once and is never overwritten afterwards, which is what makes rotation safe: a password you change is not reset on the next reconcile.

  1. Change the password in the Keycloak admin console, for the admin user in the master realm, not the netbox realm the rest of this page uses. Do not delete or rename the admin user, even though Keycloak suggests replacing it: NetBox Enterprise signs in with that username.

  2. Update the stored copy so it still matches. On Embedded Cluster, run both blocks below from sudo ./netbox-enterprise shell. Elsewhere, do not put sudo in front of this kubectl: it then fails with unable to read patch file, because sudo does not pass the <(...) file on.

    Run the prompt on its own, for the reason given in Getting a token, and type the new password:

    printf 'New password: '; IFS= read -rs NEW_PASSWORD; echo

    Then patch the Secret. The password goes in base64-encoded, so no character in it can change the patch. This changes nothing if the password is empty:

    if [ -n "$NEW_PASSWORD" ]; then
      kubectl -n <namespace> patch secret <cluster>-keycloak-admin --type merge \
        --patch-file <(printf '{"data":{"password":"%s"}}' "$(printf %s "$NEW_PASSWORD" | base64 | tr -d '\n')")
    fi
    unset NEW_PASSWORD

    Keycloak restarts about a minute after the Secret is saved, and refuses sign-in for about 30 seconds while it does. The restart ends the port-forward you opened for the admin console. Before the next step, wait until this shows the pod with a new, short age and 1/1 ready, then start the port-forward again:

    kubectl -n <namespace> get pod <cluster>-keycloak-0

    Keep this copy in sync. NetBox Enterprise falls back to this credential when its own service account in Keycloak is missing a permission or has stopped authenticating. The common case is an upgraded install that turns on identity provider federation for the first time, where the operator uses this credential to grant itself the role federation needs. If the stored copy is stale then, federation cannot start, and the resource's IdentityProvider condition shows False with reason KeycloakAdminUnavailable. Correct the secret and the operator retries on the next reconcile.

  3. Confirm the stored copy works: read the password back from the Secret with the commands in Read the break-glass Keycloak administrator, and sign in to the admin console with it.

Rotating this password does not affect NetBox Enterprise's own day-to-day management of Keycloak, which uses a separate credential.

What this release does not do

Each of these is something administrators reasonably expect and will not find:

  • No automatic connections. Nothing is connected until an administrator saves it. The interface suggests the account whose email matches, but never picks or saves one for you.
  • No invitation email. Inviting someone creates a pending user and sends nothing. There is no mail server, and air-gapped installs are supported.
  • No second federation source. The bundled identity provider federates one OIDC provider, one SAML provider or one LDAP directory, not two at once.
  • No automatic merging of a local account with a federated one. When someone signs in through your corporate provider with the same email as an existing local account, Keycloak asks them to confirm by signing in with the local account's password. If they do, the two become one account and one platform user. If the emails differ, or they skip that step, they arrive as a second, separate platform user.
  • No NetBox web interface sign-on. A connection signs people on to NetBox's REST API, not its web interface. See What a connection grants.

On this page