Single Sign-On with Amazon Cognito

This guide explains how to enable single sign‑on (SSO) for applications being proxied by F5 NGINX Plus. The solution uses OpenID Connect as the authentication mechanism, with Amazon Cognito as the identity provider (IdP), and NGINX Plus as the relying party.

See Also:

Prerequisites

The instructions assume you have the following:

An AWS account.
An NGINX Plus subscription and NGINX Plus R15 or later. For installation instructions, see the NGINX Plus Admin Guide.
The NGINX JavaScript module (njs), required for handling the interaction between NGINX Plus and the IdP. After installing NGINX Plus, install the module with the 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
```
The following directive included in the top-level (“main”) configuration context in /etc/nginx/nginx.conf, to load the NGINX JavaScript module:
```
load_module modules/ngx_http_js_module.so;
```

Configuring Amazon Cognito

Note: The following procedure reflects the Cognito GUI at the time of publication, but the GUI is subject to change. Use this guide as a reference and adapt to the current Cognito GUI as necessary.

Create a new application for NGINX Plus in the Cognito GUI:

Log in to your AWS account, open the AWS Management Console (console.aws.amazon.com), and navigate to the Cognito dashboard (you can, for example, click Cognito in the Security, Identity, & Compliance section of the Services drop‑down menu).
On the Cognito dashboard, click Manage User Pools to open the Your User Pools window. Click the Create a user pool button or the highlighted phrase.
In the Create a user pool window that opens, type a value in the Pool name field (in this guide, it’s nginx-plus-pool), then click the Review defaults button.
On the Review tab which opens, click Add app client… in the App clients field near the bottom.
On the App clients tab which opens, click Add an app client.
On the Which app clients will have access to this user pool? window which opens, enter a value (in this guide, nginx-plus-app) in the App client name field. Make sure the Generate client secret box is checked, then click the Create app client button.
On the confirmation page which opens, click Return to pool details to return to the Review tab. On that tab click the Create pool button at the bottom. (The screenshot in Step 4 shows the button.)
On the details page which opens to confirm the new user pool was successfully created, make note of the value in the Pool Id field; you will add it to the NGINX Plus configuration in Step 3 of Configuring NGINX Plus.
Click Users and groups in the left navigation column. In the interface that opens, designate the users (or group of users, on the Groups tab) who will be able to use SSO for the app being proxied by NGINX Plus. For instructions, see the Cognito documentation about creating users, importing users, or adding a group.
Click App clients in the left navigation bar. On the tab that opens, click the Show Details button in the box labeled with the app client name (in this guide, nginx-plus-app).
On the details page that opens, make note of the values in the App client id and App client secret fields. You will add them to the NGINX Plus configuration in Step 3 of Configuring NGINX Plus.
Click App client settings in the left navigation column. In the tab that opens, perform the following steps:
1. In the Enabled Identity Providers section, click the Cognito User Pool checkbox (the Select all box gets checked automatically).
2. In the Callback URL(s) field of the Sign in and sign out URLs section, type the URI of the NGINX Plus instance including the port number, and ending in /_codexch. Here we’re using https://my-nginx-plus.example.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).
3. In the OAuth 2.0 section, click the Authorization code grant checkbox under Allowed OAuth Flows and the email, openid, and profile checkboxes under Allowed OAuth Scopes.
4. Click the Save changes button.
Click Domain name in the left navigation column. In the tab that opens, type a domain prefix in the Domain prefix field under Amazon Cognito domain (in this guide, my-nginx-plus). Click the Save changes button.

Configuring NGINX Plus

Configure NGINX Plus as the OpenID Connect relying party:

Create a clone of the nginx-openid-connect GitHub repository.

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

Copy these files from the clone to /etc/nginx/conf.d:
- frontend.conf
- openid_connect.js
- openid_connect.server_conf
In your preferred text editor, open /etc/nginx/conf.d/frontend.conf. Change the second parameter of each of the following set directives to the specified value.

The <My-Cognito-Domain-Name> variable is the full value in the Domain prefix field in Step 13 of Configuring Amazon Cognito. In this guide it is https://my-nginx-plus.auth.us-east-2.amazoncognito.com.
- set $oidc_authz_endpoint – <My-Cognito-Domain-Name>/oauth2/authorize
- set $oidc_token_endpoint – <My-Cognito-Domain-Name>/oauth2/token
- set $oidc_client – Value in the App client id field from Step 11 of Configuring Amazon Cognito (in this guide, 2or4cs8bjo1lkbq6143tqp6ist)
- set $oidc_client_secret – Value in the App client secret field from Step 11 of Configuring Amazon Cognito (in this guide, 1k63m3nrcnu...)
- set $oidc_hmac_key – A unique, long, and secure phrase
Configure the JWK file. The file’s URL is

https://cognito-idp.region.amazonaws.com/User-Pool-ID/.well-known/jwks.json

where
- region is the same AWS region name as in the <My-Cognito-Domain-Name> variable used in Step 3
- User-Pool-ID is the value in the Pool Id field in Step 8 of Configuring Amazon Cognito
In this guide, the URL is

https://cognito-idp.us-east-2.amazonaws.com/us-east-2_mLoGHJpOs/.well-known/jwks.json.

The method for configuring the JWK file depends on which version of NGINX Plus you are using:
- In NGINX Plus R17 and later, NGINX Plus can read the JWK file directly. Change /etc/nginx/conf.d/frontend.conf as follows:
  1. Comment out (or remove) the auth_jwt_key_file directive.
  2. Uncomment the auth_jwt_key_request directive. (Its parameter, /_jwks_uri, refers to the value of the $oidc_jwt_keyfile variable, which you set in the next step.)
  3. Change the second parameter of the set $oidc_jwt_keyfile directive to the URL of the JWK file (https://cognito-idp.../.well-known/jwks.json).
- In NGINX Plus R16 and earlier, the JWK file must be on the local disk. (You can also use this method with NGINX Plus R17 and later if you wish.)
  1. Copy the JSON contents from the JWK file (https://cognito-idp.../.well-known/jwks.json) to a local file (for example, /etc/nginx/my_cognito_jwk.json).
  2. In /etc/nginx/conf.d/frontend.conf, change the second parameter of the set $oidc_jwt_keyfile directive to the local file path.
At the time of publication, Cognito does not support the OpenID offline_access scope. Open /etc/nginx/conf.d/openid_connect.server_conf in a text editor and remove +offline_access from the list of scopes on line 10, so that it looks like this:
```
return 302 "$oidc_authz_endpoint?response_type=code&scope=openid+profile+email&client_id=$oidc_clientaws...;
```
Confirm that the user named by the user directive in the NGINX Plus configuration (in /etc/nginx/nginx.conf by convention) has read permission on the JWK file.

Testing

In a browser, enter the address of your NGINX Plus instance and try to log in using the credentials of a user assigned to the application (see Step 9 in Configuring Amazon Cognito). The NGINX logo that appears in the screenshot was added on Cognito’s UI customization tab (not shown in this guide).

Troubleshooting

See the Troubleshooting section at the nginx-openid-connect repository on GitHub.

Revision History

Version 1 (March 2020) – Initial version (NGINX Plus Release 20)

Last modified August 22, 2024