Set Up 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.

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

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

To restrict user access with basic authentication, take the following steps:

  1. Add one or more users using the Instance Manager web interface. Note each user’s username for step 2.

  2. Add the users to the .htpasswd file on the Instance Manager server.

    If desired, you can use separate .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

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:

Enable OIDC

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 

<a href="/nginx-instance-manager/getting-started/auth/nginx-manager-jwt.conf">nginx-manager-jwt.conf</a>

# 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

For instruction on how to limit access to features using role-based access control, see the tutorial Set Up RBAC.



What’s Next