Configure Authentication

Follow the steps in this guide to configure authentication for NGINX Instance Manager.


This documentation applies to NGINX Instance Manager 2.0.0 and later.


Note:
NGINX Plus is provided and intended only to be used with NGINX Instance Manager as a frontend. You should not use NGINX Plus for other web applications or instances. Contact your sales team to purchase additional subscriptions for external uses and other systems.

Prerequisites

  1. Install NGINX Instance Manager Server.
  2. Install NGINX or NGINX Plus.
  3. Start and Enable Instance Manager and NGINX Plus (or NGINX).

Authentication Options

The following table shows the authentication options for NGINX Instance Manager on NGINX Open Source and NGINX Plus.

Table: Authentication options

Security Method NGINX OSS NGINX Plus
Commercial Support Included Included
Denylisting IPs N/A Supported
Basic Authentication Included Included
JWT Authentication N/A Included
OpenID Connect/OAuth2 N/A Supported
Rate-Limiting Included Included
Role Based Access Control N/A Supported

Basic Authentication

Basic authentication is enabled by default.

Warning:
Basic authentication is not secure and should not be used for production environments. Use OIDC or another secure authentication method for production.

Basic authentication uses a username and password that you can set locally in the /etc/nms/nginx/.htpasswd file.

If desired, you can use different .htpasswd files in different locations or restrict by IP addresses. Refer to the guide Restricting Access with HTTP Basic Authentication for more information.

JWT Authentication

You can use JSON Web Token (JWT) Authentication with NGINX Plus and Instance Manager. You need to create the JWT or use an identity provider (idP) to generate the JWT. For more examples, refer to the NGINX documentation Setting up JWT Authentication.

Below is an example NGINX conf for using JWT.

/etc/nginx/conf.d/nginx-manager-jwt.conf

nginx-manager-jwt.conf

# nginx-manager-jwt.conf
# Proxy API with JWT to 127.0.0.1 on nginx-manager
# Include the nginx-manager-upstreams.conf for the proxy_pass to work
# Ensure you have permissions set in the directories
# More information is available <https://docs.nginx.com/nginx/admin-guide/security-controls/configuring-jwt-authentication/>

map $jwt_claim_sub $jwt_status {
    "quotes" "revoked";
    "test"   "revoked";
    default  "";
}

limit_req_zone $jwt_claim_sub zone=10rps_per_client:1m rate=10r/s;

log_format jwt '$remote_addr - $remote_user [$time_local] "$request" '
               '$status $body_bytes_sent "$http_referer" "$http_user_agent" '
               '$jwt_header_alg $jwt_claim_uid $jwt_claim_url' ;

# reverse proxy with JWT authentication
#
server {
    listen      443 http2 ssl;
    status_zone nginx-manager_oauth_https;
    server_name nginx-manager.example.com;

    # Optional log locations
    # error_log /var/log/nginx/nginx-manager-jwt-error.log debug; # Reduce severity level as required   

    # SSL certificates must be valid for the FQDN and placed in the correct directories
    ssl_certificate             /etc/nms/certs/manager-server.crt;
    ssl_certificate_key         /etc/nms/certs/manager-server.key;
    # ssl_client_certificate    /etc/ssl/nginx-manager/ca.pem;

    ssl_session_cache shared:SSL:10m;
    ssl_session_timeout 24h;
    ssl_session_tickets off;

    ssl_protocols   TLSv1.2 TLSv1.3;
    ssl_ciphers EECDH+CHACHA20:EECDH+AES128:RSA+AES128:EECDH+AES256:RSA+AES256:EECDH+3DES:RSA+3DES:!MD5;
    ssl_prefer_server_ciphers   off;
    
    # Could change to /api for multiple methods of auth
    location / {
        # JWT validation
        auth_jwt "JWT Test Realm" token=$arg_myjwt;    # Change to realm you use or "" for no realm
        auth_jwt_key_file /etc/nginx/api_secret.jwk;

        if ( $jwt_status = "revoked" ) {
            return 403;
        }

        limit_req zone=10rps_per_client;

        proxy_pass http://nginx-manager_servers;
        health_check uri=/swagger-ui/;

        # Successfully authenticated users are proxied to the backend,
        # with 'sub' claim passed as HTTP header
        proxy_set_header Nginx-Management-Suite-User $jwt_claim_sub;
        proxy_set_header Connection "";
        proxy_http_version 1.1;
        client_max_body_size 0;

        access_log /var/log/nginx/nginx-manager-jwt-access.log jwt;
    }

}

# vim: syntax=nginx

OpenID Connect

Enabling OIDC

You can enable OpenID Connect (OIDC) for NGINX Instance Manager for production environments that require secure authentication.

Warning:
Before switching from Basic Auth to OIDC, make sure to add at least one admin user to your identity provider. A failure to do so may lock admin users out of NGINX Instance Manager when you enable OIDC. If that happens, you can revert to Basic Auth to restore access.
See Also:
Follow the steps in Configure OIDC with Azure Active Directory to secure NGINX Instance Manager with OpenID Connect (OIDC) using Azure Active Directory (AD) as the identity provider.

Prerequisites

To use OIDC with NGINX Instance Manager, you need to perform the following:

Steps

The OIDC configuration file (oidc_configuration.conf) includes placeholder names that need to be updated for OIDC work. The following information is needed to configure the service:

Table: OIDC placeholders

OIDC Config Placeholder Description
OIDC_AUTH_ENDPOINT The authorization endpoint of your identity provider
OIDC_CLIENT_ID The client id for your identity provider service
OIDC_CLIENT_SECRET The client secret for your identity provider service
OIDC_HMAC_KEY The HMAC key for your identity provider service
OIDC_KEYS_ENDPOINT The keys endpoint of your identity provider
OIDC_TOKEN_ENDPOINT The token endpoint of your identity provider
SERVER_FQDN The fully qualified domain name (FQDN) of the server
  1. Open the OIDC configuration file /etc/nms/nginx/oidc/oidc_configuration.conf for editing and update the placeholder values with the information for your identity provider. Save the changes.

  2. Open the NGINX Management Suite config file /etc/nginx/conf.d/nms-http.conf for editing and uncomment the OIDC settings beginning with #OIDC and comment out the settings for Basic Auth. Save the changes.

  3. Run sudo nginx -t to verify the config has no errors.

  4. Run sudo nginx -s reload to reload and apply the config.

gRPC Metadata

You can use advanced NGINX Plus features such as JWT and gRPC by following the guides on the NGINX blog. Use the encryption guide for setting up gRPC on NGINX Instance Manager.

Rate-Limiting

Enabling rate-limiting can help mitigate and prevent DDoS attacks and should be enabled for the API and web interface listeners. Using a configuration file similar to the one below can be leveraged with other authentication and encryption methods.

/etc/nginx/conf.d/nginx-manager-jwt.conf

nginx-manager-jwt.conf

# nginx-manager-jwt.conf
# Proxy API with JWT to 127.0.0.1 on nginx-manager
# Include the nginx-manager-upstreams.conf for the proxy_pass to work
# Ensure you have permissions set in the directories
# More information is available <https://docs.nginx.com/nginx/admin-guide/security-controls/configuring-jwt-authentication/>

map $jwt_claim_sub $jwt_status {
    "quotes" "revoked";
    "test"   "revoked";
    default  "";
}

limit_req_zone $jwt_claim_sub zone=10rps_per_client:1m rate=10r/s;

log_format jwt '$remote_addr - $remote_user [$time_local] "$request" '
               '$status $body_bytes_sent "$http_referer" "$http_user_agent" '
               '$jwt_header_alg $jwt_claim_uid $jwt_claim_url' ;

# reverse proxy with jwt authentication
#
server {
    listen      443 http2 ssl;
    status_zone nginx-manager_oauth_https;
    server_name nginx-manager.example.com;

    # Optional log locations
    # error_log /var/log/nginx/nginx-manager-jwt-error.log debug; # Reduce severity level as required   

    # SSL certificates must be valid for the FQDN and placed in the correct directories
    ssl_certificate             /etc/nms/certs/manager-server.crt;
    ssl_certificate_key         /etc/nms/certs/manager-server.key;
    # ssl_client_certificate    /etc/ssl/nginx-manager/ca.pem;

    ssl_session_cache shared:SSL:10m;
    ssl_session_timeout 24h;
    ssl_session_tickets off;

    ssl_protocols   TLSv1.2 TLSv1.3;
    ssl_ciphers EECDH+CHACHA20:EECDH+AES128:RSA+AES128:EECDH+AES256:RSA+AES256:EECDH+3DES:RSA+3DES:!MD5;
    ssl_prefer_server_ciphers   off;
    
    # Could change to /api for multiple methods of auth
    location / {
        # JWT validation
        auth_jwt "JWT Test Realm" token=$arg_myjwt;    # Change to realm you use or "" for no realm
        auth_jwt_key_file /etc/nginx/api_secret.jwk;

        if ( $jwt_status = "revoked" ) {
            return 403;
        }

        limit_req zone=10rps_per_client;

        proxy_pass http://nginx-manager_servers;
        health_check uri=/swagger-ui/;

        # Successfully authenticated users are proxied to the backend,
        # with 'sub' claim passed as HTTP header
        proxy_set_header Nginx-Management-Suite-User $jwt_claim_sub;
        proxy_set_header Connection "";
        proxy_http_version 1.1;
        client_max_body_size 0;

        access_log /var/log/nginx/nginx-manager-jwt-access.log jwt;
    }

}

# vim: syntax=nginx

Role Based Access Control

NGINX Instance Manager has added tagging and RBAC for v1.0.0+ and NGINX Plus proxy users. You need to set up authentication and pass the Nginx-Management-Suite-User header.

See Also:
For more information about using tags for RBAC, see Configure RBAC with tagging.

Roles and access control work with tagging, allowing instances to have a tag of any name applied in the UI or added to the dynamic-agent.conf for the particular instance.

Note:
NOTE: An admin user and role are created by default with full access.

Enforcement occurs on the URL paths listed below. The system denies access if the header doesn’t include Nginx-Management-Suite-User. A proxy must be used to secure access this way; otherwise, you could pass in anything if directly accessing nginx-manager without a proxy.

Table: RBAC enforcement

URL Path Scope
/api/platform/v1/certs Instance Management
/api/platform/v1/configs Instance Management
/api/platform/v1/instance-groups Instance Management
/api/platform/v1/instances Instance Management
/api/platform/v1/license Settings
/api/platform/v1/roles Settings
/api/platform/v1/servers Instance Management
/api/platform/v1/systems Instance Management
/api/platform/v1/users Settings

Scope: Settings

A role with a permission scope of Settings has access to the Settings options, which include License, Roles, and Users.

All GET requests for /roles and /users are filtered for non-admins by the roles they have been granted.

Scope: Instance Management

A role with a scope of Instance Management has access to the Instance Manager options, which include Instances, Instance Groups, Config Templates, Scan, and Certificates.

All GET requests except for /certs will be filtered for non-admin, based on the system Tags they have been granted through Roles.

Creating Roles

Roles are a construct of a name, access type, and one or more tags. To create roles, you need to have a role with a permission scope of Settings.

Note:

Changes made to a role may take up to 10 minutes to take effect.

Admin users can view, add, and change any system tags, as well as any access levels. Non-admin users are restricted to viewing only the roles and tags they’ve been assigned.

To create a role, take the following steps:

  1. Open the NGINX Instance Manager web interface and log in.
  2. Select the Settings gear icon.
  3. In the left menu, select Roles.
  4. Select Create.
  5. In the Name box, give the role a name.
  6. In the Display Name box, type a name to show for the role.
  7. In the Permissions section, select Create.
  8. In the Scope list, select the access level for the role:
  9. In the Access list, specify the access level.
  10. In the Tags list, select the tag or tags the role has access to. This setting is available only if Scope is Instance Manager. This setting is ignored for Admin role.

Creating Users

To add users and assign them roles, take the following steps:

  1. Open the NGINX Instance Manager web interface and log in.
  2. Select the Settings gear icon.
  3. In the left menu, select Users.
  4. Select Create.
  5. In the Username box, type the username for the new user. This is used as the Nginx-Management-Suite-User header for the user.
  6. In the Email box, type the user’s email address.
  7. In the First Name box, type the user’s first name.
  8. In the Last Name box, type the user’s last name.
  9. (Optional) In the Description box, add a description for the user account.
  10. In the Roles list, select one or more roles to assign the user. See Creating Roles to add roles to the list.
Note:

Changes made to a user may take up to 10 minutes to take effect.

Admin users can view, add, and change any system tags, as well as any access levels. Non-admin users are restricted to viewing only the roles and tags they’ve been assigned.