OpenID Connect (OIDC) Single Sign-On

NetBox Enterprise supports single sign-on (SSO) with any OpenID Connect provider, including Okta, Keycloak, Auth0, Authentik, and Google Workspace. This lets users log in with their existing credentials instead of separate NetBox account credentials.

SSO centralizes access control and simplifies user management, letting administrators grant or revoke NetBox access directly from the identity provider.

Prerequisites

Before configuring OIDC authentication, ensure you have:

Identity provider requirements:

• An OIDC-compliant identity provider, with permission to create application registrations
• Test user account for validation (optional but recommended)

NetBox Enterprise requirements:

• NetBox Enterprise v1.10 or later
• Admin console access (https://<your-cluster-host-or-ip>:30000/)
• HTTPS configured for production deployments
• NetBox Enterprise URL (used for redirect URI configuration)
• Outbound HTTPS from the NetBox pods to your provider's OIDC endpoints

Backends

NetBox authenticates through Python Social Auth, which provides a dedicated backend for Okta and a generic backend for every other OIDC provider.

Your choice determines both the settings prefix and the redirect URI.

Identity provider configuration

Okta

1. In the Okta Admin Console, go to Applications and Resources> Applications and click Create App Integration.

2. Select OIDC - OpenID Connect as the sign-in method and Web Application as the application type.

3. Complete the following fields:

   • App integration name: Enter a name (e.g. "NetBox Enterprise").
   • Grant type: Select Authorization Code.
   • Sign-in redirect URIs: https://<your-netbox-domain>/oauth/complete/okta-openidconnect/
   • Sign-out redirect URIs: https://<your-netbox-domain>/ (optional)
   • Assignments: Select the controlled access setting appropriate for your organization.

4. Click Save.

   Under General > Client Credentials, note the Client ID and Client secret.

5. Also note your Okta domain. This is shown under Settings > Account (for example, dev-123456.okta.com).

Note:

• Use HTTPS in production (HTTP only allowed for localhost testing).
• The redirect URI must match exactly what you configure in NetBox, including the trailing slash.
• The sign-out redirect URI is optional. Logging out of NetBox ends the NetBox session only, and the user's Okta session stays active.

Generic OIDC provider

These steps apply to Keycloak, Auth0, Authentik, Google Workspace, GitLab, Dex, and other OIDC-compliant providers.

1. Create a new OIDC client or application in your provider's console.

2. Complete the following fields:

   • Application type: Web application (confidential client)
   • Grant type: Authorization Code
   • Redirect URI: https://<your-netbox-domain>/oauth/complete/oidc/

3. Note the Client ID and Client secret.

4. Note your provider's issuer URL. This is the discovery endpoint URL with /.well-known/openid-configuration removed, because NetBox appends that path itself.

Confirm the discovery document is reachable and returns JSON:

curl https://<issuer-url>/.well-known/openid-configuration

The response lists the endpoints NetBox will use, including authorization_endpoint, token_endpoint, userinfo_endpoint, and jwks_uri.

NetBox Enterprise configuration

Add Python configuration overrides

Open your admin console at https://<your-cluster-host-or-ip>:30000/ and select the Config tab.

Enable Show Advanced Settings and locate the NetBox Python Configuration Overrides section.

Add the configuration for your backend, replacing the placeholder values.

Okta:

REMOTE_AUTH_BACKEND = 'social_core.backends.okta_openidconnect.OktaOpenIdConnect'
SOCIAL_AUTH_OKTA_OPENIDCONNECT_KEY = '<client-id>'
SOCIAL_AUTH_OKTA_OPENIDCONNECT_SECRET = '<client-secret>'
SOCIAL_AUTH_OKTA_OPENIDCONNECT_API_URL = 'https://<okta-domain>/oauth2/'

• client-id and client-secret are the Client Credentials from the General tab of your Okta application.
• okta-domain is your Okta domain, such as dev-123456.okta.com. Use /oauth2/ for the default authorization server, or /oauth2/<auth-server-id>/ for a custom one.

Generic OIDC:

REMOTE_AUTH_BACKEND = 'social_core.backends.open_id_connect.OpenIdConnectAuth'
SOCIAL_AUTH_OIDC_KEY = '<client-id>'
SOCIAL_AUTH_OIDC_SECRET = '<client-secret>'
SOCIAL_AUTH_OIDC_OIDC_ENDPOINT = 'https://<issuer-url>'

Deploy your configuration

1. Scroll to the bottom of the Config page
2. Click Save config
3. Click Go to updated version when prompted
4. Click Deploy to apply changes
5. Wait for NetBox Enterprise to reach Ready state

Configuration changes require restarting the application. Existing user sessions remain active during deployment.

Test your configuration

Log out of NetBox and click the Log In button at top right. You should see the normal login form as well as an option to authenticate with your provider.

Click that option. You will be redirected to your provider's authentication portal, where you can log in with your test user's credentials. You may also be prompted to grant the application access to your account.

If successful, you will be logged in as the provider's user. You can verify this by clicking your login ID in the upper right and selecting Profile.

This user account is now replicated within NetBox Enterprise, and can be assigned groups and permissions.

Assign permissions

New users have no permissions by default. To assign permissions:

1. From NetBox Enterprise, navigate to Admin > Authentication > Users (requires admin access).
2. Locate the OIDC user and assign appropriate groups or individual permissions.
3. Set Staff or Superuser status, if needed:
   • Staff: Allows access to the NetBox admin interface.
   • Superuser: Has all permissions without explicitly assigning them.

Group mapping

Automatic permission assignment from provider group membership is provider-specific, because each provider represents groups differently.

NetBox Enterprise ships authentication pipeline extensions for:

• Microsoft Entra ID Group Mapping, which matches on group object IDs
• SAML Group Mapping, which matches on group names

Group mapping for Okta is also supported. For help setting this up, or setting up group mapping for a generic OIDC provider, contact NetBox Labs support.

Troubleshooting

Redirect URI mismatch

Symptoms:

• Error message: redirect_uri_mismatch, or a provider error page stating the redirect URI is not permitted
• Error stating the redirect URI must use HTTPS

Resolution:

1. Verify the redirect URI registered with your provider matches the backend you configured, including the trailing slash:
   • Okta: https://<your-netbox-domain>/oauth/complete/okta-openidconnect/
   • Generic OIDC: https://<your-netbox-domain>/oauth/complete/oidc/
2. Check for a missing trailing slash, HTTP instead of HTTPS, the wrong domain, or extra whitespace.
3. If NetBox sits behind a reverse proxy or load balancer that terminates TLS, NetBox may not know the original request was HTTPS and will build an http:// redirect URI. Confirm the proxy forwards the original protocol headers, and set SOCIAL_AUTH_REDIRECT_IS_HTTPS = True to force HTTPS.
4. After correcting the redirect URI with your provider, wait a few minutes for the change to propagate.

Not logged in after authentication

Symptoms:

• Redirected back to NetBox after authenticating successfully
• Not logged into NetBox
• No error message displayed

Resolution:

1. Verify REMOTE_AUTH_BACKEND matches the provider you configured, and that the settings prefix matches the backend. Okta settings use SOCIAL_AUTH_OKTA_OPENIDCONNECT_; generic OIDC settings use SOCIAL_AUTH_OIDC_.
2. Verify the client ID and client secret are correct, and that you copied the secret value rather than its identifier.
3. Check NetBox logs for authentication errors:

   kubectl logs <netbox-pod> -n kotsadm | grep -i "oauth\|oidc"

Discovery endpoint not reachable

Symptoms:

• Connection timeout during authentication
• Errors fetching the OIDC configuration or the signing keys

Resolution:

1. Confirm SOCIAL_AUTH_OIDC_OIDC_ENDPOINT does not already end in /.well-known/openid-configuration.
2. Verify the NetBox pod can reach the discovery document:

   kubectl exec <netbox-pod> -n kotsadm -- curl https://<issuer-url>/.well-known/openid-configuration

3. Check that firewall rules allow outbound HTTPS and that DNS resolves from inside the cluster.

SSL certificate verification fails

Symptoms:

• Error: SSL: CERTIFICATE_VERIFY_FAILED
• Common with providers using an internal or private certificate authority

Resolution:

Add your provider's certificate authority to the NetBox trust store. Do not disable verification in production.

For development only, verification can be disabled:

SOCIAL_AUTH_VERIFY_SSL = False

Client secret expired

Symptoms:

• Authentication worked previously but now fails
• Error in logs: invalid_client, or a message about an expired secret

Resolution:

1. Generate a new client secret in your identity provider.
2. Update the secret in your NetBox configuration.
3. Deploy the updated configuration.

Prevention: Set calendar reminders ahead of secret expiration so you can rotate proactively.

Logged in but everything is denied

Symptoms:

• Authentication succeeds but pages return "You do not have permission to access this page"

Resolution:

OIDC creates the account but grants no permissions. See Assign permissions, and verify the user's Active flag is set in Admin > Authentication > Users.

Security considerations

Client secret management

• Store client secrets in the NetBox configuration and rotate them before expiration
• Use shorter expiration periods in high-security environments
• Revoke a secret immediately if it may have been exposed

Transport security

OAuth 2.0 and OIDC depend on encrypted transport for their security guarantees, so use HTTPS for both NetBox and your identity provider in production with valid TLS certificates. See TLS and Gateway Configuration.

User provisioning

• Users are automatically created on first login
• Accounts cannot be deleted via the identity provider (must be disabled in NetBox)
• Consider implementing automated deprovisioning processes for terminated employees

Session management

NetBox sessions are independent of your provider's token lifetimes. Users re-authenticate when their NetBox session expires, not when the provider's tokens do, so disabling a user in the provider prevents future logins but does not terminate an active NetBox session. To revoke access immediately, disable the account in NetBox as well.

Session lifetime is controlled by LOGIN_TIMEOUT, in seconds:

LOGIN_TIMEOUT = 3600

Audit logging

Monitor authentication events in the NetBox application log:

kubectl logs <netbox-pod> -n kotsadm | grep authentication