Microsoft Entra ID Single Sign-On

NetBox Enterprise supports single sign-on (SSO) with Microsoft Entra ID (formerly Azure Active Directory), so users can log in with their existing Microsoft credentials instead of separate NetBox account credentials.

This centralizes access control and simplifies user management, letting administrators grant or revoke NetBox access directly from Entra ID.

Prerequisites

Before configuring Entra ID authentication, ensure you have:

Microsoft Entra ID Requirements:

• Permissions to create app registrations in Entra ID
• 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)

Entra ID configuration

Register an app

Begin by registering an app for NetBox Enterprise.

1. Open the Microsoft Entra admin center and select Entra ID > App registrations in the left menu.

2. Click New registration.

3. Complete the following fields:

   • Name: Enter a name for the registration (e.g. "NetBox Enterprise").

   • Account type: Select the single-tenant option.

     Multitenant authentication

     NetBox also supports multitenant authentication via Entra ID. However, this requires a different backend and an additional configuration parameter. See Multitenant authentication below.

   • Redirect URI: Select Web and enter the path to your NetBox Enterprise installation, ending with /oauth/complete/azuread-oauth2/.

     For example: https://<your-netbox-domain>/oauth/complete/azuread-oauth2/

     Note:

     • Use HTTPS in production (HTTP only allowed for localhost testing)
     • This must match exactly what you configure in Entra ID (including the trailing slash)

   

4. Note the application (client) ID and the directory (tenant) ID. You will need these when configuring SSO from NetBox Enterprise.

   

Create a secret

1. From the page for your new NetBox app registration, select Certificates & secrets in the menu on the left.

2. Under Client secrets, click New client secret.

3. Provide a description and optionally select an expiration period.

4. After creating the secret, note its value. You will need this when configuring NetBox Enterprise.

   

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 following configuration, replacing the placeholder values:

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

• application-id is the Application (client) ID you copied from the Overview page for your NetBox app registration.
• tenant-id is the Directory (tenant) ID you copied from the Overview page for your NetBox app registration.
• client-secret-value is the Value you copied from the Certificates & secrets page for your NetBox app registration.

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 using Entra ID.

Click the option to log in with Microsoft Entra ID.

You will be redirected to Microsoft's authentication portal where you can log in with your test user's Microsoft credentials.

If successful, you will be logged in as the Entra ID 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 Entra ID 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.

For automatic permission assignment based on Entra ID groups, configure Group Mapping.

Multitenant authentication

NetBox Enterprise supports multitenant authentication for organizations using multiple Entra ID tenants. This requires a different backend configuration.

Multitenant backend:

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

When creating the app registration, select Multiple Entra ID tenants instead of single tenant.

For detailed multitenant configuration, refer to the Python Social Auth documentation.

Troubleshooting

Redirect URI mismatch

Symptoms:

• Error message: "AADSTS50011: The redirect URI specified in the request does not match the redirect URIs configured for the application"
• Redirected to Entra ID error page

Resolution:

1. Verify the redirect URI in Entra ID app registration exactly matches:

   https://<your-netbox-domain>/oauth/complete/azuread-oauth2/

2. Common issues:

   • Missing trailing slash
   • HTTP instead of HTTPS
   • Incorrect domain or path
   • Extra whitespace in configuration

3. After correcting the redirect URI in Entra ID, wait a few minutes for changes to propagate

Not logged in after authentication

Symptoms:

• Redirected back to NetBox after successful Entra ID authentication
• Not logged into NetBox
• No error message displayed

Resolution:

1. Verify the backend configuration:

   • Check that REMOTE_AUTH_BACKEND is set to 'social_core.backends.azuread.AzureADOAuth2'
   • For single-tenant apps only (not multitenant)

2. Verify credentials are correct:

   • Application (client) ID matches Entra ID
   • Client secret is the secret value (not the secret ID)
   • Tenant ID is correct

3. Check NetBox logs for authentication errors:

   kubectl logs <netbox-pod> -n kotsadm | grep -i "azure\|auth"

Client secret expired

Symptoms:

• Authentication worked previously but now fails
• Error in logs: "invalid_client" or "secret expired"

Resolution:

1. Generate a new client secret in Entra ID (Step 3)
2. Update NetBox configuration with the new secret value
3. Deploy the updated configuration

Prevention: Set calendar reminders before secret expiration to rotate secrets proactively.

HTTPS Required error

Symptoms:

• Error: "redirect_uri must be HTTPS"
• Occurs when using HTTP redirect URI

Resolution:

Production environments require HTTPS. Configure TLS for NetBox Enterprise. See TLS and Gateway Configuration.

Exception: Testing with HTTP redirect URIs using localhost or 127.0.0.1 addresses is allowed for development.

Security considerations

Client secret management

• Store client secrets securely in NetBox configuration (encrypted at rest)
• Rotate secrets before expiration
• Use appropriate expiration periods (shorter for high-security environments)
• Revoke secrets immediately if compromised

User provisioning

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

Session management

NetBox session timeout is independent of Entra ID token expiration. Users must re-authenticate when their NetBox session expires, not when Entra ID tokens expire.