SSO Configuration Reference

NetBox supports multiple SSO backends. The configuration parameters for these backends share a common pattern.

NetBox authenticates through Python Social Auth, so most parameters are prefixed SOCIAL_AUTH_ followed by the backend name.

Where to add these parameters

NetBox Enterprise, Embedded Cluster:

Admin console at https://<your-cluster-host-or-ip>:30000/, under Config > Show Advanced Settings > NetBox Python Configuration Overrides.

NetBox Enterprise, Helm:

netboxEnterprise.spec.netbox.config.customPythonConfig in your values file. See NetBox Configuration.

Backends and redirect URIs

The redirect URI always follows the pattern /oauth/complete/<backend-name>/, where the backend name is fixed by the backend class.

Provider	`REMOTE_AUTH_BACKEND`	Redirect URI
Microsoft Entra ID (single tenant)	`social_core.backends.azuread.AzureADOAuth2`	`https://<your-netbox-domain>/oauth/complete/azuread-oauth2/`
Microsoft Entra ID (multitenant)	`social_core.backends.azuread_tenant.AzureADTenantOAuth2`	`https://<your-netbox-domain>/oauth/complete/azuread-tenant-oauth2/`
Okta	`social_core.backends.okta_openidconnect.OktaOpenIdConnect`	`https://<your-netbox-domain>/oauth/complete/okta-openidconnect/`
Any OIDC provider	`social_core.backends.open_id_connect.OpenIdConnectAuth`	`https://<your-netbox-domain>/oauth/complete/oidc/`
SAML 2.0	`social_core.backends.saml.SAMLAuth`	`https://<your-netbox-domain>/oauth/complete/saml/` (the ACS URL)

Redirect URIs must use HTTPS in production and must match what you register with your provider exactly, including the trailing slash.

Common parameters

These apply regardless of which backend you choose.

Parameter	Description
`REMOTE_AUTH_BACKEND`	Python path to the authentication backend. See the table above. This is the only setting required to enable SSO: NetBox adds it to `AUTHENTICATION_BACKENDS`, which is what puts the provider's button on the login page. Local authentication remains available as a fallback.
`SOCIAL_AUTH_REDIRECT_IS_HTTPS`	Forces HTTPS in generated redirect URIs. Set to `True` when NetBox sits behind a reverse proxy or load balancer that terminates TLS. Set `False` only for localhost testing.
`SOCIAL_AUTH_VERIFY_SSL`	Defaults to `True`. Set to `False` only in development, when your provider uses a certificate NetBox cannot verify.
`SOCIAL_AUTH_BACKEND_ATTRS`	Customizes how the backend appears on the login page, as `{'<backend-name>': ('<display name>', '<icon>')}`. See Authentication.
`LOGIN_TIMEOUT`	Session lifetime in seconds. Independent of your provider's token lifetimes. See Security settings.

Settings that do not apply to SSO

Configuration generated by NetBox Enterprise also sets REMOTE_AUTH_ENABLED and REMOTE_AUTH_AUTO_CREATE_USER alongside REMOTE_AUTH_BACKEND, so you will see them in existing deployments. Neither is required for SSO, and neither affects it.

REMOTE_AUTH_AUTO_CREATE_USER is read only by NetBox's RemoteUserBackend. SSO accounts are created by the create_user step in NetBox's default authentication pipeline, which runs whether or not this setting is present.

REMOTE_AUTH_ENABLED controls only RemoteUserMiddleware, which authenticates users from a request header rather than from an identity provider. It does not gate the SSO backends, the pipeline, or the login page buttons.

REMOTE_AUTH_ENABLED trusts a request header

Setting REMOTE_AUTH_ENABLED = True tells NetBox to accept the value of the REMOTE_AUTH_HEADER request header (HTTP_REMOTE_USER by default) as the authenticated username. If the proxy in front of NetBox does not strip that header from incoming client requests, a caller can set it themselves and be authenticated as any user. Leave it unset unless you are deliberately using header-based authentication and your proxy removes the header from client traffic.

Microsoft Entra ID

Full guide: Microsoft Entra ID Single Sign-On.

Single tenant:

REMOTE_AUTH_BACKEND = 'social_core.backends.azuread.AzureADOAuth2'
SOCIAL_AUTH_AZUREAD_OAUTH2_KEY = '<application-id>'
SOCIAL_AUTH_AZUREAD_OAUTH2_SECRET = '<client-secret-value>'
SOCIAL_AUTH_AZUREAD_OAUTH2_TENANT_ID = '<tenant-id>'

Multitenant:

REMOTE_AUTH_BACKEND = 'social_core.backends.azuread_tenant.AzureADTenantOAuth2'
SOCIAL_AUTH_AZUREAD_TENANT_OAUTH2_KEY = '<application-id>'
SOCIAL_AUTH_AZUREAD_TENANT_OAUTH2_SECRET = '<client-secret-value>'
SOCIAL_AUTH_AZUREAD_TENANT_OAUTH2_TENANT_ID = '<tenant-id>'

Value	Where to find it
`application-id`	Application (client) ID on the Overview page of your app registration
`tenant-id`	Directory (tenant) ID on the Overview page of your app registration
`client-secret-value`	The Value shown on the Certificates & secrets page when the secret is created. Displayed only once.

Okta

Full guide: OpenID Connect (OIDC) Single Sign-On.

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/'

Value	Where to find it
`client-id`	Client Credentials on the General tab of your Okta application
`client-secret`	Client Credentials on the General tab of your Okta application
`okta-domain`	Settings > Account in the Okta Admin Console, for example `dev-123456.okta.com`. Append `/oauth2/` for the default authorization server, or `/oauth2/<auth-server-id>/` for a custom one.

Okta also accepts an optional sign-out redirect URI, https://<your-netbox-domain>/. NetBox never signs users out at the provider, so this value is not used during logout and the user's Okta session survives a NetBox logout.

Generic OIDC

Full guide: OpenID Connect (OIDC) Single Sign-On. Works with Keycloak, Auth0, Authentik, Google Workspace, GitLab, Dex, and other OIDC-compliant providers.

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>'

SOCIAL_AUTH_OIDC_OIDC_ENDPOINT is the issuer URL without /.well-known/openid-configuration. NetBox appends that path when it fetches the discovery document, so including it produces a doubled URL and authentication fails.

Provider	Issuer URL
Keycloak	`https://<keycloak-domain>/realms/<realm>`
Auth0	`https://<tenant>.auth0.com`
Authentik	`https://<authentik-domain>/application/o/<app-slug>`
GitLab	`https://<gitlab-domain>`

SAML 2.0

Full guide: SAML Single Sign-On.

REMOTE_AUTH_BACKEND = 'social_core.backends.saml.SAMLAuth'

# Service provider (NetBox) identity
SOCIAL_AUTH_SAML_SP_ENTITY_ID = 'https://<your-netbox-domain>'
SOCIAL_AUTH_SAML_SP_PUBLIC_CERT = """-----BEGIN CERTIFICATE-----
<contents of saml_cert.pem>
-----END CERTIFICATE-----"""
SOCIAL_AUTH_SAML_SP_PRIVATE_KEY = """-----BEGIN PRIVATE KEY-----
<contents of saml_private_key.pem>
-----END PRIVATE KEY-----"""

# Required by the SAML backend
SOCIAL_AUTH_SAML_ORG_INFO = {
    'en-US': {
        'name': '<organization-name>',
        'displayname': '<organization-display-name>',
        'url': '<organization-website>',
    }
}
SOCIAL_AUTH_SAML_TECHNICAL_CONTACT = {
    'givenName': 'Technical Support',
    'emailAddress': '<technical-contact-email>',
}
SOCIAL_AUTH_SAML_SUPPORT_CONTACT = {
    'givenName': 'Support Team',
    'emailAddress': '<support-contact-email>',
}

# Identity provider
SOCIAL_AUTH_SAML_ENABLED_IDPS = {
    'default': {
        'entity_id': '<idp-entity-id>',
        'url': '<idp-sso-url>',
        'x509cert': '<idp-certificate>',
        'attr_user_permanent_id': 'email',
        'attr_username': 'email',
        'attr_email': 'email',
        'attr_first_name': 'first_name',
        'attr_last_name': 'last_name',
    }
}

Value	Notes
`SOCIAL_AUTH_SAML_SP_ENTITY_ID`	Must match the SP entity ID registered with your IdP exactly, including whether it ends in a slash.
`SOCIAL_AUTH_SAML_SP_PUBLIC_CERT`, `SOCIAL_AUTH_SAML_SP_PRIVATE_KEY`	Pasted as triple-quoted strings so the PEM headers and line breaks survive.
`entity_id`, `url`, `x509cert`	From your IdP's SAML metadata. Unlike the SP certificate, `x509cert` is base64 data on a single line with no PEM headers.
`attr_*`	Names of attributes in the SAML assertion, not NetBox field names. Only configure the attributes your IdP actually sends; a configured attribute that is absent from the assertion causes authentication to fail.

Group mapping

Group mapping assigns NetBox groups and user flags automatically from identity provider group membership. It requires adding a mapping step to the authentication pipeline, so the pipeline must be declared in full.

Backend	Final pipeline step	Matches on
Microsoft Entra ID	`nbc_auth_extensions.azure_authentication.azuread_map_groups`	Group object IDs (GUIDs)
SAML	`nbc_auth_extensions.saml_authentication.saml_map_groups`	Group names, from the `groups` attribute

Full guides: Microsoft Entra ID Group Mapping and SAML Group Mapping.

Pipeline, identical for both backends apart from the final step:

SOCIAL_AUTH_PIPELINE = (
    'social_core.pipeline.social_auth.social_details',
    'social_core.pipeline.social_auth.social_uid',
    'social_core.pipeline.social_auth.social_user',
    'social_core.pipeline.user.get_username',
    'social_core.pipeline.social_auth.associate_by_email',
    'social_core.pipeline.user.create_user',
    'social_core.pipeline.social_auth.associate_user',
    'netbox.authentication.user_default_groups_handler',
    'social_core.pipeline.social_auth.load_extra_data',
    'social_core.pipeline.user.user_details',
    '<group-mapping-step>',
)

Do not change the order of the other steps, and keep the group mapping step last.

Microsoft Entra ID mapping, which additionally requires Microsoft Graph API access:

SOCIAL_AUTH_AZUREAD_OAUTH2_RESOURCE = 'https://graph.microsoft.com/'

SOCIAL_AUTH_PIPELINE_CONFIG = {
    'AZUREAD_USER_FLAGS_BY_GROUP': {
        'is_staff': ['<azure-group-id-for-staff>'],
        'is_superuser': ['<azure-group-id-for-superusers>'],
    },
    'AZUREAD_GROUP_MAP': {
        '<azure-group-id>': '<netbox-group-name>',
    }
}

SAML mapping:

SOCIAL_AUTH_PIPELINE_CONFIG = {
    'SAML_USER_FLAGS_BY_GROUP': {
        'is_staff': ['<idp-group-name-for-staff>'],
        'is_superuser': ['<idp-group-name-for-superusers>'],
    },
    'SAML_GROUP_MAP': {
        '<idp-group-name>': '<netbox-group-name>',
    }
}

For both backends, the NetBox groups named as values must already exist, names are case-sensitive, and memberships are cleared and rebuilt on every login.

LDAP

LDAP uses a Django authentication backend rather than Python Social Auth, with its own AUTH_LDAP_* parameter set. See LDAP Authentication.

Full configuration guides

Guide	Covers
Microsoft Entra ID Single Sign-On	Entra ID app registration, single tenant and multitenant
Microsoft Entra ID Group Mapping	Graph API permissions, group object IDs, pipeline configuration
SAML Single Sign-On	Certificate generation, IdP registration, attribute mapping
SAML Group Mapping	The `groups` attribute, pipeline configuration
OpenID Connect (OIDC) Single Sign-On	Okta and generic OIDC providers
LDAP Authentication	Directory binding, user and group search, attribute mapping

NetBox Cloud uses the same parameters, applied by NetBox Labs Support on request: Microsoft Entra ID Setup, Okta SSO Setup, SAML Configuration, Entra ID Group Mapping, Okta Group Mapping, and SAML Group Mapping.

On this page