Docs

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 a NotOnOrAfter a 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 IdPValue
Entity ID and audience restrictionhttps://<netbox-hostname>/sso/realms/netbox
Assertion consumer service (ACS) URL, HTTP-POSThttps://<netbox-hostname>/sso/realms/netbox/broker/<alias>/endpoint
Sign the assertionYes
Assertion lifetime (NotOnOrAfter)A few minutes
AttributesThe 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

  1. Tick Federate a SAML identity provider. This also ticks Enable Bundled Keycloak, unless you saved it off before.
  2. Fill in the fields.
  3. Save the config, then deploy.
FieldRequiredValue
SAML Provider AliasYesThe alias from step 1
SAML Sign-in Button LabelNoThe label of the sign-in button. Blank shows the alias
SAML Provider Entity IDYesYour IdP's entity ID. Keycloak refuses a response from a different issuer
SAML Single Sign-On URLYesThe https:// URL where your IdP takes sign-in requests (HTTP-Redirect binding)
SAML Signing Keys FromYesMetadata URL or Pasted certificates. Air-gapped installs default to Pasted certificates
SAML Metadata URLWith Metadata URLYour IdP's https:// metadata URL
SAML Signing CertificatesWith Pasted certificatesEvery current signing certificate, in PEM format. Do not paste a private key
SAML Stable ID AttributeYesThe attribute from step 2
SAML Groups AttributeNoThe 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-enterprise

Do 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
FieldRequiredValue
aliasYesThe alias from step 1
enabledNoUnset means true. Use false to turn the provider off
displayNameNoThe label of the sign-in button. Unset shows the alias
idpEntityIdYesYour IdP's entityID. Keycloak refuses a response from a different issuer
singleSignOnServiceUrlYesThe https:// URL where Keycloak sends the browser
signingCertificatesOne of the twoThe Secret name and key of the PEM signing certificates
metadataUrlOne of the twoYour IdP's https:// metadata URL
stableIdAttributeYesThe attribute from step 2
groupsAttributeNoThe 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 reasonMeaning
True, FederationConsistentThe realm matches your configuration. With certificates that you supply, the message gives the latest end date of the valid certificates
False, SigningCertificateExpiringThe last valid certificate ends within 30 days. See Rotate the signing certificate
False, SigningCertificateInvalidNo certificate in the Secret is valid now. Every SAML login fails
False, SigningCertificateUnreadableThe 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.
  • validateSignature and wantAssertionsSigned, 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.
  • syncMode FORCE, so each login copies the attributes again. A group removed at your IdP leaves federated_groups at 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.pem

    openssl must 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.pem with 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: false in 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

ProblemCause 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 errorThe 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 responseYour IdP does not send the stable ID attribute with the exact name that you configured
Every login creates a new userThe value of the stable ID attribute changes between logins. Use a value that never changes for the person
federated_groups is emptyYour 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_ERROR with error="invalid_signature".
  • An expired or not yet valid certificate in the list logs Ignoring invalid certificate: [, once for each such certificate on each login. The Subject: and To: lines after it name the certificate and give its end date.
  • A wrong key with valid dates logs invalid_signature but no Ignoring invalid certificate line. So with no such line, the dates are not the cause: compare the listed certificates with your IdP's signing certificate.
  • An Ignoring invalid certificate line 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.

On this page