Platform Single Sign-On
Federate your own OpenID Connect provider, SAML provider or LDAP directory into the identity provider bundled with NetBox Enterprise, and what an install that signs in to NetBox directly today should expect
NetBox Enterprise can ship its own identity provider. When it is enabled, the platform trusts that provider and nothing else. Your corporate identity provider does not replace it — it federates into it, becoming a second way to sign in to the same realm, beside the realm's own username and password form.
This page covers connecting your provider, confirming it works, turning it off again, and what an install whose users sign in to NetBox directly today should expect.
This is not NetBox sign-on
Federating a provider changes how people sign in to the platform interface. It does not change how anyone signs in to NetBox itself, and enabling it will not put your corporate login in front of the NetBox web interface.
Putting SSO in front of NetBox is a separate, unrelated setup that this release does not replace. Those pages remain current:
The two systems run side by side, and nothing stops you from configuring both. See Moving from direct NetBox SSO.
Federation is also only the first half of getting someone working. It establishes who a person is on the platform. Connecting that person to a NetBox account is a separate administrative step, covered in Identity Mapping.
One source at a time
This page covers an OpenID Connect provider, and the requirements that every source shares. The bundled provider can instead federate a SAML provider or an LDAP directory:
It federates one source at a time. When you turn one source on, the Admin Console hides the other two.
SAML and LDAP configured directly against NetBox are unaffected by anything on this page.
Before you start
Federation is configured either in the Admin Console, under Identity Provider (Keycloak), or
under netboxEnterprise.spec in your Helm values. Do not edit the NetBoxEnterprise custom
resource by hand: it is rendered from your configuration, so the next deploy either overwrites the
edit or fails with a field-manager conflict. See
Identity Mapping.
The console writes a subset of the block the Helm path does:
- It has no field for
scopesorgroupsClaim. A console install always requestsopenid profile emailand reads group membership from a claim namedgroups. If your provider needs an extra scope to emit groups, or names the claim differently, configure federation through Helm instead. - It stores the client secret in a Secret it manages itself,
keycloak-oidc-federation-clientwith keyclient_secret. You cannot point it at a Secret you created.
Everything else in the field reference applies to both.
These four have to hold or no federated provider is created at all:
| Requirement | Why |
|---|---|
spec.idp.enabled is true | Deploys the bundled identity provider. Off by default |
Routing is in Gateway mode and spec.gateway.enabled is true | The bundled provider is served through a Gateway listener; there is no other route to it. Without both, IdentityProvider reports False with reason PendingHost |
At least one Gateway listener names a concrete hostname, or no listener names a hostname and spec.ingress.tls names a host | The sign-in URL is built from the first concrete listener hostname. When no listener declares a hostname, the first spec.ingress.tls host is used instead. Listeners that are all wildcards (*.example.com and nothing else) leave no origin, even with a spec.ingress.tls host. Without an origin, IdentityProvider reports False with reason PendingHost |
| The install is cluster-scoped | Enabling the bundled provider creates cluster-scoped roles. A namespace-only install reports IdentityProvider False with reason NamespaceScopedUnsupported |
A Helm install routes through Ingress by default, so the bundled provider needs Gateway routing turned on. In your Helm values, set netboxEnterprise.spec.routing.mode: gateway and netboxEnterprise.spec.gateway.enabled: true. Add an HTTPS listener whose hostname is your NetBox hostname. To use the bundled Traefik controller, also set gateway.enabled: true. Turning on the bundled Keycloak has a complete example. Gateway routing replaces Ingress routing. On an existing install, the upgrade that turns it on deletes the Ingress objects the operator created, so plan a short cutover and point your DNS at the Gateway after it. Without these values, IdentityProvider is False with reason PendingHost. That condition does not gate Ready, so Ready can still be True.
These two have to hold before anyone can put a federated login to use. Both are off by default:
| Requirement | Why |
|---|---|
spec.pas.enabled is true | The authorization server the platform signs people in against |
spec.ui.enabled is true, with spec.ui.hostname set | The platform interface a federated login lands in |
On a Helm install without them, the sign-in button works but the login has nowhere to land.
On an Admin Console install:
- Embedded Cluster: the bundled provider takes its host from the NetBox Hostname. With
that field blank,
IdentityProviderreportsFalsewith reasonPendingHost, and no sign-in button appears. To give a federated login a place to land, tick Enable the Platform UI and set the Platform UI Hostname. That also turns on Enable the Platform Authorization Server, unless you turned it off yourself. Identity Mapping gives the hostname rules. - Admin Console on an existing cluster: the console configures Ingress rather than a Gateway,
so the bundled provider cannot be provisioned in this release.
IdentityProviderreportsFalsewith reasonPendingHost.
Two more things worth knowing before you plan a rollout:
- The bundled provider shares NetBox Enterprise's PostgreSQL database. Single sign-on availability is tied to that database's availability, backup, and failover; the two recover together, not independently.
- If you serve the platform interface on its own hostname with
spec.ui.hostname, that hostname is not where your provider redirects back to. See Build the callback URL.
Connecting your provider
Do these in order. The alias appears inside the callback URL, and the callback URL is what you register with your provider in order to get a client ID and secret, so working out of order stalls at step 3.
1. Choose an alias
The alias is your provider's stable key inside the realm. It identifies the button on the sign-in page and every federated identity link.
Treat it as permanent. Changing it after people have signed in orphans their identity links, and those people come back as new, empty accounts. Renaming it also leaves the old provider running beside the new one, because there is no longer anything pointing at the old one to remove it.
It must be letters, digits, underscores, and hyphens only, up to 64 characters.
2. Build the callback URL
Your provider redirects back to the bundled provider's broker endpoint for this alias:
https://<netbox-hostname>/sso/realms/netbox/broker/<alias>/endpoint<netbox-hostname> is the concrete Gateway listener hostname NetBox Enterprise is served on. On an
install that serves the platform interface on a second hostname, this is still the NetBox hostname
— the bundled provider is served there, not on the platform interface's hostname. Registering the
platform hostname instead produces a login that works right up to the final redirect and then
fails.
You can confirm the exact URL after step 6 rather than trusting this one: the bundled provider displays the redirect URI it will accept on your provider's settings page in its admin console.
3. Register the application with your provider
In your identity provider, create an OpenID Connect application — an "app registration" in Microsoft Entra ID, an "application" in Okta — with:
- The callback URL from step 2 as an allowed redirect URI.
- The authorization code flow enabled, with a client secret. The secret is posted to your token
endpoint as form parameters (
client_secret_post). - Any scope your provider needs in order to emit group membership, if you intend to send groups.
Each provider emits group membership its own way: Okta under a
groupsscope, Entra ID through the groups claim in the app registration's token configuration. Check your provider's documentation. The default scope set requests no group scope, and adding one needs thescopesfield, which the Admin Console does not expose.
Record the client ID and the client secret.
4. Store the client secret
The client secret never goes into the custom resource. Put it in a Kubernetes Secret in the NetBox Enterprise namespace, and reference that Secret from the configuration.
Create it from a file rather than with --from-literal, which would write the secret into your
shell history. The file must hold the secret and nothing else, with no trailing newline. Run the
prompt on its own, for the reason given in
Getting a token, and type the secret:
printf 'Client secret: '; IFS= read -rs CLIENT_SECRET; echoThen write the file and create the Secret from it:
( umask 077; rm -f /path/to/client-secret.txt; printf %s "$CLIENT_SECRET" > /path/to/client-secret.txt ) && \
kubectl -n <namespace> create secret generic customer-oidc \
--from-file=clientSecret=/path/to/client-secret.txt && \
kubectl -n <namespace> label secret customer-oidc \
netboxlabs.com/federation-credential=true \
app.kubernetes.io/part-of=netbox-enterprise
unset CLIENT_SECRETThe && chain labels only a Secret that the create command made. If a Secret named
customer-oidc already exists, create fails and the chain stops, so the label does not opt in
that other Secret.
Delete the file once the Secret exists.
netboxlabs.com/federation-credential=truelets NetBox Enterprise read the Secret. The client secret goes to thetokenUrlin your configuration, so the owner of the Secret must opt it in. Without the label,IdentityFederationshowsFalsewith reasonFederationCredentialRefused, and the condition message gives the command that adds the label.app.kubernetes.io/part-of=netbox-enterpriseputs the Secret in the Velero backup. Without it, a restored install has no client secret. Do not useapp.kubernetes.io/managed-by=netbox-operator: NetBox Enterprise deletes a Secret that has that label and the instance label of your install.
A missing Secret, a missing key, or a blank value is not fatal to the cluster, but it does stop
federation. NetBox Enterprise raises a KeycloakFederationUnavailable event naming the Secret and
the key, writes nothing to the provider, and retries on the next reconcile. What you see depends on
whether the realm already existed: on a first install the sign-in button appears but logins fail
after your provider redirects back, and on an install that turns federation on later there is no
button at all. Create or fix the Secret, then see
Applying a Secret change. A new client secret works the same way.
5. Read the endpoints from your provider
Fetch your provider's .well-known/openid-configuration document and map its keys onto the
configuration fields:
| Configuration field | Discovery document key |
|---|---|
issuerUrl | issuer |
authorizationUrl | authorization_endpoint |
tokenUrl | token_endpoint |
jwksUrl | jwks_uri |
userInfoUrl | userinfo_endpoint |
The endpoints are configured explicitly rather than discovered, so the same values render
identically on every install. Note what that does not buy you: the cluster still reaches tokenUrl
and jwksUrl on every login, and the browser still reaches authorizationUrl, so federating an
external provider is not something an air-gapped install can do.
For Microsoft Entra ID, if the application uses custom signing keys or a claims-mapping policy, add
?appid=<client-id> to jwksUrl. Use the same value as clientId. Or fetch the discovery document
with ?appid=<client-id>: the jwks_uri it returns already includes it. For other applications, the
parameter has no effect, so you can add it or omit it. Microsoft describes the parameter in
Validate the signature.
issuerUrl must equal the iss claim of the tokens your provider mints, character for character.
A trailing slash is a mismatch, and every login is rejected.
6. Add the federation block
Under Helm, add the block to your values file. Two switches outside spec are needed as well: the
top-level idp.enabled installs the bundled identity provider's operator, and
netboxEnterprise.enabled renders the custom resource at all. The Keycloak operator also needs the
netbox-enterprise-crds-keycloak chart, which a cluster admin installs before you upgrade. See
Install CRDs. Any field the custom resource
accepts can be set under netboxEnterprise.spec:
idp:
enabled: true
netboxEnterprise:
enabled: true
spec:
idp:
enabled: true
oidcFederation:
alias: acme-oidc
displayName: Sign in with Acme
issuerUrl: https://login.acme.example.com/oauth2/default
authorizationUrl: https://login.acme.example.com/oauth2/default/v1/authorize
tokenUrl: https://login.acme.example.com/oauth2/default/v1/token
jwksUrl: https://login.acme.example.com/oauth2/default/v1/keys
userInfoUrl: https://login.acme.example.com/oauth2/default/v1/userinfo
clientId: 0oa1example2clientid
clientSecret:
name: customer-oidc
key: clientSecret
scopes:
- openid
- profile
- email
- groups
groupsClaim: groupsField reference
| Field | Required | Constraint | When unset |
|---|---|---|---|
alias | yes | Letters, digits, _ and -, up to 64 characters | — |
enabled | no | Boolean | true. Configuring the block is what turns federation on |
displayName | no | Any string | The sign-in button is labeled with the alias |
issuerUrl | yes | Any string; compared against the token's iss | — |
authorizationUrl | yes | Must start https:// | — |
tokenUrl | yes | Must start https:// | — |
jwksUrl | yes | Must start https:// | — |
userInfoUrl | no | Must start https://, or be empty | Omitted from the provider |
clientId | yes | Any string | — |
clientSecret | yes | A Secret name and key | — |
scopes | no | Each entry 1–128 characters from letters, digits, and _ . : / - | openid profile email |
groupsClaim | no | 1–128 characters from letters, digits, and _ . : / -. Omit it rather than setting it empty | groups |
Every URL the bundled provider actually fetches must be https://, and the API server refuses
anything else rather than accepting it into a provider that looks configured. That matters most on
jwksUrl: incoming tokens are signature-checked against exactly those keys, so fetching them over
plaintext would let anyone on the network path serve their own.
issuerUrl is the one endpoint field with no such constraint, because it is never fetched — it is
only compared against the token's iss claim. The Admin Console still requires an https://
Issuer URL before it saves.
Each scopes entry is a single scope. Entries are joined with a space into the scope set requested
from your provider, which is why an entry containing a space, or any other character outside that
set, is rejected: a space would silently turn one entry into two scopes.
Checking that it works
Start with the provisioning condition on the custom resource:
kubectl -n <namespace> get netboxenterprise <name> \
-o jsonpath='{.status.conditions[?(@.type=="IdentityProvider")]}'| Result | Meaning |
|---|---|
True, reason Provisioned | The realm was provisioned |
Unknown, reason Provisioning or KeycloakNotReady | The identity provider is starting, or the realm import is still running |
Unknown, reason HealthUnconfirmed | The identity provider is ready again after an outage, but NetBox Enterprise could not confirm the realm and its sign-in client on this pass. It stays until a pass confirms them |
Unknown, reason GatewayPolicyRejected or GatewayPolicyUnconfirmed | The realm exists, but the Gateway has not yet confirmed it will route the sign-in path securely |
False, reason PendingHost | No Gateway is enabled, or no listener names a concrete hostname. See Before you start |
False, reason NamespaceScopedUnsupported | The install is namespace-scoped, and the bundled provider needs cluster scope |
False, reason KeycloakAdminUnavailable | Federation is configured, but the stored Keycloak administrator password no longer matches. See KeycloakFederationUnavailable events |
False, any other reason | Read the condition message; it names the cause |
Apart from KeycloakAdminUnavailable, that condition covers the realm, not your federated
provider. The IdentityFederation condition covers the
provider, and the events give the details. To list every Warning event on the NetBox Enterprise
resource:
kubectl -n <namespace> get events --field-selector type=Warning,involvedObject.kind=NetBoxEnterpriseA field selector matches one event reason. To check for one cause:
# Federation is on, but the bundled identity provider is off.
kubectl -n <namespace> get events --field-selector reason=FederationRequiresBundledKeycloak
# Your provider refused the client ID or the client secret.
kubectl -n <namespace> get events --field-selector reason=FederationCredentialsRejected
# The client-secret Secret does not have the opt-in label.
kubectl -n <namespace> get events --field-selector reason=FederationCredentialRefused
# NetBox Enterprise could not set the provider up in the bundled identity provider.
kubectl -n <namespace> get events --field-selector reason=KeycloakFederationUnavailableEach of the first three is published when IdentityFederation changes to its reason, and only
when that reason leads the condition. Every other False reason, such as
UndeclaredFederationSource or FederationNotReconciled, publishes an event with the reason as its
name. An Unknown reason publishes no event. A rejection behind a provider that NetBox Enterprise
could not write publishes a FederationNotReconciled event, not FederationCredentialsRejected,
so read the condition message too. KeycloakFederationUnavailable is published on every reconcile
while its cause stands.
Then confirm the realm is reachable:
curl -s https://<netbox-hostname>/sso/realms/netbox/.well-known/openid-configuration | headIf it prints nothing, run it again without -s. A certificate error usually means the hostname
still serves the default placeholder certificate, or this machine does not trust the certificate's
issuer: see
Default certificate behavior.
Finally, sign in. Open the realm's own account page:
https://<netbox-hostname>/sso/realms/netbox/accountThe sign-in page should show the username and password form plus a button labeled with your
displayName, or with the alias if you did not set one. Completing a login through that button and
landing back on the account page is the only check that exercises the whole brokered flow. The
condition and events above confirm that the provider was configured, not that a login succeeds.
To confirm a group claim arrived, look at the brokered user's attributes in the identity provider's
admin console: the incoming claim is copied onto a user attribute named federated_groups. The
admin console is deliberately not served through the public gateway, so reach it by port-forwarding
— Identity Mapping
has the recipe and the administrator credentials.
If the bundled identity provider was first enabled before this release, its realm did not
declare the federated_groups attribute, and Keycloak discards an undeclared attribute without an
error. NetBox Enterprise declares it on every reconcile, on existing realms too, and raises a
KeycloakUserProfileReconciled event when it adds it. If Keycloak refuses the change, it raises a
KeycloakUserProfileUnavailable event instead: see Troubleshooting. Group
claims are kept from each person's next sign-in after the attribute exists.
Applying a Secret change
This applies to every federation source: the OpenID Connect client secret, the SAML signing certificates, and the LDAP bind password.
NetBox Enterprise does not watch these Secrets. It reads a changed Secret at the next periodic
reconcile, within five minutes unless spec.reconcileInterval sets another value. To apply the
change at once, change an annotation on the custom resource, which starts a reconcile:
kubectl -n <namespace> annotate netboxenterprise <name> \
nbe.netboxlabs.com/reconcile="$(date +%s)" --overwriteOn the Admin Console, save the config and deploy to apply the change.
The IdentityFederation condition
The IdentityFederation condition reports what NetBox Enterprise found in the realm, for every
federation source:
kubectl -n <namespace> get netboxenterprise <name> \
-o jsonpath='{.status.conditions[?(@.type=="IdentityFederation")]}'These rows apply to every source. The SAML and LDAP pages give more rows for their source.
| Status and reason | Meaning |
|---|---|
True, FederationConsistent | The realm's providers match your configuration |
False, UndeclaredFederationSource | The realm has an enabled provider or directory that your configuration does not declare, for example after you delete or rename an entry, or add a provider in the Keycloak admin console. NetBox Enterprise deletes nothing. Turn it off as the page for your source shows |
False, BundledKeycloakDisabled | Federation is on, but the bundled Keycloak is off. Tick Enable Bundled Keycloak, or on Helm set idp.enabled and spec.idp.enabled to true |
False, FederationNotReconciled | NetBox Enterprise could not read a credential Secret, or could not write the provider. The KeycloakFederationUnavailable events give the cause |
Unknown, FederationUnconfirmed | NetBox Enterprise could not read the realm. If the message names view-identity-providers, the NetBox Enterprise service account does not have that role, and the condition stays |
| No output | NetBox Enterprise found no source to report, or has not reached the realm yet. Make sure that the entry is in your configuration, then check again after the next reconcile. On the Admin Console, a required field with only spaces writes no entry |
These rows come from the client credential check, which runs for an OpenID Connect provider only.
NetBox Enterprise checks the client credentials against your provider after each change, and every
hour. An LDAP bind password Secret without the label also reports FederationCredentialRefused:
see the LDAP page.
| Status and reason | Meaning |
|---|---|
False, CredentialsRejected | Your provider refused the client ID or the client secret, so every federated sign-in fails. Local accounts still sign in. See Troubleshooting |
False, FederationCredentialRefused | The client-secret Secret does not have the label netboxlabs.com/federation-credential=true, so NetBox Enterprise did not read it. The message gives the command that adds it. See Troubleshooting |
Unknown, ProviderUnreachable | NetBox Enterprise could not check the client credentials, for example because it has no route to tokenUrl. This does not show whether sign-in works. See Troubleshooting |
When the realm has more than one problem, the reason gives the most urgent one, and the message
lists all of them. A Secret without the label ranks first, so its condition message can also name
the provider that NetBox Enterprise could not write as a result. NetBox Enterprise publishes a
Warning event each time the condition changes to a new False reason.
On an Admin Console install, the support bundle reports the same condition as the Federated identity provider health check.
How the credential check works
Your provider does not see the client ID and secret until someone signs in, so a wrong value otherwise shows up only as failed logins. NetBox Enterprise checks them itself:
- It sends your
tokenUrlthe request that ends a login, with a random code that cannot be redeemed. If your provider checks the code before the client, as Entra ID does, NetBox Enterprise sends a secondclient_credentialsrequest for a resource that does not exist. Neither request can return a token. - The client secret goes only to
tokenUrl, which is where the bundled identity provider sends it on every federated login. NetBox Enterprise follows no redirect and never logs the secret. - The request comes from the NetBox Enterprise operator pod. It uses that pod's proxy settings, the
system trust store, and the CA certificates in
spec.extraCaCertificates.
The check runs on the next reconcile after the alias, tokenUrl, clientId, the client Secret,
the public hostname, or the list of spec.extraCaCertificates entries changes. Otherwise it runs
once an hour, so a new certificate in an existing CA Secret waits for the hourly check.
Each check shows as a failed client sign-in in your provider's own logs. In Entra ID it appears in the service principal sign-in logs once an hour, which can trigger a security alert. Tell your identity team before you turn federation on.
A check that gets no usable answer reports Unknown, never a new False. If a
CredentialsRejected already stands, it keeps that rejection. A redirect, a 2xx answer,
and an Entra ID multi-tenant token URL (common, organizations, or consumers) all count as no
usable answer. A True result proves only that your provider accepted the client ID and secret.
It does not check issuerUrl, jwksUrl, the callback URL, or the claims.
What is managed, and what is left alone
The provider is enforced from your configuration on every reconcile. Editing these in the admin console does not stick:
alias, providerId, displayName, enabled, storeToken, trustEmail, linkOnly,
hideOnLogin, authenticateByDefault, and in the provider's configuration clientId,
clientSecret, clientAuthMethod, issuer, authorizationUrl, tokenUrl, jwksUrl,
userInfoUrl, useJwksUrl, validateSignature, defaultScope, syncMode, and
hideOnLoginPage.
The group-claim mapper that writes federated_groups is managed too, matched by its name, so
editing it in the admin console is reverted on the next reconcile.
Clearing an optional value in your configuration clears it on the provider too, so removing
userInfoUrl genuinely removes the endpoint rather than pinning the stale one. The one exception
is disabling federation after its Secret is gone: the provider keeps the client secret it already
holds.
Everything else on the provider belongs to you and survives a reconcile, including
firstBrokerLoginFlowAlias and postBrokerLoginFlowAlias — so an extra one-time-password step on
federated logins stays where you put it — along with organizationId, pkceEnabled, logoutUrl,
allowedClockSkew, prompt, and disableUserInfo.
Two settings are worth understanding rather than changing:
- The provider is not made the default and is not hidden. The sign-in page keeps its username and password form and gains a button beside it, so a provider with the wrong endpoints, a stale secret, or an expired certificate degrades to "the SSO button does not work" instead of locking every administrator out. Identity Mapping explains exactly how far that guarantee goes.
- Email addresses arriving from your provider are not treated as verified. When a federated address collides with an account that already exists in the realm, the person is asked to prove the existing account with its password rather than being silently linked to it. That protection comes from the realm's default first-broker-login flow: if you replace that flow with one that auto-links by email, you take on the collision risk yourself.
Group claims are re-read on every login, not only the first. A group revoked at your provider
is removed from the person's federated_groups attribute at their next sign-in rather than
persisting. Nothing in this release reads that attribute.
Turning federation off
Helm: set enabled: false inside the oidcFederation block and leave the rest of the block
in place. On the custom resource this is the only supported off switch.
Admin Console: untick Accept logins through this provider and deploy, leaving the connection details filled in. Unticking Federate an existing OIDC provider also disables the provider, but unless you ticked Enable Bundled Keycloak yourself it turns off the whole bundled identity provider as well, local accounts included. Prefer the first toggle.
On the next reconcile the button disappears and brokered logins stop. Federated identity links survive, so turning it back on restores the same accounts rather than duplicating them. You do not need the client-secret Secret to still exist in order to disable — deleting it is a natural part of decommissioning an upstream provider, and the two edits can arrive in either order.
Deleting the whole oidcFederation block does not turn federation off. With nothing left
pointing at the provider, it stays live and enabled with the credential it already holds, and keeps
accepting logins. Renaming the alias behaves the same way, leaving the old provider running beside
the new one. In both cases IdentityFederation turns False with reason
UndeclaredFederationSource, and the message names the provider that is still live.
Disable first. Confirm the button is gone. Then remove the block.
Only one federation source can be enabled at a time, and the API server refuses a configuration
that enables a second one. A source with enabled: false does not count. To move from OpenID
Connect to SAML or LDAP, disable this block rather than deleting it.
Moving from direct NetBox SSO
The two run side by side
There is no automated migration and no supported cutover, because NetBox's own authentication is not routed through the bundled identity provider in this release.
Nothing in this release rejects both being configured at once: NetBox's direct SSO is configured as a block of Python, which no validation inspects or correlates with your federation settings. An install can run two independent authentication systems against the same corporate provider with no warning. Any transition is a planned, manual exercise rather than a configuration flip.
The settings do not translate
| Direct NetBox SSO | Platform federation | |
|---|---|---|
| Who authenticates the person | NetBox | The bundled identity provider, brokering to yours |
| How it is configured | A hand-written Python configuration override | Structured fields, validated when you apply them |
| Endpoint inputs | Backend-specific settings — a tenant ID, an Okta API URL, a discovery URL | issuerUrl, authorizationUrl, tokenUrl, jwksUrl, userInfoUrl |
| Client credentials | Written inline in the Python | A client ID plus a reference to a Kubernetes Secret |
| Redirect URI you register | NetBox's own callback | The bundled provider's broker endpoint for the alias |
| Group handling | Whatever the Python does, commonly a custom authentication pipeline | The claim named by groupsClaim, copied to a user attribute |
There is no mechanical conversion between the two. Read your provider's discovery document and fill the federation fields from it, as in step 5, rather than trying to translate the existing Python.
One difference is worth acting on regardless of any transition: the direct path holds the client secret in plaintext inside the Python override, which on an Admin Console install means inside the application configuration. Federation takes a reference to a Kubernetes Secret, so the value never enters the custom resource.
That last guarantee is about the custom resource specifically. Enter the secret in the Admin
Console and the console still renders it into a Secret manifest of its own — the value is held as
a password field, not written into spec.idp. On Helm, you can keep the secret out of the rendered
manifests entirely by creating the Kubernetes Secret yourself and referencing it from the
resource. The Admin Console always uses its own Secret.
The two registrations are also separate. The broker callback you register for federation is not the one NetBox uses, so plan for both to exist during any overlap.
Group membership stops granting NetBox permissions
This is the change to plan for, and it will surprise people.
Today, an install can auto-grant NetBox staff or superuser status from identity provider group membership, because the Python override can contain arbitrary logic. The common patterns are a custom authentication pipeline step that sets those flags from a group claim, and header-based group sync. Both run inside NetBox, on every login, with no administrator involved.
Federation does not carry that automation. A group claim lands on the brokered user as the
federated_groups attribute and stops there. Nothing reads it to grant a NetBox permission, and
permissions are assigned by an administrator by hand.
Two consequences:
- Anyone whose NetBox superuser or staff access comes from group membership today will not have it after moving. Enumerate those people before any transition and plan the manual assignment.
- A person who arrives with no group claim still gets a valid login, carrying no group signal. That is deliberate: with per-organization federation many real users arrive without a group claim, and failing their login would turn a provider misconfiguration into an outage. They hold nothing until an administrator grants it.
Troubleshooting
IdentityProvider is False with reason PendingHost
No Gateway is enabled, or no host resolves for it. Listeners that are all wildcards are a usual
cause. So are listeners that declare no hostname while spec.ingress.tls names no host. Either
way there is no resolvable origin to build the realm's sign-in URL from, so provisioning is
deferred rather than emitted broken. Add a concrete listener hostname and provisioning runs on the
next reconcile.
On Embedded Cluster the listeners get a hostname only once the platform interface is turned on. See Before you start.
On Helm, the usual cause is Ingress routing, which is the chart default. Ready can still be True
while this happens. Turn on Gateway routing as Before you start describes.
IdentityFederation is False with reason BundledKeycloakDisabled
Federation is on, but the bundled identity provider is off, so no federated login can succeed. A
FederationRequiresBundledKeycloak event is published once, when the condition appears.
- Admin Console: tick Enable Bundled Keycloak.
- Helm: set both the top-level
idp.enabledandnetboxEnterprise.spec.idp.enabledtotrue. The first installs the bundled identity provider's operator.
To stop federating instead, see Turning federation off.
IdentityFederation is False with reason CredentialsRejected
Your provider refused the client credentials, so every federated login fails. Local accounts still
sign in. A FederationCredentialsRejected event is published once, when the condition appears.
The condition message names the client ID and the Secret and key that hold the client secret. When your provider says which of the two it refused, the message says so too. Entra ID does, including for an expired client secret.
Fix the value your provider refused:
- Admin Console: correct Client ID or Client Secret on the Identity Provider (Keycloak) screen, and deploy.
- Helm: correct
spec.idp.oidcFederation.clientId, or put the new client secret in the Secret. See Applying a Secret change.
The condition clears when the next check succeeds. A changed client ID or client secret triggers a check on the next reconcile. Otherwise the check runs once an hour.
Deleting the Secret, or leaving its key missing or blank, does not clear the rejection. The bundled
identity provider keeps the client secret it already holds, so the rejection stands until a check
runs with a new secret. While the Secret is missing, the condition shows reason
FederationNotReconciled, and the rejection follows it in the message.
IdentityFederation is False with reason FederationCredentialRefused
The Secret that clientSecret names does not have the label
netboxlabs.com/federation-credential=true, so NetBox Enterprise did not read it. It does not check
the client secret, and it does not set it on the provider.
- A provider the bundled identity provider already holds keeps its stored client secret, so federated sign-in through it can keep working. A rotated client secret does not reach it.
- On a first install, the provider is not created.
The condition message gives the command that adds the label:
kubectl -n <namespace> label secret <secret> netboxlabs.com/federation-credential=true --overwriteThe condition clears on the next reconcile, and the credential check runs at once. To reconcile
without waiting, see Applying a Secret change. Adding the label
is the only fix: deleting the Secret clears the refusal, but NetBox Enterprise then has no client
secret to check or rotate. A FederationCredentialRefused event is published once, when the condition appears.
On an Admin Console install, the console's own Secret already has the label. This reason there means someone removed it by hand.
IdentityFederation is Unknown with reason ProviderUnreachable
NetBox Enterprise tried to check the client credentials and got no usable answer. Common causes:
- The operator pod has no route to
tokenUrl. - A proxy or TLS failure. For a provider on a private CA, add the CA to
spec.extraCaCertificates. A CA Secret that cannot be read, or whose value is not PEM, is skipped, so the check fails at TLS. - A PEM block in
spec.extraCaCertificatesthat is not a certificate. Then no request was sent, and the operator log names the cause.
The condition message names the cause. No event is published. This result says nothing about
whether federated login works. If the operator pod has no route to your provider by design, the
condition stays Unknown.
While a CredentialsRejected stands, a check with no usable answer keeps the rejection. A fix made
while the operator was down shows only once a check gets a clear answer.
The sign-in button never appears
Confirm that spec.idp.enabled is true and that the federation block is actually present on the
live resource:
kubectl -n <namespace> get netboxenterprise <name> -o jsonpath='{.spec.idp}'On an install configured through the Admin Console, the block is written only once every required field is filled in. An absent block there means one of them was left blank, not that the console cannot write it. See Before you start.
Also check that enabled inside the block is not false.
KeycloakFederationUnavailable events
Read the event message. Two common causes:
-
The Secret holding the client secret is missing, the named key is absent, or its value is blank. Create or fix the Secret and it converges on the next periodic reconcile.
-
NetBox Enterprise could not use its administrator access to the bundled provider. On every reconcile it checks that its service account can manage identity providers, and re-grants that role if it was removed by hand. It does not check
manage-realmormanage-clientsthat way. AKeycloakUserProfileUnavailableevent namesmanage-realmwhen Keycloak answered403; if that event or a client error names one of these roles, grant it back to theservice-account-nbe-operatoruser in thenetboxrealm.A
403that persists means the password in the<cluster>-keycloak-adminSecret no longer matches the one Keycloak holds, andIdentityProvideralso reportsFalsewith reasonKeycloakAdminUnavailable. Follow the rotation steps to bring them back in line.
Logins fail as soon as your provider redirects back
Check issuerUrl against the iss claim of a token your provider actually mints. They are compared
character for character, and a trailing slash is a mismatch.
If the signature check is failing instead, confirm jwksUrl is your provider's live jwks_uri and
that it is reachable from inside the cluster.
If the failure is a rejected redirect URI, re-check step 2: on an install that serves the platform interface on its own hostname, the callback is still on the NetBox hostname.
Group claims never arrive
Confirm three things, in order:
- Your provider is configured to emit the claim at all. Most require an explicit scope or a claim-mapping rule.
- That scope is listed in
scopes. The default set isopenid profile emailand includes no group scope. The Admin Console cannot change it; configure federation through Helm instead. groupsClaimmatches the claim name exactly. It is matched exactly, so a near miss produces a login that silently carries no group signal.
If your provider serves groups from the userinfo endpoint rather than in the ID token, userInfoUrl
must be set.
The provider still accepts logins after you removed it
Expected. See Turning federation off. IdentityFederation names the
provider with reason UndeclaredFederationSource. Restore the block with enabled: false, confirm
the button is gone, then remove it.
What this release does not do
- No
scopesorgroupsClaimin the Admin Console. A console install cannot request a group scope. - No second federation source. The bundled identity provider federates one OpenID Connect provider, one SAML provider or one LDAP directory, not two at once.
- No automated migration off direct NetBox SSO, and no guard against having both configured at once.
- No automated group-to-permission mapping. Group claims reach the
federated_groupsuser attribute and stop. - No removal by deletion. Deleting the federation block leaves the provider live; disable it first.
- No sign-in check. The credential check proves only that your provider accepted the client ID
and secret. Its answers are measured on Keycloak and Entra ID. A provider that answers
differently reads
Unknownor goes undetected, neverFalse. - No clean wipe on disabling the bundled provider. Turning
spec.idp.enabledoff removes the Kubernetes resources, but the realm and client data and the identity provider's PostgreSQL role and schema stay in the database. Re-enabling re-adopts them.
TLS and Gateway: Accessing NetBox Enterprise
The NetBox Enterprise installation provides its own gateway controller (Traefik, serving the Kubernetes Gateway API) on ports 80 and 443. No additional confi...
Platform Sign-On with SAML
Federate your SAML 2.0 identity provider, such as Entra ID, Okta or ADFS, into the identity provider bundled with NetBox Enterprise, so your users sign in to the platform interface with their SAML account