docs: Update SSO pages for Netbox

docs/administration/authentication/google.md

@@ -1,27 +1,75 @@
 # Google
 
-This guide explains how to configure single sign-on (SSO) support for NetBox using [Google OAuth2](https://developers.google.com/identity/protocols/oauth2/web-server) as an authentication backend.
+NetBox supports single sign-on (SSO) with Google, so users can log in with their existing Google credentials instead of separate NetBox account credentials.
 
-## Google OAuth2 Configuration
+This centralizes access control and simplifies user management, letting administrators grant or revoke NetBox access directly from Google.
 
-1. Log into [console.cloud.google.com](https://console.cloud.google.com/).
-2. Create new project for NetBox.
-3. Under "APIs and Services" click "OAuth consent screen" and enter the required information.
-4. Under "Credentials," click "Create Credentials" and select "OAuth 2.0 Client ID." Select type "Web application."
-    - "Authorized JavaScript origins" should follow the format `http[s]://<netbox>[:<port>]`
-    - "Authorized redirect URIs" should follow the format `http[s]://<netbox>[:<port>]/oauth/complete/google-oauth2/`
-5. Copy the "Client ID" and "Client Secret" values somewhere convenient.
+For more information, see [Using OAuth 2.0 for Web Server Applications](https://developers.google.com/identity/protocols/oauth2/web-server).
+
+## Prerequisites
+
+Before configuring Google authentication, ensure you have:
+
+**Google requirements:**
+
+* A Google Cloud project, and permission to create OAuth credentials within it
+* Test user account for validation (optional but recommended)
+
+**NetBox requirements:**
+
+* Access to `configuration.py` and permission to restart the NetBox services
+* HTTPS configured for production deployments
+* Your NetBox URL (used for redirect URI configuration)
 
 !!! note
-    Google requires the NetBox hostname to use a public top-level-domain (e.g. `.com`, `.net`). The use of IP addresses is not permitted (except `127.0.0.1`).
+    Google requires the NetBox hostname to use a public top-level domain (e.g. `.com`, `.net`). The use of IP addresses is not permitted (except `127.0.0.1`).
+
+## Google configuration
+
+### Configure the consent screen
+
+1. Log into the [Google Cloud console](https://console.cloud.google.com/) and create a new project for NetBox, or select an existing one.
+
+2. Under **APIs & Services**, open the **OAuth consent screen**.
+
+3. Select the user type:
+
+    * **Internal**: Only users within your Google Workspace organization can log in. This option is available only to Workspace customers.
+    * **External**: Any Google account can log in, subject to the publishing status described below.
+
+4. Enter the required app information, such as the app name, user support email, and developer contact address.
+
+!!! note "Publishing status"
+    While an external app's publishing status is **Testing**, only the accounts listed as test users on the consent screen can log in; everyone else is refused. Publish the app when you are ready to allow general access.
+
+### Create OAuth credentials
 
-For more information, consult [Google's documentation](https://developers.google.com/identity/protocols/oauth2/web-server#prerequisites).
+1. Under **APIs & Services**, open **Credentials**, click **Create Credentials**, and select **OAuth client ID**.
 
-## NetBox Configuration
+2. Select **Web application** as the application type.
 
-### 1. Enter configuration parameters
+3. Complete the following fields:
 
-Enter the following configuration parameters in `configuration.py`, substituting your own values:
+    * **Name**: Enter a name for the client (e.g. "NetBox").
+
+    * **Authorized JavaScript origins**: Enter the URL of your NetBox installation.
+
+        For example: `https://<your-netbox-domain>`
+
+    * **Authorized redirect URIs**: Enter the path to your NetBox installation, ending with `/oauth/complete/google-oauth2/`.
+
+        For example: `https://<your-netbox-domain>/oauth/complete/google-oauth2/`
+
+4. Click **Create**, then note the **Client ID** and **Client secret**. You will need these when configuring NetBox.
+
+!!! warning
+    Treat the client secret as a credential. Store it securely, and rotate it if it may have been exposed.
+
+## NetBox configuration
+
+### Enter configuration parameters
+
+Add the following configuration to `configuration.py`, substituting your own values:
 
 ```python
 REMOTE_AUTH_BACKEND = 'social_core.backends.google.GoogleOAuth2'
@@ -29,9 +77,22 @@ SOCIAL_AUTH_GOOGLE_OAUTH2_KEY = '{CLIENT_ID}'
 SOCIAL_AUTH_GOOGLE_OAUTH2_SECRET = '{CLIENT_SECRET}'
 ```
 
-### 2. Restart NetBox
+* `CLIENT_ID` is the **Client ID** you copied from the **Credentials** page for your NetBox OAuth client.
+* `CLIENT_SECRET` is the **Client secret** you copied from the **Credentials** page for your NetBox OAuth client.
+
+### Restrict access by domain (optional)
+
+An external OAuth client accepts any Google account by default. To limit logins to one or more domains, add the following to `configuration.py`:
+
+```python
+SOCIAL_AUTH_GOOGLE_OAUTH2_WHITELISTED_DOMAINS = ['example.com']
+```
+
+Individual addresses may be permitted with `SOCIAL_AUTH_GOOGLE_OAUTH2_WHITELISTED_EMAILS`. See the [python-social-auth documentation](https://python-social-auth.readthedocs.io/en/latest/backends/google.html) for details.
 
-Restart the NetBox services so that the new configuration takes effect. This is typically done with the command below:
+### Restart NetBox
+
+Configuration changes require restarting the application. This is typically done with the command below:
 
 ```no-highlight
 sudo systemctl restart netbox
@@ -39,14 +100,71 @@ sudo systemctl restart netbox
 
 ## Testing
 
-Log out of NetBox if already authenticated, and click the "Log In" button at top right. You should see the normal login form as well as an option to authenticate using Google. Click that link.
+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 Google.
+
+Click the option to log in with Google.
 
 ![NetBox Google login form](../../media/authentication/netbox_google_login.png)
 
-You should be redirected to Google's authentication portal. Enter the username/email and password of your test account to continue. You may also be prompted to grant this application access to your account.
+You will be redirected to Google's authentication portal where you can log in with your test user's Google credentials. You may also be prompted to grant this application access to your account.
+
+![Google login portal](../../media/authentication/google_login_portal.png)
+
+If successful, you will be redirected back to the NetBox UI, and will be logged in as the Google 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, and can be assigned groups and permissions.
+
+## Assign permissions
+
+New users have no permissions by default. To assign permissions:
+
+1. From NetBox, navigate to **Admin > Authentication > Users** (requires admin access).
+
+2. Locate the Google user and assign appropriate groups or individual [permissions](../permissions.md).
+
+3. Set [staff or superuser status](../../models/users/user.md), if needed:
+
+    * **Staff**: Allows the user to log into the legacy Django admin site. Most NetBox functionality is exposed via the standard UI, so staff status is rarely needed.
+    * **Superuser**: Grants the user all permissions implicitly, bypassing all permission checks.
+
+!!! warning "Security considerations"
+    Exercise extreme caution when configuring Superuser users or groups.
+
+    Superusers have unrestricted access to NetBox and can:
+
+    * Modify any data, including configuration
+    * Elevate other users to superuser status
+
+## Troubleshooting
+
+### Redirect URI does not match
+
+Google requires that the authenticating client request a redirect URI that matches one of the authorized redirect URIs you configured for the OAuth client. A mismatch produces a `redirect_uri_mismatch` error.
+
+This URI must begin with `https://` (unless using `127.0.0.1` for development) and must match **exactly** what you configured in Google (including the trailing slash). The redirect URI is where Google sends users after authentication. NetBox uses the following pattern:
+
+```text
+https://<your-netbox-domain>/oauth/complete/google-oauth2/
+```
+
+If Google complains that the requested URI starts with `http://` (not HTTPS), it's likely that your HTTP server is misconfigured or sitting behind a load balancer, so NetBox is not aware that HTTPS is being used. To force the use of an HTTPS redirect URI, set the following in `configuration.py` per the [python-social-auth docs](https://python-social-auth.readthedocs.io/en/latest/configuration/settings.html#processing-redirects-and-urlopen):
+
+```python
+SOCIAL_AUTH_REDIRECT_IS_HTTPS = True
+```
+
+Note that changes to an OAuth client in the Google Cloud console can take some time to propagate.
+
+### Access blocked during authentication
+
+If Google refuses the login with an error such as "access_denied" before the user reaches NetBox, the account is not permitted to use the OAuth client.
+
+Check the consent screen configuration: an app with a publishing status of **Testing** admits only the accounts listed as test users, and an **Internal** app admits only accounts within your Google Workspace organization. Add the account as a test user, publish the app, or adjust the user type as appropriate.
+
+### Not logged in after authenticating
 
-![NetBox Google login form](../../media/authentication/google_login_portal.png)
+If you are redirected to the NetBox UI after authenticating successfully, but are not logged in, double-check the `REMOTE_AUTH_BACKEND` value configured in `configuration.py` against your Google OAuth client.
 
-If successful, you will be redirected back to the NetBox UI, and will be logged in as the Google user. You can verify this by navigating to your profile (using the button at top right).
+The instructions provided above are only applicable to the `google.GoogleOAuth2` backend. Confirm too that `SOCIAL_AUTH_GOOGLE_OAUTH2_KEY` matches the client ID in Google, and that `SOCIAL_AUTH_GOOGLE_OAUTH2_SECRET` is the secret value rather than its ID.
 
-This user account has been replicated locally to NetBox, and can now be assigned groups and permissions.
+If you have restricted access by domain, confirm that the account's domain appears in `SOCIAL_AUTH_GOOGLE_OAUTH2_WHITELISTED_DOMAINS`.

docs/administration/authentication/overview.md → docs/administration/authentication/index.md

@@ -37,7 +37,9 @@ Optionally, user profile information can be supplied by `REMOTE_USER_FIRST_NAME`
 REMOTE_AUTH_BACKEND = 'social_core.backends.google.GoogleOAuth2'
 ```
 
-NetBox supports single sign-on authentication via the [python-social-auth](https://github.com/python-social-auth) library. To enable SSO, specify the path to the desired authentication backend within the `social_core` Python package. Please see the complete list of [supported authentication backends](https://github.com/python-social-auth/social-core/tree/master/social_core/backends) for the available options.
+NetBox supports single sign-on authentication via the [python-social-auth](https://github.com/python-social-auth) library. 
+
+To enable SSO, specify the path to the desired authentication backend within the `social_core` Python package. See the complete list of [supported authentication backends](https://github.com/python-social-auth/social-core/tree/master/social_core/backends) for the available options.
 
 Most remote authentication backends require some additional configuration through settings prefixed with `SOCIAL_AUTH_`. These will be automatically imported from NetBox's `configuration.py` file. Additionally, the [authentication pipeline](https://python-social-auth.readthedocs.io/en/latest/pipeline.html) can be customized via the `SOCIAL_AUTH_PIPELINE` parameter. (NetBox's default pipeline is defined in `netbox/settings.py` for your reference.)
 

docs/administration/authentication/microsoft-entra-id.md

@@ -1,51 +1,83 @@
 # Microsoft Entra ID
 
-This guide explains how to configure single sign-on (SSO) support for NetBox using [Microsoft Entra ID](https://www.microsoft.com/en-us/security/business/identity-access/microsoft-entra-id) as an authentication backend.
+NetBox supports single sign-on (SSO) with [Microsoft Entra ID](https://www.microsoft.com/en-us/security/business/identity-access/microsoft-entra-id) (formerly Azure Active Directory), so users can log in with their existing Microsoft credentials instead of separate NetBox account credentials.
 
-## Entra ID Configuration
+This centralizes access control and simplifies user management, letting administrators grant or revoke NetBox access directly from Entra ID.
 
-### 1. Create a test user (optional)
+## Prerequisites
 
-Create a new user in AD to be used for testing. You can skip this step if you already have a suitable account created.
+Before configuring Entra ID authentication, ensure you have:
 
-### 2. Create an app registration
+**Microsoft Entra ID requirements:**
 
-Under the Azure Active Directory dashboard, navigate to **Add > App registration**.
+* Permissions to create app registrations in Entra ID
+* Test user account for validation (optional but recommended)
 
-![Add an app registration](../../media/authentication/azure_ad_add_app_registration.png)
+**NetBox requirements:**
 
-Enter a name for the registration (e.g. "NetBox") and ensure that the "single tenant" option is selected.
+* Access to `configuration.py` and permission to restart the NetBox services
+* HTTPS configured for production deployments
+* Your NetBox URL (used for redirect URI configuration)
 
-Under "Redirect URI", select "Web" for the platform and enter the path to your NetBox installation, ending with `/oauth/complete/azuread-oauth2/`. Note that this URI **must** begin with `https://` unless you are referencing localhost (for development purposes).
+## Entra ID configuration
 
-![App registration parameters](../../media/authentication/azure_ad_app_registration.png)
+!!! tip
+    We recommend that you first [create a new Entra ID user](https://learn.microsoft.com/en-us/entra/fundamentals/how-to-create-delete-users) for testing.
 
-Once finished, make note of the application (client) ID; this will be used when configuring NetBox.
+    You can skip this step if you already have a suitable account created.
 
-![Completed app registration](../../media/authentication/azure_ad_app_registration_created.png)
+### Register an app
 
-!!! tip "Multitenant authentication"
-    NetBox also supports multitenant authentication via Azure AD; however, it requires a different backend and an additional configuration parameter. Please see the [`python-social-auth` documentation](https://python-social-auth.readthedocs.io/en/latest/backends/azuread.html#tenant-support) for details concerning multitenant authentication.
+Begin by registering an app for NetBox.
 
-### 3. Create a secret
+1. Open the [Microsoft Entra admin center](https://entra.microsoft.com/#home) and select **Entra ID > App registrations** in the left menu.
 
-When viewing the newly-created app registration, click the "Add a certificate or secret" link under "Client credentials". Under the "Client secrets" tab, click the "New client secret" button.
+2. Click **New registration**.
 
-![Add a client secret](../../media/authentication/azure_ad_add_client_secret.png)
+3. Complete the following fields:
 
-You can optionally specify a description and select a lifetime for the secret.
+    * **Name**: Enter a name for the registration (e.g. "NetBox").
 
-![Client secret parameters](../../media/authentication/azure_ad_client_secret.png)
+    * **Account type**: Select the single-tenant option.
 
-Once finished, make note of the secret value (not the secret ID); this will be used when configuring NetBox.
+        !!! tip "Multitenant authentication"
+            NetBox also supports multitenant authentication via Entra ID. However, this requires a different backend and an additional configuration parameter. See [Multitenant authentication](#multitenant-authentication) below.
 
-![Client secret parameters](../../media/authentication/azure_ad_client_secret_created.png)
+    * **Redirect URI**: Select **Web** and enter the path to your NetBox installation, ending with `/oauth/complete/azuread-oauth2/`.
 
-## NetBox Configuration
+        For example: `https://<your-netbox-domain>/oauth/complete/azuread-oauth2/`
 
-### 1. Enter configuration parameters
+        Note:
 
-Enter the following configuration parameters in `configuration.py`, substituting your own values:
+        * Use HTTPS in production (HTTP only allowed for localhost testing)
+        * This must match exactly what you configure in Entra ID (including the trailing slash)
+
+    ![App registration parameters](../../media/authentication/azure_ad_app_registration.png)
+
+4. Note the application (client) ID and the directory (tenant) ID. You will need these when configuring SSO from NetBox.
+
+    ![Completed app registration](../../media/authentication/azure_ad_app_registration_created.png)
+
+### 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** (not the secret ID). You will need this when configuring NetBox.
+
+    ![Created client secret](../../media/authentication/azure_ad_client_secret_created.png)
+
+!!! warning
+    This value is only displayed once; copy it immediately.
+
+## NetBox configuration
+
+### Enter configuration parameters
+
+Add the following configuration to `configuration.py`, replacing the placeholder values:
 
 ```python
 REMOTE_AUTH_BACKEND = 'social_core.backends.azuread.AzureADOAuth2'
@@ -53,9 +85,15 @@ SOCIAL_AUTH_AZUREAD_OAUTH2_KEY = '{APPLICATION_ID}'
 SOCIAL_AUTH_AZUREAD_OAUTH2_SECRET = '{SECRET_VALUE}'
 ```
 
-### 2. Restart NetBox
+* `APPLICATION_ID` is the **Application (client) ID** you copied from the **Overview** page for your NetBox app registration.
+* `SECRET_VALUE` is the **Value** you copied from the **Certificates & secrets** page for your NetBox app registration.
+
+!!! note
+    If you are deploying multitenant authentication, you will need to use a different `REMOTE_AUTH_BACKEND` backend. See [Multitenant authentication](#multitenant-authentication) below.
 
-Restart the NetBox services so that the new configuration takes effect. This is typically done with the command below:
+### Restart NetBox
+
+Configuration changes require restarting the application. This is typically done with the command below:
 
 ```no-highlight
 sudo systemctl restart netbox
@@ -63,26 +101,86 @@ sudo systemctl restart netbox
 
 ## Testing
 
-Log out of NetBox if already authenticated, and click the "Log In" button at top right. You should see the normal login form as well as an option to authenticate using Azure AD. Click that link.
+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.
+
+![NetBox Entra ID login form](../../media/authentication/netbox_azure_ad_login.png)
+
+You will be redirected to Microsoft's authentication portal where you can log in with your test user's Microsoft credentials. You may also be prompted to grant this application access to your account.
+
+![Microsoft authentication portal](../../media/authentication/azure_ad_login_portal.png)
+
+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, and can be assigned groups and permissions.
+
+## Assign permissions
 
-![NetBox Azure AD login form](../../media/authentication/netbox_azure_ad_login.png)
+New users have no permissions by default. To assign permissions:
 
-You should be redirected to Microsoft's authentication portal. Enter the username/email and password of your test account to continue. You may also be prompted to grant this application access to your account.
+1. From NetBox, navigate to **Admin > Authentication > Users** (requires admin access).
 
-![NetBox Azure AD login form](../../media/authentication/azure_ad_login_portal.png)
+2. Locate the Entra ID user and assign appropriate groups or individual [permissions](../permissions.md).
 
-If successful, you will be redirected back to the NetBox UI, and will be logged in as the AD user. You can verify this by navigating to your profile (using the button at top right).
+3. Set [staff or superuser status](../../models/users/user.md), if needed:
 
-This user account has been replicated locally to NetBox, and can now be assigned groups and permissions.
+    * **Staff**: Allows the user to log into the legacy Django admin site. Most NetBox functionality is exposed via the standard UI, so staff status is rarely needed.
+    * **Superuser**: Grants the user all permissions implicitly, bypassing all permission checks.
+
+!!! warning "Security considerations"
+    Exercise extreme caution when configuring Superuser users or groups.
+
+    Superusers have unrestricted access to NetBox and can:
+
+    * Modify any data, including configuration
+    * Elevate other users to superuser status
+
+## Multitenant authentication
+
+NetBox 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 = '{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](https://python-social-auth.readthedocs.io/en/latest/backends/azuread.html#tenant-support).
 
 ## Troubleshooting
 
-### Redirect URI does not Match
+### Redirect URI does not match
+
+Entra ID requires that the authenticating client request a redirect URI that matches the one you configured for the app registration.
+
+This URI must begin with `https://` (unless using `localhost` for the domain) and must match **exactly** what you configured in Entra ID (including the trailing slash). The redirect URI is where Entra ID sends users after authentication. NetBox uses the following pattern:
+
+```text
+https://<your-netbox-domain>/oauth/complete/azuread-oauth2/
+```
+
+If Entra ID complains that the requested URI starts with `http://` (not HTTPS), it's likely that your HTTP server is misconfigured or sitting behind a load balancer, so NetBox is not aware that HTTPS is being used. To force the use of an HTTPS redirect URI, set the following in `configuration.py` per the [python-social-auth docs](https://python-social-auth.readthedocs.io/en/latest/configuration/settings.html#processing-redirects-and-urlopen):
+
+```python
+SOCIAL_AUTH_REDIRECT_IS_HTTPS = True
+```
+
+### Not logged in after authenticating
+
+If you are redirected to the NetBox UI after authenticating successfully, but are not logged in, double-check the `REMOTE_AUTH_BACKEND` value configured in `configuration.py` against your Entra ID app registration.
+
+The instructions provided above are only applicable to the `azuread.AzureADOAuth2` backend using a single-tenant app registration. Confirm too that `SOCIAL_AUTH_AZUREAD_OAUTH2_KEY` matches the application (client) ID in Entra ID, and that `SOCIAL_AUTH_AZUREAD_OAUTH2_SECRET` is the secret value rather than its ID.
 
-Azure requires that the authenticating client request a redirect URI that matches what you've configured for the app in step two. This URI **must** begin with `https://` (unless using `localhost` for the domain).
+### Expired client secret
 
-If Azure complains that the requested URI starts with `http://` (not HTTPS), it's likely that your HTTP server is misconfigured or sitting behind a load balancer, so NetBox is not aware that HTTPS is being use. To force the use of an HTTPS redirect URI, set `SOCIAL_AUTH_REDIRECT_IS_HTTPS = True` in `configuration.py` per the [python-social-auth docs](https://python-social-auth.readthedocs.io/en/latest/configuration/settings.html#processing-redirects-and-urlopen).
+If authentication fails and you see an error such as "invalid_client" or "secret expired", this means your client secret has expired.
 
-### Not Logged in After Authenticating
+Generate a new client secret in Entra ID, update `configuration.py` with the new value, and restart the NetBox services.
 
-If you are redirected to the NetBox UI after authenticating successfully, but are _not_ logged in, double-check the configured backend and app registration. The instructions in this guide pertain only to the `azuread.AzureADOAuth2` backend using a single-tenant app registration.
+To prevent this, we recommend setting a calendar reminder to rotate and update your secret.

docs/administration/authentication/okta.md

@@ -1,55 +1,105 @@
 # Okta
 
-This guide explains how to configure single sign-on (SSO) support for NetBox using [Okta](https://www.okta.com/) as an authentication backend.
+NetBox supports single sign-on (SSO) with [Okta](https://www.okta.com/), so users can log in with their existing Okta credentials instead of separate NetBox account credentials.
 
-## Okta Configuration
+This centralizes access control and simplifies user management, letting administrators grant or revoke NetBox access directly from Okta.
 
-!!! tip "Okta developer account"
-    Okta offers free developer accounts at <https://developer.okta.com/>.
+For more information, see [OpenID Connect app integrations](https://help.okta.com/en-us/content/topics/apps/apps-about-oidc.htm). Okta also offers [free developer accounts](https://developer.okta.com/) if you want to evaluate SSO before rolling it out.
 
-### 1. Create a test user (optional)
+## Prerequisites
 
-Create a new user in the Okta admin portal to be used for testing. You can skip this step if you already have a suitable account created.
+Before configuring Okta authentication, ensure you have:
 
-### 2. Create an app registration
+**Okta requirements:**
 
-Within the Okta administration dashboard, navigate to  **Applications > Applications**, and click the "Create App Integration" button. Select "OIDC" as the sign-in method, and "Web application" for the application type.
+* Permission to create app integrations in the Okta Admin Console
+* Test user account for validation (optional but recommended)
 
-![Create an app registration](../../media/authentication/okta_create_app_registration.png)
+**NetBox requirements:**
 
-On the next page, give the app integration a name (e.g. "NetBox") and specify the sign-in and sign-out URIs. These URIs should follow the formats below:
+* Access to `configuration.py` and permission to restart the NetBox services
+* HTTPS configured for production deployments
+* Your NetBox URL (used for redirect URI configuration)
 
-* Sign-in URI: `https://{netbox}/oauth/complete/okta-openidconnect/`
-* Sign-out URI: `https://{netbox}/oauth/disconnect/okta-openidconnect/`
+## Okta configuration
 
-![Web app integration](../../media/authentication/okta_web_app_integration.png)
+!!! tip
+    We recommend that you first [create a new Okta user](https://help.okta.com/en-us/content/topics/users-groups-profiles/usgp-add-users.htm) for testing.
 
-Under "Assignments," select the controlled access setting most appropriate for your organization. Click "Save" to complete the creation.
+    You can skip this step if you already have a suitable account created.
 
-Once finished, note the following parameters. These will be used to configured NetBox.
+### Create an app integration
 
-* Client ID
-* Client secret
-* Okta domain
+1. In the Okta Admin Console, select **Applications and Resources > Applications** in the left menu.
 
-![Okta integration parameters](../../media/authentication/okta_integration_parameters.png)
+2. Click **Create App Integration**.
 
-## NetBox Configuration
+3. Select **OIDC - OpenID Connect** as the sign-in method and **Web Application** as the application type, then click **Next**.
 
-### 1. Enter configuration parameters
+    ![Create an app registration](../../media/authentication/okta_create_app_registration.png)
 
-Enter the following configuration parameters in `configuration.py`, substituting your own values:
+4. Complete the following fields:
+
+    * **App integration name**: Enter a name for the integration (e.g. "NetBox").
+
+    * **Grant type**: Select **Authorization Code**.
+
+    * **Sign-in redirect URIs**: Enter the path to your NetBox installation, ending with `/oauth/complete/okta-openidconnect/`.
+
+        For example: `https://<your-netbox-domain>/oauth/complete/okta-openidconnect/`
+
+    * **Sign-out redirect URIs**: `https://<your-netbox-domain>/oauth/disconnect/okta-openidconnect/`
+
+    * **Assignments**: Under **Controlled access**, choose how users get access to NetBox:
+
+        * **Limit access to selected groups**: Enter the names of the groups that should have access.
+        * **Allow everyone in your organization to access**: Any user in your Okta org can log in.
+        * **Skip group assignment for now**: Nobody can log in until you assign users or groups on the integration's **Assignments** tab.
+
+    ![Web app integration](../../media/authentication/okta_web_app_integration.png)
+
+5. Click **Save**.
+
+!!! warning "Note on Federation Broker Mode"
+    Selecting **Allow everyone in your organization to access** offers **Enable immediate access with Federation Broker Mode**. That mode provides [SSO without pre-assigning the app to users](https://help.okta.com/oie/en-us/content/topics/apps/apps-fbm-main.htm). In this mode, the integration's sign-on policy alone governs access, so Okta keeps no assignment records and there is nothing for your groups to be assigned to. Okta [doesn't support group assignments](https://help.okta.com/oie/en-us/content/topics/apps/apps-fbm-known-issues.htm) in this mode, and NetBox won't appear on your users' Okta End-User Dashboard.
+
+    You can [disable Federation Broker Mode](https://help.okta.com/oie/en-us/content/topics/apps/apps-fbm-disable.htm) later from the **Federation Broker Mode** section of the integration's **General** tab. Okta restores assignments once the background process finishes.
+
+### Note the integration parameters
+
+1. From the page for your new NetBox app integration, select the **General** tab.
+
+2. Under **Client Credentials**, note the **Client ID** and the **Client secret**. You will need these when configuring NetBox.
+
+    ![Okta integration parameters](../../media/authentication/okta_integration_parameters.png)
+
+3. Note your Okta domain, shown under **Settings > Account** in the Admin Console and in the account menu at top right (for example, `dev-123456.okta.com`).
+
+!!! warning
+    Treat the client secret as a credential. Store it securely, and rotate it if it may have been exposed.
+
+## NetBox configuration
+
+### Enter configuration parameters
+
+Add the following configuration to `configuration.py`, substituting your own values:
 
 ```python
 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/'
+SOCIAL_AUTH_OKTA_OPENIDCONNECT_KEY = '{CLIENT_ID}'
+SOCIAL_AUTH_OKTA_OPENIDCONNECT_SECRET = '{CLIENT_SECRET}'
+SOCIAL_AUTH_OKTA_OPENIDCONNECT_API_URL = 'https://{OKTA_DOMAIN}/oauth2/'
 ```
 
-### 2. Restart NetBox
+* `CLIENT_ID` is the **Client ID** you copied from the **General** tab for your NetBox app integration.
+* `CLIENT_SECRET` is the **Client secret** you copied from the **General** tab for your NetBox app integration.
+* `OKTA_DOMAIN` is your Okta domain, such as `dev-123456.okta.com`.
 
-Restart the NetBox services so that the new configuration takes effect. This is typically done with the command below:
+The API URL ends with `/oauth2/` for the default Okta authorization server. If you use a custom authorization server, use `/oauth2/{AUTH_SERVER_ID}/` instead.
+
+### Restart NetBox
+
+Configuration changes require restarting the application. This is typically done with the command below:
 
 ```no-highlight
 sudo systemctl restart netbox
@@ -57,14 +107,75 @@ sudo systemctl restart netbox
 
 ## Testing
 
-Log out of NetBox if already authenticated, and click the "Log In" button at top right. You should see the normal login form as well as an option to authenticate using Okta. Click that link.
+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 Okta.
+
+Click the option to log in with Okta.
 
 ![NetBox Okta login form](../../media/authentication/netbox_okta_login.png)
 
-You should be redirected to Okta's authentication portal. Enter the username/email and password of your test account to continue. You may also be prompted to grant this application access to your account.
+You will be redirected to Okta's authentication portal where you can log in with your test user's Okta credentials. You may also be prompted to grant this application access to your account.
 
 ![Okta login portal](../../media/authentication/okta_login_portal.png)
 
-If successful, you will be redirected back to the NetBox UI, and will be logged in as the Okta user. You can verify this by navigating to your profile (using the button at top right).
+If successful, you will be redirected back to the NetBox UI, and will be logged in as the Okta 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, and can be assigned groups and permissions.
+
+## Assign permissions
+
+New users have no permissions by default. To assign permissions:
+
+1. From NetBox, navigate to **Admin > Authentication > Users** (requires admin access).
+
+2. Locate the Okta user and assign appropriate groups or individual [permissions](../permissions.md).
+
+3. Set [staff or superuser status](../../models/users/user.md), if needed:
+
+    * **Staff**: Allows the user to log into the legacy Django admin site. Most NetBox functionality is exposed via the standard UI, so staff status is rarely needed.
+    * **Superuser**: Grants the user all permissions implicitly, bypassing all permission checks.
+
+!!! warning "Security considerations"
+    Exercise extreme caution when configuring Superuser users or groups.
+
+    Superusers have unrestricted access to NetBox and can:
+
+    * Modify any data, including configuration
+    * Elevate other users to superuser status
+
+## Troubleshooting
+
+### Redirect URI does not match
+
+Okta requires that the authenticating client request a redirect URI that matches a sign-in redirect URI you configured in the app integration.
+
+This URI must begin with `https://` and must match **exactly** what you configured in Okta (including the trailing slash). The redirect URI is where Okta sends users after authentication. NetBox uses the following pattern:
+
+```text
+https://<your-netbox-domain>/oauth/complete/okta-openidconnect/
+```
+
+If Okta complains that the requested URI starts with `http://` (not HTTPS), it's likely that your HTTP server is misconfigured or sitting behind a load balancer, so NetBox is not aware that HTTPS is being used. To force the use of an HTTPS redirect URI, set the following in `configuration.py` per the [python-social-auth docs](https://python-social-auth.readthedocs.io/en/latest/configuration/settings.html#processing-redirects-and-urlopen):
+
+```python
+SOCIAL_AUTH_REDIRECT_IS_HTTPS = True
+```
+
+### User is not assigned to the application
+
+If authentication fails with an error such as "User is not assigned to the client application", the account you are testing with has no assignment to the NetBox app integration.
+
+In the Okta Admin Console, open the integration and add the user, or a group the user belongs to, under **Assignments**.
+
+### Not logged in after authenticating
+
+If you are redirected to the NetBox UI after authenticating successfully, but are not logged in, double-check the `REMOTE_AUTH_BACKEND` value configured in `configuration.py` against your Okta app integration.
+
+The instructions provided above are only applicable to the `okta_openidconnect.OktaOpenIdConnect` backend. Confirm too that `SOCIAL_AUTH_OKTA_OPENIDCONNECT_SECRET` is the secret value rather than its ID, and that `SOCIAL_AUTH_OKTA_OPENIDCONNECT_API_URL` points at the authorization server the integration uses.
+
+### Expired client secret
+
+If authentication fails and you see an error such as "invalid_client" or "secret expired", this means your client secret has expired.
+
+Generate a new client secret in Okta, update `configuration.py` with the new value, and restart the NetBox services.
 
-This user account has been replicated locally to NetBox, and can now be assigned groups and permissions.
+To prevent this, we recommend setting a calendar reminder to rotate and update your secret.

docs/features/authentication-permissions.md

@@ -46,4 +46,4 @@ NetBox integrates with the open source [python-social-auth](https://github.com/p
 * Okta
 * OIDC
 
-...and many others. It's also possible to build your own custom backends as needed using python-social-auth's base OAuth, OpenID, and SAML classes. You can find some examples of configuring SSO in NetBox' [authentication documentation](../administration/authentication/overview.md).
+...and many others. It's also possible to build your own custom backends as needed using python-social-auth's base OAuth, OpenID, and SAML classes. You can find some examples of configuring SSO in NetBox' [authentication documentation](../administration/authentication/index.md).

docs/models/users/user.md

@@ -2,7 +2,7 @@
 
 A user represents an individual account in NetBox. Users authenticate to access the application, and may be granted permissions either directly or through their assigned [groups](./group.md). Each user can hold one or more API [tokens](./token.md) for use with the REST and GraphQL APIs.
 
-NetBox extends Django's stock user model to support multiple API tokens per user, configurable [object permissions](./objectpermission.md), and integration with [remote authentication backends](../../administration/authentication/overview.md).
+NetBox extends Django's stock user model to support multiple API tokens per user, configurable [object permissions](./objectpermission.md), and integration with [remote authentication backends](../../administration/authentication/index.md).
 
 ## Fields
 

mkdocs.yml

@@ -168,7 +168,7 @@ nav:
             - Migrating to v4.0: 'plugins/development/migration-v4.md'
     - Administration:
         - Authentication:
-            - Overview: 'administration/authentication/overview.md'
+            - Overview: 'administration/authentication/index.md'
             - Google: 'administration/authentication/google.md'
             - Microsoft Entra ID: 'administration/authentication/microsoft-entra-id.md'
             - Okta: 'administration/authentication/okta.md'