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
NetBox Enterprise 2.5.0 can federate your SAML 2.0 identity provider (IdP) into its bundled identity provider, Keycloak. Your users then sign in to the platform interface with their SAML account. NetBox sign-in does not change. To put SAML in front of NetBox itself, see SAML Single Sign-On.
Platform Single Sign-On gives the background and the requirements that every source shares.
Before you start
- The bundled identity provider is on and provisioned. See Before you start.
- No other federation source is on. See One source at a time.
- Your IdP can send a stable, unique user ID as a SAML attribute. The email address is not stable enough.
- Your IdP signs each assertion. Keycloak refuses an unsigned assertion.
- Each assertion has an
AudienceRestriction, and aNotOnOrAftera few minutes after issue. Keycloak checks the audience and the expiry only when the assertion has them. Keycloak does not record the assertions that it accepted.
Connect your SAML provider
1. Choose the alias
The alias names the sign-in button, and it is part of the URLs that you register at your IdP.
Use only letters, digits, _ and -, up to 64 characters.
Do not change the alias after you deploy it. The old provider stays on, and identity links belong to the alias, so people come back as new, empty accounts.
The alias must differ from the alias of your OpenID Connect provider, also when that provider is off. If the two are the same, the deploy fails, and the Admin Console shows a warning.
2. Choose the stable ID attribute
The stable ID attribute holds an ID that never changes for a person. Its value becomes the Keycloak username and the key of the federated identity. If the value changes, the person gets a second account. Keycloak never uses the NameID, because many IdPs send an email address or a value for each session there.
There is no default. Examples:
- Entra ID:
http://schemas.microsoft.com/identity/claims/objectidentifier - Okta: a custom attribute mapped from the Okta user ID
- Keycloak as the IdP: a property mapper on the user's
id
The names of the stable ID attribute and the groups attribute can have only letters, digits, and _ . : / # -, up to 256 characters.
3. Register NetBox Enterprise at your IdP
Give these values to your IdP team.
<netbox-hostname> is the NetBox hostname, not the Platform UI hostname.
| Setting at the IdP | Value |
|---|---|
| Entity ID and audience restriction | https://<netbox-hostname>/sso/realms/netbox |
| Assertion consumer service (ACS) URL, HTTP-POST | https://<netbox-hostname>/sso/realms/netbox/broker/<alias>/endpoint |
| Sign the assertion | Yes |
Assertion lifetime (NotOnOrAfter) | A few minutes |
| Attributes | The stable ID attribute, email, first_name, last_name, and the groups attribute |
Keycloak serves the service-provider metadata at https://<netbox-hostname>/sso/realms/netbox/broker/<alias>/endpoint/descriptor.
On Embedded Cluster, the Admin Console shows these values under SAML Provider Alias, after you set the NetBox Hostname and the alias.
If you change the NetBox hostname, the entity ID, the ACS URL, and the service-provider metadata URL change. Register the new values at your IdP, or every SAML login fails.
4. Choose the source of the signing certificates
Keycloak checks each assertion against your IdP's signing certificates. Use one of these sources:
- Metadata URL. Keycloak loads the certificates from your IdP's metadata, and follows a rotation at your IdP by itself. The Keycloak pod must reach the
https://URL directly, not through a proxy. Keycloak accepts any key that the URL serves, so the TLS trust of the URL protects every login. - Certificates that you supply. Keycloak fetches nothing, so this works on an air-gapped install or behind a proxy. You must add a new certificate before the current one expires. See Rotate the signing certificate.
For a metadata URL with a private CA, add the CA certificate under Additional CA Certificates in the Admin Console, or in spec.extraCaCertificates on Helm.
A chain through a certificate that NetBox Enterprise distrusts, such as the eMudhra roots and intermediates, fails even with its CA added. The Keycloak log then shows Untrusted certificate.
5. Enter the configuration
Admin Console
- Tick Federate a SAML identity provider. This also ticks Enable Bundled Keycloak, unless you saved it off before.
- Fill in the fields.
- Save the config, then deploy.
| Field | Required | Value |
|---|---|---|
| SAML Provider Alias | Yes | The alias from step 1 |
| SAML Sign-in Button Label | No | The label of the sign-in button. Blank shows the alias |
| SAML Provider Entity ID | Yes | Your IdP's entity ID. Keycloak refuses a response from a different issuer |
| SAML Single Sign-On URL | Yes | The https:// URL where your IdP takes sign-in requests (HTTP-Redirect binding) |
| SAML Signing Keys From | Yes | Metadata URL or Pasted certificates. Air-gapped installs default to Pasted certificates |
| SAML Metadata URL | With Metadata URL | Your IdP's https:// metadata URL |
| SAML Signing Certificates | With Pasted certificates | Every current signing certificate, in PEM format. Do not paste a private key |
| SAML Stable ID Attribute | Yes | The attribute from step 2 |
| SAML Groups Attribute | No | The attribute that lists the person's groups. Blank means groups |
The console keeps pasted certificates in the Secret keycloak-saml-federation-certs, key signing.pem.
Helm
If you supply the certificates, put them in a Secret.
The app.kubernetes.io/part-of label puts the Secret in the Velero backup. Without it, a restored install has no certificates, and SAML sign-in fails until you create the Secret again:
kubectl -n <namespace> create secret generic acme-saml-certs \
--from-file=signing.pem=idp-signing.pem
kubectl -n <namespace> label secret acme-saml-certs \
app.kubernetes.io/part-of=netbox-enterpriseDo not use the label app.kubernetes.io/managed-by=netbox-operator. NetBox Enterprise deletes a Secret that has that label and the instance label of your install.
Then add the entry to your values file. samlFederation holds one entry:
idp:
enabled: true
netboxEnterprise:
enabled: true
spec:
idp:
enabled: true
samlFederation:
- alias: acme-saml
displayName: Sign in with Acme
idpEntityId: https://idp.acme.example/saml
singleSignOnServiceUrl: https://idp.acme.example/saml/sso
signingCertificates:
name: acme-saml-certs
key: signing.pem
stableIdAttribute: http://schemas.microsoft.com/identity/claims/objectidentifier
groupsAttribute: http://schemas.microsoft.com/ws/2008/06/identity/claims/groups| Field | Required | Value |
|---|---|---|
alias | Yes | The alias from step 1 |
enabled | No | Unset means true. Use false to turn the provider off |
displayName | No | The label of the sign-in button. Unset shows the alias |
idpEntityId | Yes | Your IdP's entityID. Keycloak refuses a response from a different issuer |
singleSignOnServiceUrl | Yes | The https:// URL where Keycloak sends the browser |
signingCertificates | One of the two | The Secret name and key of the PEM signing certificates |
metadataUrl | One of the two | Your IdP's https:// metadata URL |
stableIdAttribute | Yes | The attribute from step 2 |
groupsAttribute | No | The attribute that lists the person's groups. Unset means groups |
Set exactly one of signingCertificates and metadataUrl. The API server refuses both or neither.
The custom resource reference gives every field.
Check that it works
Read the IdentityFederation condition, as The IdentityFederation condition shows. These rows apply to SAML:
| Status and reason | Meaning |
|---|---|
True, FederationConsistent | The realm matches your configuration. With certificates that you supply, the message gives the latest end date of the valid certificates |
False, SigningCertificateExpiring | The last valid certificate ends within 30 days. See Rotate the signing certificate |
False, SigningCertificateInvalid | No certificate in the Secret is valid now. Every SAML login fails |
False, SigningCertificateUnreadable | The Secret is missing or unreadable, or holds no PEM certificate that parses. NetBox Enterprise turns the provider off, or on a new install does not create it. Local accounts still sign in |
The certificate reasons apply only while the provider is on.
The condition does not prove that a login works.
To test a login, open https://<netbox-hostname>/sso/realms/netbox/account, select your button, and sign in at your IdP.
After the login, the Keycloak user has the IdP's groups in the federated_groups attribute.
Nothing in this release reads that attribute.
What NetBox Enterprise manages
NetBox Enterprise writes these Keycloak settings on every reconcile. An edit in the Keycloak admin console does not stay:
- The alias, the button label, the on/off state, and the visibility on the login page.
- The entity ID, the single sign-on URL, and the signing certificates or the metadata URL.
validateSignatureandwantAssertionsSigned, always on.- The stable ID attribute as the principal.
trustEmail, always off, so Keycloak does not treat an email address from your IdP as verified.syncModeFORCE, so each login copies the attributes again. A group removed at your IdP leavesfederated_groupsat the next login.postBindingResponse, always on, so the sign-in request asks your IdP to send its response by HTTP-POST. Microsoft Entra ID refuses a request that asks for HTTP-Redirect.postBindingLogout, always off, so logout requests stay on HTTP-Redirect, the only binding Entra takes for them. This applies only if you add a single-logout URL in the console.artifactBindingResponse, always cleared, because Keycloak checks it first and would ask your IdP for HTTP-Artifact instead of HTTP-POST.- The mappers for email, first name, last name, and groups.
Other settings keep your values, such as the NameID policy, allowedClockSkew (default 0), forceAuthn, and the requested authentication context.
Multi-factor authentication therefore stays at your IdP.
Rotate the signing certificate
With a metadata URL, Keycloak follows a rotation at your IdP by itself. An expired certificate in the metadata refuses every login, and the condition does not warn about it, because NetBox Enterprise does not read the metadata.
With certificates that you supply, add the new certificate beside the current one before the current one expires. Keycloak uses every listed certificate that is in its validity period, and ignores the others. You can remove the old certificate later.
-
Admin Console: paste both certificates in SAML Signing Certificates, save, then deploy.
-
Helm: put both certificates in one file, and check the file:
cat current-signing.pem new-signing.pem > signing.pem && \ openssl crl2pkcs7 -nocrl -certfile signing.pem | openssl pkcs7 -print_certs -noout && \ grep -c 'BEGIN' signing.pem && grep -c 'BEGIN CERTIFICATE' signing.pemopensslmust show a subject and an issuer for each of the two certificates, and the two counts must be the same. If a check fails, do not apply the file. A key block or a value that does not parse turns the provider off at once. A file with only the new certificate refuses every login until your IdP signs with the new key.Then update the Secret. A server-side apply keeps its labels:
kubectl -n <namespace> create secret generic acme-saml-certs \ --from-file=signing.pem=signing.pem --dry-run=client -o yaml \ | kubectl -n <namespace> apply --server-side --force-conflicts -f -To apply the change before the next reconcile, see Applying a Secret change.
Then check the IdentityFederation message:
- The end date is usually that of the new certificate:
openssl x509 -noout -enddate -in new-signing.pem. - If the message says that Keycloak ignores certificates, at least one certificate is expired or not yet valid.
- The message does not identify the certificate. Compare
openssl x509 -noout -fingerprint -sha256 -in new-signing.pemwith the certificate that your IdP shows.
When no listed certificate is valid, every SAML login fails, also when your IdP's key did not change.
The user sees "Invalid signature in response from identity provider", and the Keycloak log shows Ignoring invalid certificate.
To read that log, see Read the Keycloak log.
Revoke a signing certificate
Replace the certificate in the Secret with a different certificate that parses.
If you delete the Secret, or its value does not parse, NetBox Enterprise turns the provider off and removes the certificates that Keycloak stored. New SAML logins fail, sessions that are open continue, and local accounts still sign in. The provider comes back on at the first reconcile after the Secret holds a usable certificate. While Keycloak is unreachable, a revocation has no effect: Keycloak still trusts the old certificates.
What changes for your users
- NetBox's own SAML backend stays on, if you use it, with its group mirroring, staff and superuser groups, and required group.
- Each person signs in two times: to NetBox, and to the platform interface through Keycloak. With the same IdP, both use the same credentials. Your IdP's session decides if it asks for the password again.
- An administrator connects each platform user to their NetBox account by hand. Until then, the platform interface shows that person no NetBox data. See Identity Mapping.
- Keycloak admits every person that your IdP authenticates. It has no required-group check in this release. To limit access, limit who is assigned the NetBox Enterprise application at your IdP.
Account collisions
Keycloak never links a SAML user to a local Keycloak account by itself. When the IdP sends the email address of a local account, the user sees "User with email ... already exists. How do you want to continue?". To link the accounts, the user must prove that they own the local account. They use its password, or an email link if the realm has email. The administrator gets no condition, event, or log line for a collision.
Do not change the realm's first-broker-login flow to one that links accounts by email. The default flow keeps two people in separate accounts.
Identity links belong to one alias. After a change from an OpenID Connect provider to SAML, people who signed in through OpenID Connect come back as new accounts. They see the prompt above when the email address matches.
Turn federation off
- Admin Console: untick Federate a SAML identity provider, save, then deploy. The console keeps your settings and writes the provider as off.
- Helm: set
enabled: falsein the entry, and keep the rest of the entry.
The button disappears, and Keycloak refuses logins through the provider. The identity links stay, so people get the same accounts when you turn the provider on again.
Do not delete the entry or change the alias.
On the Admin Console, a cleared required field also deletes the entry.
NetBox Enterprise never deletes a provider, so the old provider stays on, and the condition shows UndeclaredFederationSource.
To recover, put the entry back with enabled: false, or turn the provider off in the Keycloak admin console.
To change to another source, turn SAML off and the other source on in the same save.
Troubleshooting
| Problem | Cause and fix |
|---|---|
| "Invalid signature in response from identity provider" | Check, in order: the condition (SigningCertificateInvalid means that no listed certificate is valid now: each one is expired or not yet valid); the Keycloak log (Read the Keycloak log); that your IdP signs the assertion, not only the response; that the certificate is your IdP's current signing certificate |
| An issuer or audience error | The entity ID must equal the Issuer in the response. The audience at your IdP must be https://<netbox-hostname>/sso/realms/netbox |
| Keycloak refuses the response | Your IdP does not send the stable ID attribute with the exact name that you configured |
| Every login creates a new user | The value of the stable ID attribute changes between logins. Use a value that never changes for the person |
federated_groups is empty | Your IdP sends no attribute whose Name or FriendlyName matches the groups attribute exactly. The user still signs in, with no groups |
The bundled realm does not store login events by default. Failed logins show only in the Keycloak server log. To read it, see Read the Keycloak log.
Read the Keycloak log
By default, Keycloak runs one pod for each node, up to three pods.
Set spec.idp.replicas to run a different number.
Each pod logs only the logins that it handles, so read every pod:
kubectl -n <namespace> logs -c keycloak --prefix --tail=-1 \
-l app=keycloak,app.kubernetes.io/managed-by=keycloak-operator \
| grep -E 'invalid_signature|Ignoring invalid certificate|Subject:|To:'Keep --tail=-1: with -l, kubectl shows only 10 lines of each pod.
If a container restarted, run the command a second time with --previous --ignore-errors.
That run shows only the log from before the restart. It does not show the current log.
Without --ignore-errors, kubectl stops at the first pod that did not restart.
Read the lines as follows:
- Each refused login logs
IDENTITY_PROVIDER_RESPONSE_ERRORwitherror="invalid_signature". - An expired or not yet valid certificate in the list logs
Ignoring invalid certificate: [, once for each such certificate on each login. TheSubject:andTo:lines after it name the certificate and give its end date. - A wrong key with valid dates logs
invalid_signaturebut noIgnoring invalid certificateline. So with no such line, the dates are not the cause: compare the listed certificates with your IdP's signing certificate. - An
Ignoring invalid certificateline does not prove that the dates are the cause. If the list also has a valid certificate, the login fails because that certificate does not match your IdP's signing key.
No output does not prove that there is no problem. These are the usual causes:
- No login was attempted since the pods started.
- A pod restarted. Run the command again with
--previous --ignore-errors. - The namespace is wrong.
Try a login, then run the command again.
If there is still no output, make sure that kubectl -n <namespace> get pods -l app=keycloak lists the Keycloak pods.
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
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