Enterprise

SAML Single Sign-On

Configure NetBox Enterprise to authenticate users via SAML 2.0, enabling integration with identity providers like Okta, Microsoft Entra ID, OneLogin, and others.

Overview

SAML (Security Assertion Markup Language) is an XML-based standard for exchanging authentication and authorization data. NetBox acts as the service provider (SP) while your identity provider (IdP) authenticates users and issues SAML assertions.

User accounts are created automatically on first login. Permissions must be assigned manually or via group mapping.

Before You Begin

Requirements:

NetBox Enterprise v1.10 or later with admin console access
SAML 2.0 compliant identity provider with administrative access
HTTPS configured (required for production)
OpenSSL for generating service provider certificates

Network:

NetBox must be reachable by users (for redirect back from IdP)
HTTPS required for production (HTTP only allowed for localhost testing)

SAML Terminology

Term	Description
Service Provider (SP)	NetBox Enterprise - requests authentication from IdP
Identity Provider (IdP)	Authentication system (Okta, Entra ID, etc.) - authenticates users
SAML Assertion	XML document containing authentication statements, signed by IdP
ACS URL	Assertion Consumer Service - endpoint where IdP sends assertions: `https://<domain>/oauth/complete/saml/`
Entity ID	Unique identifier for SP or IdP (typically NetBox URL for SP)

Authentication Flow

User attempts to access NetBox
NetBox redirects user to IdP with SAML request
User authenticates with IdP credentials
IdP generates and signs SAML assertion
Browser posts assertion to NetBox ACS URL
NetBox validates signature using IdP public certificate
NetBox extracts user attributes and creates/updates account
User is granted access

Generate Service Provider Certificates

NetBox requires a public certificate and private key to identify itself to the IdP.

# Generate private key
openssl genpkey -algorithm RSA -out saml_private_key.pem -pkeyopt rsa_keygen_bits:2048

# Generate self-signed certificate (valid 365 days)
openssl req -new -x509 -key saml_private_key.pem -out saml_cert.pem -days 365

When prompted, provide organization information. Use NetBox domain for Common Name.

Security:

Store private key securely (never commit to version control)
Use 365-day validity periods
Document expiration dates
Rotate before expiration

Certificate Format: Certificates must be in PEM format with headers intact (-----BEGIN CERTIFICATE----- / -----END CERTIFICATE-----).

Identity Provider Configuration

Configure your IdP to recognize NetBox as a service provider.

Required Information for IdP

Provide these values to your identity provider:

ACS URL: https://<your-netbox-domain>/oauth/complete/saml/
SP Entity ID: https://<your-netbox-domain>
SP Certificate: <contents of saml_cert.pem>

User Attribute Mapping

Configure your IdP to send these attributes in SAML assertions:

SAML Attribute	IdP Property	Description
`email`	Email address	User email (used as username)
`first_name`	First name	User first name
`last_name`	Last name	User last name
`groups`	Group memberships	List of groups (for group mapping)

Provider Examples:

Provider	How to Configure
Okta	Applications > [App] > SAML Settings > Attribute Statements Add: `email=user.email`, `first_name=user.firstName`, `last_name=user.lastName` Group Attribute Statement: `groups` with filter `Matches regex: .*`
Entra ID	Enterprise apps > [App] > Single sign-on > Attributes & Claims Add: `email=user.mail`, `first_name=user.givenname`, `last_name=user.surname`, `groups=user.groups`
OneLogin	Applications > [App] > Parameters Add: `email=Email`, `first_name=First Name`, `last_name=Last Name`, `groups=User Roles`

Collect IdP Information

After configuring your IdP application, collect:

IdP Entity ID: Unique identifier for your identity provider (from metadata)

IdP SSO URL: URL where NetBox sends authentication requests (Single Sign-On URL)

IdP x509 Certificate: Public certificate for verifying signatures. Download from IdP or extract from metadata:

curl -o metadata.xml https://your-idp.com/metadata
grep -oP '(?<=<X509Certificate>).*?(?=</X509Certificate>)' metadata.xml

Certificate should be a single line of base64 data without headers.

NetBox Configuration

Access admin console at https://<cluster-host>:30000/ and navigate to Config > Show Advanced Settings > NetBox Python Configuration Overrides.

Add SAML Configuration

# Enable remote authentication
REMOTE_AUTH_ENABLED = True
REMOTE_AUTH_AUTO_CREATE_USER = True
REMOTE_AUTH_BACKEND = 'social_core.backends.saml.SAMLAuth'

# Force HTTPS for OAuth redirects (set False only for localhost testing)
SOCIAL_AUTH_REDIRECT_IS_HTTPS = True

# Service Provider configuration
SOCIAL_AUTH_SAML_SP_ENTITY_ID = "https://<your-netbox-domain>"
SOCIAL_AUTH_SAML_SP_PUBLIC_CERT = """-----BEGIN CERTIFICATE-----
<your-certificate-data-here>
-----END CERTIFICATE-----"""
SOCIAL_AUTH_SAML_SP_PRIVATE_KEY = """-----BEGIN PRIVATE KEY-----
<your-private-key-data-here>
-----END PRIVATE KEY-----"""

# Organization information (displayed in SAML metadata)
SOCIAL_AUTH_SAML_ORG_INFO = {
    "en-US": {
        "name": "<your-organization-name>",
        "displayname": "<your-organization-display-name>",
        "url": "<your-organization-website>",
    }
}

# Technical contact
SOCIAL_AUTH_SAML_TECHNICAL_CONTACT = {
    "givenName": "Technical Support",
    "emailAddress": "<technical-contact-email>"
}

# Support contact
SOCIAL_AUTH_SAML_SUPPORT_CONTACT = {
    "givenName": "Support Team",
    "emailAddress": "<support-contact-email>"
}

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

Configuration Parameters

Certificates: Use triple-quoted strings to preserve newlines. Include PEM headers for SP certificate and key. IdP certificate should be base64 data only (no headers).

Entity IDs: SP Entity ID must match the value configured in IdP exactly (including/excluding trailing slash).

Multiple IdPs: Add additional entries to SOCIAL_AUTH_SAML_ENABLED_IDPS dictionary with different keys.

Deploy

Click Save config
Click Go to updated version
Click Deploy
Wait for Ready state

Configuration changes require application restart. Existing sessions remain active.

Testing

Log out of NetBox
Navigate to login page
Click SAML authentication link
Authenticate with IdP credentials
Verify redirect to NetBox and successful login
Navigate to Admin > Users to verify account creation

Verify user details:

Username matches email address
First and last names populated
Email matches IdP

SAML Metadata

NetBox publishes SAML metadata at:

https://<your-netbox-domain>/oauth/metadata/saml/

Some identity providers can import this URL for automatic configuration. Metadata includes SP Entity ID, ACS URL, public certificate, and organization information. Attribute mappings must still be configured manually.

Assigning Permissions

Users authenticated via SAML have no permissions by default.

Manual assignment:

Navigate to Admin > Users
Locate SAML user
Assign groups or individual permissions
Set Staff status for admin interface access
Set Superuser status for full system access

Automated assignment: Configure SAML group mapping. See SAML Group Mapping for details.

Troubleshooting

kubectl Access

Commands below require cluster shell access.

SAML Response Validation Failed

Error: SAML response validation failed / signature verification errors

Resolution:

Verify IdP certificate: Remove headers and newlines (single line base64), check expiration, download fresh from metadata
Verify ACS URL matches exactly: https://<domain>/oauth/complete/saml/ (including trailing slash)
Check certificate hasn't expired

Attribute Mapping Errors

Symptoms: User logs in but username empty, first/last name missing

Resolution:

Check attribute names in IdP configuration (case-sensitive)
Verify test user has values for all required attributes (email, first_name, last_name)
Enable SAML debugging and inspect actual attribute names sent by IdP

Certificate Format Errors

Error: Could not deserialize key data / PEM routines: no start line

Resolution:

SP certificate and key must include headers and use triple-quoted strings:

SOCIAL_AUTH_SAML_SP_PUBLIC_CERT = """-----BEGIN CERTIFICATE-----
MIIDXTCCAkWgAwIBAgIJAKL0UG...
-----END CERTIFICATE-----"""

Verify certificates:

openssl x509 -in saml_cert.pem -text -noout
openssl rsa -in saml_private_key.pem -check

Entity ID Mismatch

Error: The response was received at a URL that is not configured

Resolution:

Verify SP Entity ID matches in both NetBox configuration and IdP
Common issues: trailing slash, HTTP vs HTTPS, subdomain differences
Update both to use identical values

IdP SSO URL Errors

Symptoms: Timeout or connection refused when attempting login

Resolution:

Verify IdP SSO URL is correct (check url in SOCIAL_AUTH_SAML_ENABLED_IDPS)
Test URL accessibility:
```
curl -I <idp-sso-url>
```
Check for typos, incorrect protocol, or wrong domain

User Not Logged In After Authentication

Symptoms: Redirected to NetBox but not logged in, no error message

Resolution:

Check NetBox logs:

kubectl logs <netbox-pod> -n kotsadm | grep -i saml

Verify email attribute present in SAML assertion
Confirm REMOTE_AUTH_ENABLED and REMOTE_AUTH_AUTO_CREATE_USER set to True

HTTPS Redirect Issues

Symptoms: Redirected to HTTP instead of HTTPS, login loop

Resolution:

Set SOCIAL_AUTH_REDIRECT_IS_HTTPS: True for production HTTPS
Verify reverse proxy forwards correct protocol headers
Always access NetBox via HTTPS URL

Security Considerations

HTTPS Requirement: SAML assertions contain sensitive data. Use HTTPS in production (HTTP only for localhost testing). Ensure valid TLS certificates and configure HSTS headers.

Certificate Management:

SP certificates: Encrypted in NetBox configuration. Rotate before expiration. Document expiration dates.
IdP certificates: Monitor expiration. Update NetBox configuration when IdP rotates certificates. Test authentication after updates.

Assertion Security: SAML assertions are digitally signed. Never disable signature verification. Always use current IdP certificates.

User Provisioning: Accounts created automatically on first login cannot be deleted via IdP. Implement automated deprovisioning or audit accounts regularly. Disable unused accounts manually.

Audit Logging: Monitor authentication events:

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

Overview​

Before You Begin​

SAML Terminology​

Authentication Flow​

Generate Service Provider Certificates​

Identity Provider Configuration​

Required Information for IdP​

User Attribute Mapping​

Collect IdP Information​

NetBox Configuration​

Add SAML Configuration​

Configuration Parameters​

Deploy​

Testing​

SAML Metadata​

Assigning Permissions​

Troubleshooting​

SAML Response Validation Failed​

Attribute Mapping Errors​

Certificate Format Errors​

Entity ID Mismatch​

IdP SSO URL Errors​

User Not Logged In After Authentication​

HTTPS Redirect Issues​

Security Considerations​

Related Documentation​

Overview

Before You Begin

SAML Terminology

Authentication Flow

Generate Service Provider Certificates

Identity Provider Configuration

Required Information for IdP

User Attribute Mapping

Collect IdP Information

NetBox Configuration

Add SAML Configuration

Configuration Parameters

Deploy

Testing

SAML Metadata

Assigning Permissions

Troubleshooting

SAML Response Validation Failed

Attribute Mapping Errors

Certificate Format Errors

Entity ID Mismatch

IdP SSO URL Errors

User Not Logged In After Authentication

HTTPS Redirect Issues

Security Considerations

Related Documentation