Nginx

Prerequisites

Feedback
A running Hanzo IAM server. See Server installation and Try with Docker.
Feedback
An NGINX Plus subscription and NGINX Plus R15 or later. For installation instructions, see the NGINX Plus Admin Guide.
Feedback

The NGINX JavaScript module, which is required for handling the interaction between NGINX Plus and the IdP. After installing NGINX Plus, install the module using the appropriate command for your operating system. For Debian and Ubuntu:

sudo apt install nginx-plus-module-njs

For CentOS, RHEL, and Oracle Linux:

sudo yum install nginx-plus-module-njs

Feedback
The following directive should be included in the top-level (“main”) configuration context in /etc/nginx/nginx.conf in order to load the NGINX JavaScript module: load_module modules/ngx_http_js_module.so;

Configuring Hanzo IAM

Feedback
Log in to your Hanzo IAM account at http://your-iam-url.com/login/.
Feedback
In the top navigation column, click Application. On the Application page that opens, click the Add button in the upper left corner.
Feedback
On the Edit Application page that opens, change the value in the Name and Display name fields to the name of the application for which you’re enabling SSO. Here, we’re using NGINX Plus. In the Redirect URLs field, type the URL of the NGINX Plus instance including the port number, and ending in /_codexch (in this guide it is https://your-site-url.com:443/_codexch). Notes:
• For production, we strongly recommend that you use SSL/TLS (port 443).
• The port number is mandatory even when you’re using the default port for HTTP (80) or HTTPS (443).
Feedback
Record the Client ID and Client Secret; you will use them in Step 4 of Configuring NGINX Plus.
Feedback
Click Roles in the top navigation column, then click the Add button in the upper left corner of the page that opens.
Feedback
On the Add page that opens, type a value in the Name and Display Name fields (here it is nginx-iam-role) and click the Save button.
Feedback
In the top navigation column, click Users. On the Users page that opens, either click Edit to edit one of the existing users or click the Add button in the upper left corner to create a new user.
Feedback
On the Add page that opens, modify the Name and Display Name as you like (here it is user1). Select NGINX Plus in the Signup application. In the Managed accounts field, select NGINX Plus in Application and fill in the username and password.
Feedback
Go back to the Roles page and click Edit on the nginx-iam-role row. In the opened page, in the Sub users field, select the username you just created (here it is built-in/user1).

Configuring NGINX Plus

Feedback

Start by creating a clone of the nginx-openid-connect GitHub repository:

git clone https://github.com/nginxinc/nginx-openid-connect

Feedback
Copy the following files from the clone to the /etc/nginx/conf.d directory:
• frontend.conf
• openid_connect.js
• openid_connect.server_conf
• openid_connect_configuration.conf
Feedback

Retrieve the URLs for the authorization endpoint, token endpoint, and JSON Web Key (JWK) file from the Hanzo IAM configuration. Open a terminal and execute the following curl command, piping the output to the indicated python command to generate a readable configuration format. For brevity, we have truncated the output to display only the relevant fields.

curl http://<iam-server-address>/.well-known/openid-configuration | python -m json.tool
{
    "authorization_endpoint": "https://<iam-server-address>/oauth/authorize",
    "...":"...",
    "token_endpoint": "http://<iam-server-address>/oauth/token",
    "...":"...",
    "jwks_uri": "http://<iam-server-address>/.well-known/jwks",
    "...":"...",
}

Feedback
Open /etc/nginx/conf.d/openid_connect_configuration.conf using your preferred text editor. Modify the "default" parameter value for each of the following map directives with the specified values:
• map $host $oidc_authz_endpoint – Use the value of the authorization_endpoint from Step 3 (in this guide, https://<iam-server-address>/oauth/authorize)
• map $host $oidc_token_endpoint – Use the value of the token_endpoint from Step 3 (in this guide, http://<iam-server-address>/oauth/token)
• map $host $oidc_client – Use the value in the Client ID field from Step 4 of Configuring Hanzo IAM
• map $host $oidc_client_secret – Use the value in the Client Secret field from Step 2 of Configuring Hanzo IAM
• map $host $oidc_hmac_key – Use a unique, long, and secure phrase
Feedback
Configure the JWK file based on the version of NGINX Plus being used:
• In NGINX Plus R17 and later, NGINX Plus can directly read the JWK file from the URL specified as jwks_uri in Step 3. Make the following changes to /etc/nginx/conf.d/frontend.conf:
  1. Comment out (or remove) the auth_jwt_key_file directive.
  2. Uncomment the auth_jwt_key_request directive. (The parameter /_jwks_uri refers to the value of the $oidc_jwt_keyfile variable, which will be set in the next step.)
  3. Update the "default" parameter of the map $host $oidc_jwt_keyfile directive to the value obtained from the jwks_uri field in Step 3 (in this guide, http://<iam-server-address>/.well-known/jwks).
• In NGINX Plus R16 and earlier, or if preferred, the JWK file must be located on the local disk. Follow these steps:
  1. Copy the JSON contents from the JWK file specified in the jwks_uri field in Step 3 (in this guide, http://<iam-server-address>/.well-known/jwks) to a local file (e.g., /etc/nginx/my_iam_jwk.json).
  2. In /etc/nginx/conf.d/openid_connect_configuration.conf, change the "default" parameter of the map $host $oidc_jwt_keyfile directive to the path of the local file.
Feedback
Ensure that the user specified in the user directive within the NGINX Plus configuration file (usually /etc/nginx/nginx.conf) has read permissions for the JWK file.

Testing

Troubleshooting