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:
| Requirement | Why |
|---|---|
spec.idp.enabled is true | Deploys the bundled Keycloak identity provider |
Routing is in Gateway mode, spec.gateway.enabled is true, and at least one Gateway listener names a concrete hostname | The 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-scoped | The bundled identity provider creates cluster-scoped roles |
spec.pas.enabled is true | Deploys the authorization server that stores the connections |
On external PostgreSQL, spec.pas.postgres is set | The 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 admits | The 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.specin your values file and runhelm 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 asexample.comor an IP address. It must also differ from the NetBox hostname. Put each administrator in Initial Platform Administrators, onesubper 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_hostnameandpas_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 onesubper line. To list several, write them to a config values file, for exampleadmin-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.
- Open the Keycloak admin console. Follow Read the break-glass Keycloak administrator for the credentials and the port-forward.
- Select the
netboxrealm. Do not create people in themasterrealm: it holds the console's own administrator. - Open Users and add a user. Fill in the username, email, first name and last name. The realm requires all four.
- On the user's Credentials tab, set a password. Keep Temporary on, so that the person sets a new password at first sign-in.
- 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
netboxrealm, 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.initialAdminSubsin your values. On Embedded Cluster, set Initial Platform Administrators in the Admin Console, onesubper 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
subcontaining 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 theirsubfor a comma. - An administrator promoted this way is protected while their
substays 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:
- 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
sublist and a restart. - Remove their
subfrom the list and wait for the authorization server to restart. - 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
pendingflag.
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:
- In the Keycloak admin console, open the
netboxrealm, then Realm settings, then the User profile tab.- Open the
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.AdminUiServiceso 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:
| Header | Value |
|---|---|
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; echoRun 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:
| Field | What it is |
|---|---|
email | The person on the platform side. An email no Keycloak account holds creates a pending user |
netbox_instance | The NetBox instance id from ListNetBoxInstances |
netbox_user_id | The 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
}'| Response | Cause |
|---|---|
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_denied | The 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_foundand nothing changes. BatchDeactivateUsersrefuses your own id (failed_precondition) and any administrator protected byspec.pas.initialAdminSubs(permission_denied). On a pending user it rescinds the invite.BatchReactivateUsersrefuses 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; echoThe 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:
-
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> -
Forward local port 443 to the service. Binding a port below 1024 needs administrator rights on most systems, and
sudodoes not read your own kubeconfig, so name it:sudo kubectl --kubeconfig "$HOME/.kube/config" -n <namespace> \ port-forward svc/<cluster>-keycloak-service 443:8443On Embedded Cluster,
kubectlruns on a controller node, so the forward listens on that node. Run it there on port 8443 instead, fromsudo ./netbox-enterprise shell, and tunnel it to the machine running the browser.sudodrops 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> -
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. -
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.
-
Change the password in the Keycloak admin console, for the
adminuser in themasterrealm, not thenetboxrealm the rest of this page uses. Do not delete or rename theadminuser, even though Keycloak suggests replacing it: NetBox Enterprise signs in with that username. -
Update the stored copy so it still matches. On Embedded Cluster, run both blocks below from
sudo ./netbox-enterprise shell. Elsewhere, do not putsudoin front of thiskubectl: it then fails withunable to read patch file, becausesudodoes 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; echoThen 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_PASSWORDKeycloak 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/1ready, then start the port-forward again:kubectl -n <namespace> get pod <cluster>-keycloak-0Keep 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
IdentityProvidercondition showsFalsewith reasonKeycloakAdminUnavailable. Correct the secret and the operator retries on the next reconcile. -
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.
Platform Sign-On with LDAP
Federate your Active Directory or OpenLDAP directory into the identity provider bundled with NetBox Enterprise, so your users sign in to the platform interface with their directory account
SAML Single Sign-On
Configure SAML 2.0 authentication for NetBox Enterprise with any SAML-compliant identity provider