# Get started with OIDC


> Configure OpenID Connect (OIDC) authentication for F5 NGINX Instance Manager using any OIDC-compliant identity provider to enable Single Sign-On.


## Overview

We recommend using OpenID Connect (OIDC) as the preferred authentication method for F5 NGINX Instance Manager. OIDC offers several advantages, including Single Sign-On (SSO) for users and simplified user management for administrators through user groups. OIDC also enables easy scalability and streamlined user access management.

NGINX Instance Manager’s implementation of OIDC is designed to work with any Identity Provider (IdP) that supports the OIDC protocol. The instructions below are general and can be applied to any IdP.

**Note:** To learn how to configure OIDC with a specific identity provider, refer to the linked topics in the [Set up specific IdPs for OIDC](#oidc-specific-idps) section at the bottom of this page.

**Note:** OpenID Connect (OIDC) authentication is not supported when NGINX Instance Manager is running in [forward-proxy mode](nim/system-configuration/configure-forward-proxy.md). OIDC is configured on the NGINX Plus layer and cannot pass authentication requests through a forward proxy.

## Create roles and user groups in NGINX Instance Manager {#configure-nim}

When using OIDC for authentication, administrators don't need to create and manage users in NGINX Instance Manager. Instead, they create user groups in NGINX Instance Manager that match groups in their IdP. The roles assigned to the user group set the access level and permissions for users based on their group membership. Users who aren't in a group with an assigned role won't have access to NGINX Instance Manager.

To grant users access using OIDC, follow these steps:

1. Create a role in NGINX Instance Manager.
2. Create a user group and assign a role to it. **The group name must exactly match a group name in your IdP**.
3. Set up OIDC.

### Create a role {#create-role}

Roles in NGINX Instance Manager are a critical part of [role-based access control (RBAC)](/nim/admin-guide/rbac/overview-rbac.md). By creating roles, you define the access levels and permissions for different user groups that correspond to groups in your Identity Provider (IdP).

NGINX Instance Manager includes a built-in administrator role called `admin`. You can create additional roles as needed.

The `admin` user or any user with `CREATE` permission for the **User Management** feature can create a role.

Follow these steps to create a role and set its permissions:

1. In a web browser, go to the FQDN for your NGINX Instance Manager host and log in.
1. Select the **Settings** (gear) icon in the upper-right corner.
1. From the left navigation menu, select **Roles**.
1. Select **Create**.
1. On the **Create Role** form, provide the following details:

   - **Name**: The name to use for the role.
   - **Display Name**: An optional, user-friendly name to show for the role.
   - **Description**: An optional, brief description of the role.

1. To add permissions:

   1. Select **Add Permission**.
   2. Select the NGINX Instance Manager module you're creating the permission for from the **Module** list.
   3. Select the feature you're granting permission for from the **Feature** list. To learn more about features, see [Get started with RBAC](/nim/admin-guide/rbac/overview-rbac.md).
   4. Select **Add Additional Access** to choose a CRUD (Create, Read, Update, Delete) access level.
      - Select the access level(s) you want to grant from the **Access** list.
   5. Select **Save**.

1. Repeat step 6 if you need to add more permissions for other features.
1. When you've added all the necessary permissions, select **Save** to create the role.

#### Example scenario

Suppose you need to create an "app-developer" role. With this role, users can create and edit applications but not delete them or do administrative tasks. Name the role `app-developer`, select the relevant features, and grant permissions that align with the application development process while restricting administrative functions.

#### Next steps

After creating a role, assign it to a user group within NGINX Instance Manager that matches a group in your IdP. Proceed to the [create a user group with an assigned role](#create-user-group) section for detailed instructions.

### Create a user group with an assigned role {#create-user-group}

**Note:** To ensure that NGINX Instance Manager and your IdP work together seamlessly, group names must exactly match between the two systems. If the group names don’t match, the OIDC integration will fail, preventing users from accessing NGINX Instance Manager. For example, if you have a group called "app-developers" in your IdP, you must create a user group called "app-developers" in NGINX Instance Manager. The group claim must also be part of the token your IdP generates. Refer to your IdP's documentation for guidance on adding group claims.

Here's how to create a user group and assign roles:

1. In a web browser, go to the FQDN for your NGINX Instance Manager host and log in.
1. Select the **Settings** (gear) icon in the upper-right corner.
1. From the left navigation menu, select **User Groups**.
1. Select **Create**.
1. On the **Create Group** form, provide the following information:

   - **Group Name** (required): The group name or Object ID. This must **exactly match** the name used in the IdP.
   - **Display Name**: A friendly name for the group.
   - **Description**: A brief description of the group.

1. Select one or more roles from the **Roles** list to assign to the group.

   **Note:** At least one user group must have the `admin` role assigned.

1. Select **Save** to create the group.

#### Example scenario

Imagine you’ve created a role called "app-developer" for users who develop, create, and modify applications but don’t need to perform administrative tasks. You want this role to correspond to a group in your IdP named "app-developers."

In this case, select the "app-developer" role when creating the "app-developers" user group in NGINX Instance Manager. Users in the "app-developers" group from the IdP will inherit the "app-developer" role in NGINX Instance Manager.

#### Next steps

Now that you've created a user group and assigned a role in NGINX Instance Manager, continue to the [configure OIDC](#configure-oidc) section. These instructions will help you integrate with your IdP and ensure user groups and permissions work as expected.

## Configure OIDC {#configure-oidc}

### Before you begin

**Note:** 
Before switching from basic authentication to OIDC, make sure to add at least one admin user to your IdP. Failure to do so can result in admin users being locked out of NGINX Instance Manager. If this occurs, you can restore access by reverting back to basic authentication.

When you configure OIDC for NGINX Instance Manager, basic authentication will be disabled for all users, including the default `admin` user. To ensure uninterrupted access, create a user group in NGINX Instance Manager that corresponds to a group in your IdP and assign the appropriate roles.

- Follow the instructions above to [grant users access](#granting-users-access) before proceeding.

### Requirements

The following requirements must be met before you can use OIDC with NGINX Instance Manager:

1. [Install NGINX Instance Manager](/nim/deploy/vm-bare-metal/install.md) on a server that also has [NGINX Plus R21 or newer](/nginx/admin-guide/installing-nginx/installing-nginx-plus.md) installed. Ensure the server hosting NGINX Plus has a fully qualified domain name (FQDN).

2. [Install the NGINX JavaScript module (njs)](https://www.nginx.com/blog/introduction-nginscript/) on the same server as NGINX Instance Manager. This module is required for managing communications between NGINX Plus and the identity provider.

3. Configure an IdP to provide authentication services. This includes setting up authentication policies, scopes, and client credentials within your IdP.

### Enable OIDC

To enable OIDC, follow these steps to update the OIDC configuration file:

1. Open `/etc/nms/nginx/oidc/openid_configuration.conf` in a text editor and replace the default placeholder values with the relevant information for your IdP. (For more information on the variables, refer to the [OIDC configuration values](#oidc-variables).) Save the changes.

1. Open `/etc/nginx/conf.d/nms-http.conf` in a text editor and uncomment the OIDC settings that begin with `#OIDC`. Comment out the basic authentication settings. Save the changes.

1. Run `sudo nginx -t` to validate the configuration and ensure there are no errors.

1. Reload NGINX and apply the new configuration with `sudo nginx -s reload`.

### OIDC configuration values {#oidc-variables}

The sections below provide detailed descriptions of the OIDC configuration values.

#### Metadata from well-known endpoints

- **$oidc_authz_endpoint**: The URL of the IdP’s OAuth 2.0 Authorization endpoint.
- **$oidc_jwt_keyfile**: The URL of the IdP’s JSON Web Key Set (JWKS) document.
- **$oidc_logout_endpoint**: The URL of the IdP’s end_session endpoint.
- **$oidc_token_endpoint**: The URL of the IdP’s OAuth 2.0 Token endpoint.
- **$oidc_userinfo_endpoint**: The URL of the IdP’s UserInfo endpoint.
- **$oidc_host**: The URL of the IdP’s application (for example, `https://{my-app}.okta.com`).
- **$oidc_scopes**: List of OAuth 2.0 scope values supported by the server (for example, `openid+profile+email+offline_access`).

#### Custom configuration for well-known endpoints

For custom settings, adjust parameters such as `$oidc_authz_path_params_enable`, `$oidc_logout_query_params`, and others to match your IdP’s needs.

## Set up specific IdPs for OIDC {#oidc-specific-idps}

For specific IdP setup instructions, refer to the following:

- [Set up Microsoft Entra as an OIDC identity provider](/nim/admin-guide/authentication/oidc/microsoft-entra-setup.md)
- [Set up Keycloak as an OIDC identity provider](/nim/admin-guide/authentication/oidc/keycloak-setup.md)