# Microsoft Entra ID Single Sign-On (/docs/enterprise/nbe-azure-sso)















Configure NetBox Enterprise to authenticate users via Microsoft Entra ID (formerly Azure Active Directory) using OAuth 2.0. This guide covers basic SSO setup. For group-based permission assignment, see [Entra ID Group Mapping](/enterprise/nbe-azure-group-mapping/).

<Callout type="info" title="Applies to both deployment methods">
  This guide shows configuration via the **Embedded Cluster** Admin Console. For **Helm** deployments, add the same Python configuration to `netboxEnterprise.spec.netbox.config.customPythonConfig` in your values file. See [NetBox Configuration](/enterprise/helm/configuration/netbox) for details.
</Callout>

## Prerequisites [#prerequisites]

Before configuring Entra ID authentication, ensure you have:

**Microsoft Entra ID Requirements:**

* Azure subscription with Entra ID (formerly Azure AD)
* 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)

## Understanding the Redirect URI [#understanding-the-redirect-uri]

The redirect URI is where Entra ID sends users after authentication. NetBox Enterprise uses the following pattern:

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

This URI must:

* Use HTTPS in production (HTTP only allowed for localhost testing)
* Match exactly what you configure in Entra ID (including the trailing slash)
* Be accessible from user browsers

## Microsoft Entra ID Configuration [#microsoft-entra-id-configuration]

### Step 1: Create App Registration [#step-1-create-app-registration]

1. Sign in to the [Microsoft Entra admin center](https://entra.microsoft.com/)
2. Navigate to **Identity > Applications > App registrations**
3. Click **New registration**
4. Configure the application:
   * **Name**: NetBox Enterprise (or your preferred name)
   * **Supported account types**: Accounts in this organizational directory only (Single tenant)
   * **Redirect URI**:
     * Platform: **Web**
     * URI: `https://<your-netbox-domain>/oauth/complete/azuread-oauth2/`

<img alt="App registration form" src="__img0" />

5. Click **Register**

### Step 2: Note Application Identifiers [#step-2-note-application-identifiers]

After registration, note the following values from the Overview page:

* **Application (client) ID**: Used in NetBox configuration as `SOCIAL_AUTH_AZUREAD_OAUTH2_KEY`
* **Directory (tenant) ID**: Used in NetBox configuration as `SOCIAL_AUTH_AZUREAD_OAUTH2_TENANT_ID`

<img alt="App registration overview" src="__img1" />

### Step 3: Create Client Secret [#step-3-create-client-secret]

1. In your app registration, navigate to **Certificates & secrets**
2. Select the **Client secrets** tab
3. Click **New client secret**
4. Configure the secret:
   * **Description**: NetBox Enterprise (optional)
   * **Expires**: Select appropriate expiration period for your security requirements
5. Click **Add**
6. Copy the **Value** (not the Secret ID) immediately

<img alt="Client secret creation" src="__img2" />

**Important:** The secret value is only displayed once. Store it securely. If you lose it, you must generate a new secret.

### Step 4: Configure Token Claims (Optional) [#step-4-configure-token-claims-optional]

For group-based access control (covered in [Group Mapping](/enterprise/nbe-azure-group-mapping/)), configure optional claims:

1. Navigate to **Token configuration** in your app registration
2. Click **Add optional claim**
3. Select **ID** token type
4. Add the `groups` claim
5. Check **Turn on the Microsoft Graph groups claim**
6. Select **Security groups** or **All groups** based on your requirements

## NetBox Enterprise Configuration [#netbox-enterprise-configuration]

### Accessing Configuration [#accessing-configuration]

1. Access the admin console at `https://<your-cluster-host-or-ip>:30000/`
2. Navigate to the **Config** tab
3. Enable **Show Advanced Settings**
4. Locate the **NetBox Python Configuration Overrides** section

<img alt="Advanced settings location" src="__img3" />

### Adding Entra ID Configuration [#adding-entra-id-configuration]

Add the following configuration, replacing the placeholder values:

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

**Configuration parameters:**

* `REMOTE_AUTH_BACKEND`: Specifies the authentication backend (do not modify)
* `SOCIAL_AUTH_AZUREAD_OAUTH2_KEY`: Application (client) ID from Step 2
* `SOCIAL_AUTH_AZUREAD_OAUTH2_SECRET`: Client secret value from Step 3
* `SOCIAL_AUTH_AZUREAD_OAUTH2_TENANT_ID`: Directory (tenant) ID from Step 2

### Deploying Configuration [#deploying-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 application restart. Existing user sessions remain active during deployment.

## Testing Authentication [#testing-authentication]

### Initial Login [#initial-login]

1. Open NetBox Enterprise in a browser
2. Log out if currently authenticated
3. Click **Log In** at the top right
4. Verify the login page displays an option to authenticate using Entra ID

<img alt="NetBox login page with Entra ID option" src="__img4" />

5. Click the Entra ID authentication link
6. You will be redirected to Microsoft's authentication portal
7. Enter your Entra ID credentials

<img alt="Microsoft authentication portal" src="__img5" />

8. You may be prompted to grant NetBox Enterprise access to your profile
9. After successful authentication, you will be redirected to NetBox

### Verifying User Creation [#verifying-user-creation]

After first login:

1. Verify you are logged in by checking the username at the top right
2. Navigate to your user profile (click your username, select **Profile**)
3. Verify your user details match your Entra ID account

Users are automatically created in NetBox on first login. The local user account is linked to the Entra ID account for subsequent authentications.

### Assigning Permissions [#assigning-permissions]

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

1. Navigate to **Admin > Authentication > Users** (requires admin access)
2. Locate the Entra ID user
3. Assign appropriate groups or individual permissions
4. Set **Staff status** if the user needs admin panel access
5. Set **Superuser status** if the user needs full system access

For automatic permission assignment based on Entra ID groups, configure [Group Mapping](/enterprise/nbe-azure-group-mapping/).

## Multitenant Authentication [#multitenant-authentication]

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

**Multitenant backend:**

```python
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 &#x2A;*Accounts in any organizational directory (Any Azure AD directory - Multitenant)** instead of single tenant.

For detailed multitenant configuration, refer to the [Python Social Auth documentation](https://python-social-auth.readthedocs.io/en/latest/backends/azuread.html#tenant-support).

## Troubleshooting [#troubleshooting]

### Redirect URI Mismatch [#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 [#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:
   ```shell
   kubectl logs <netbox-pod> -n kotsadm | grep -i "azure\|auth"
   ```

### Client Secret Expired [#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 [#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](/enterprise/nbe-tls-ingress/).

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

## Security Considerations [#security-considerations]

### Client Secret Management [#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 [#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 [#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.

## Related Documentation [#related-documentation]

* [Entra ID Group Mapping](/enterprise/nbe-azure-group-mapping/) - Configure group-based access control
* [OpenID Connect (OIDC) SSO](/enterprise/nbe-oidc-sso/) - Alternative OAuth 2.0 configuration
* [SAML Single Sign-On](/enterprise/nbe-saml/) - Alternative SSO method using SAML 2.0
* [TLS and Gateway Configuration](/enterprise/nbe-tls-ingress/) - Configure HTTPS for NetBox Enterprise

## Additional Resources [#additional-resources]

* [Microsoft Entra ID Documentation](https://learn.microsoft.com/en-us/entra/identity/)
* [Python Social Auth Azure AD Backend](https://python-social-auth.readthedocs.io/en/latest/backends/azuread.html)
* [OAuth 2.0 Authorization Code Flow](https://learn.microsoft.com/en-us/entra/identity-platform/v2-oauth2-auth-code-flow)