Docs

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 scopes or groupsClaim. A console install always requests openid profile email and reads group membership from a claim named groups. 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-client with key client_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:

RequirementWhy
spec.idp.enabled is trueDeploys the bundled identity provider. Off by default
Routing is in Gateway mode and spec.gateway.enabled is trueThe 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 hostThe 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-scopedEnabling 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:

RequirementWhy
spec.pas.enabled is trueThe authorization server the platform signs people in against
spec.ui.enabled is true, with spec.ui.hostname setThe 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, IdentityProvider reports False with reason PendingHost, 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. IdentityProvider reports False with reason PendingHost.

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 groups scope, 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 the scopes field, 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; echo

Then 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_SECRET

The && 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=true lets NetBox Enterprise read the Secret. The client secret goes to the tokenUrl in your configuration, so the owner of the Secret must opt it in. Without the label, IdentityFederation shows False with reason FederationCredentialRefused, and the condition message gives the command that adds the label.
  • app.kubernetes.io/part-of=netbox-enterprise puts the Secret in the Velero backup. Without it, a restored install has no client secret. Do not use app.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 fieldDiscovery document key
issuerUrlissuer
authorizationUrlauthorization_endpoint
tokenUrltoken_endpoint
jwksUrljwks_uri
userInfoUrluserinfo_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: groups

Field reference

FieldRequiredConstraintWhen unset
aliasyesLetters, digits, _ and -, up to 64 characters—
enablednoBooleantrue. Configuring the block is what turns federation on
displayNamenoAny stringThe sign-in button is labeled with the alias
issuerUrlyesAny string; compared against the token's iss—
authorizationUrlyesMust start https://—
tokenUrlyesMust start https://—
jwksUrlyesMust start https://—
userInfoUrlnoMust start https://, or be emptyOmitted from the provider
clientIdyesAny string—
clientSecretyesA Secret name and key—
scopesnoEach entry 1–128 characters from letters, digits, and _ . : / -openid profile email
groupsClaimno1–128 characters from letters, digits, and _ . : / -. Omit it rather than setting it emptygroups

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")]}'
ResultMeaning
True, reason ProvisionedThe realm was provisioned
Unknown, reason Provisioning or KeycloakNotReadyThe identity provider is starting, or the realm import is still running
Unknown, reason HealthUnconfirmedThe 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 GatewayPolicyUnconfirmedThe realm exists, but the Gateway has not yet confirmed it will route the sign-in path securely
False, reason PendingHostNo Gateway is enabled, or no listener names a concrete hostname. See Before you start
False, reason NamespaceScopedUnsupportedThe install is namespace-scoped, and the bundled provider needs cluster scope
False, reason KeycloakAdminUnavailableFederation is configured, but the stored Keycloak administrator password no longer matches. See KeycloakFederationUnavailable events
False, any other reasonRead 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=NetBoxEnterprise

A 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=KeycloakFederationUnavailable

Each 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 | head

If 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/account

The 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)" --overwrite

On 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 reasonMeaning
True, FederationConsistentThe realm's providers match your configuration
False, UndeclaredFederationSourceThe 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, BundledKeycloakDisabledFederation 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, FederationNotReconciledNetBox Enterprise could not read a credential Secret, or could not write the provider. The KeycloakFederationUnavailable events give the cause
Unknown, FederationUnconfirmedNetBox 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 outputNetBox 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 reasonMeaning
False, CredentialsRejectedYour provider refused the client ID or the client secret, so every federated sign-in fails. Local accounts still sign in. See Troubleshooting
False, FederationCredentialRefusedThe 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, ProviderUnreachableNetBox 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 tokenUrl the 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 second client_credentials request 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 SSOPlatform federation
Who authenticates the personNetBoxThe bundled identity provider, brokering to yours
How it is configuredA hand-written Python configuration overrideStructured fields, validated when you apply them
Endpoint inputsBackend-specific settings — a tenant ID, an Okta API URL, a discovery URLissuerUrl, authorizationUrl, tokenUrl, jwksUrl, userInfoUrl
Client credentialsWritten inline in the PythonA client ID plus a reference to a Kubernetes Secret
Redirect URI you registerNetBox's own callbackThe bundled provider's broker endpoint for the alias
Group handlingWhatever the Python does, commonly a custom authentication pipelineThe 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.enabled and netboxEnterprise.spec.idp.enabled to true. 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 --overwrite

The 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.extraCaCertificates that 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-realm or manage-clients that way. A KeycloakUserProfileUnavailable event names manage-realm when Keycloak answered 403; if that event or a client error names one of these roles, grant it back to the service-account-nbe-operator user in the netbox realm.

    A 403 that persists means the password in the <cluster>-keycloak-admin Secret no longer matches the one Keycloak holds, and IdentityProvider also reports False with reason KeycloakAdminUnavailable. 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:

  1. Your provider is configured to emit the claim at all. Most require an explicit scope or a claim-mapping rule.
  2. That scope is listed in scopes. The default set is openid profile email and includes no group scope. The Admin Console cannot change it; configure federation through Helm instead.
  3. groupsClaim matches 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 scopes or groupsClaim in 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_groups user 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 Unknown or goes undetected, never False.
  • No clean wipe on disabling the bundled provider. Turning spec.idp.enabled off 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.

On this page