Single Sign-On with Okta
This documentation applies to F5 NGINX Plus R15 and later.
You can use NGINX Plus with Okta and OpenID Connect to enable single sign-on (SSO) for your proxied applications. By following the steps in this guide, you will learn how to set up SSO using OpenID Connect as the authentication mechanism, with Okta as the identity provider (IdP), and NGINX Plus as the relying party.
See Also:
You can find more information about the NGINX Plus OpenID Connect integration in the project’s GitHub repo.
Prerequisites
To complete the steps in this guide, you need the following:
- An Okta administrator account.
- NGINX Plus with a valid subscription.
- The NGINX JavaScript module (
njs
) – thenjs
module handles the interaction between NGINX Plus and Okta. - Install
jq
on the host machine where you installed NGINX Plus.
Install NGINX Plus and the njs Module
-
If you do not already have NGINX Plus installed, follow the steps in the NGINX Plus Admin Guide to do so.
-
Install the NGINX JavaScript module by following the steps in the
njs
installation guide. -
Add the following directive to the top-level (“main”) configuration context in the NGINX Plus configuration (
/etc/nginx/nginx.conf
) to load thenjs
module:load_module modules/ngx_http_js_module.so;
Configure Okta
Take the steps in this section to create a new application for NGINX Plus.
Note:
This section contains images that reflect the state of the Okta web interface at the time of publication. The actual Okta GUI may differ from the examples shown here. Use this guide as a reference and adapt the instructions to suit the current Okta GUI as necessary.
This section describes the Okta Workforce Identity SSO product. You will need administrator access to your organization in Okta to complete this task. Your experience may differ somewhat if you’re using the Okta Customer Identity product.
Create a New Okta Web Application
-
Log in to Okta at okta.com.
-
Select the Admin button next to your username to access the Admin console.
-
On your Admin dashboard, select Applications in the left-hand navigation menu.
-
On the Applications page, select the Create App Integration button.
-
In the Create a new app integration window, define the following values, then select Next:
- Sign-in method: OIDC - OpenID Connect
- Application type: Web Application
Set up the Web App Integration
On the New Web App Integration page in the Okta web interface, fill in the following information, then select Save.
Field | Desciption | Example Value |
---|---|---|
App integration name | The name of the OpenID Connect relying party. Okta refers to this as the “application”. | NGINX-Plus |
Sign-in redirect URIs | The URI of the NGINX Plus instance – including the port number – ending in /_codexch .
|
https://my-nginx.example.com:443/_codexch |
Sign-out redirect URIs | The URI to redirect users to after logging out. This is an optional field with a default value of http://localhost:8080 . |
We removed the default value in our example. |
Controlled access | Controls who can access the application. | “Allow everyone in your organization to access” You should select the appropriate value for your use case. |
Get the Okta App Client Credentials
After you finish creating your application, the Okta Application page should display. You can find the Client Credentials for your Okta Application here.
Tip:
If you need to find this information later, log in to your Okta admin account as described above, select Applications in the left-hand menu, then select your application.
Make note of the Client ID and Client secret values for your application. You will need these when you configure NGINX Plus.
Manage Access to your Okta Application
To change the users and groups that have access to your Okta Application:
- Log in to Okta as an Admin as described above.
- Select Applications in the left-hand menu, then select your application.
- Select the Assignments tab for the Application.
Here, you can manage which users in your organization are granted access to this application.
Set up NGINX Plus
Take the steps in this section to set up NGINX Plus as the OpenID Connect relying party.
Configure NGINX OpenID Connect
-
Clone the nginx-openid-connect GitHub repository, or download the repo files.
git clone https://github.com/nginxinc/nginx-openid-connect.git
-
Copy the following files to the
/etc/nginx/conf.d
directory on the host machine where NGINX Plus is installed:frontend.conf
openid_connect.js
openid_connect.server_conf
openid_connect_configuration.conf
-
Get the URLs for the authorization endpoint, token endpoint, and JSON Web Key (JWK) file from the Okta configuration.
Run the following
curl
command in a terminal.Tip:
We recommend piping the output tojq
to output the entire configuration in an easily readable format.curl https://<username>-admin.okta.com/.well-known/openid-configuration | jq ... { "authorization_endpoint": "https://<username>.okta.com/oauth2/v1/authorize", ... "jwks_uri": "https://<username>.okta.com/oauth2/v1/keys", ... "token_endpoint": "https://<username>.okta.com/oauth2/v1/token", ... }
-
Add the correct values for your IdP to the OpenID Connect configuration file (
/etc/nginx/conf.d/openid_connect_configuration.conf
).This file contains the primary configuration for one or more IdPs in
map{}
blocks. You should modify themap…$oidc_
blocks as appropriate to match your IdP configuration.- Define the
$oidc_authz_endpoint
,$oidc_token_endpoint
, and$oidc_jwt_keyfile
values using the information returned in the previous step. - Change the URI defined in
map…$oidc_logout_redirect
to the URI of a resource (for example, your home page) that should be displayed after a client requests the/logout
location. - Set a unique, long, and secure phrase for
$oidc_hmac_key
to ensure nonce values are unpredictable.
- Define the
Set up JSON Web Key Authorization
NGINX Plus can read the JWK file directly from the URL reported as jwks_uri
in the output of the curl
command you ran in the previous section.
Note:
If you are using NGINX Plus R16 or earlier, refer to Set up JWK Authorization using a local file.
Take the following steps to set up NGINX Plus to access the JWK file by using a URI.
-
In the
/etc/nginx/conf.d/frontend.conf
file, remove (or comment out) the auth_jwt_key_file directive. -
Uncomment the auth_jwt_key_request directive.
The parameter
/_jwks_uri
refers to the value of the$oidc_jwt_keyfile
variable, which you already set in the OpenID Connect configuration file (/etc/nginx/conf.d/openid_connect_configuration.conf
).
Set up JWK Authorization using a Local File
In NGINX Plus R16 and earlier, NGINX Plus cannot access the JWK file via the URI. Instead, the JWK file must be on the local disk.
Take the steps below to set up JWK authorization using a local file:
- Copy the JSON contents from the JWK file named in the
jwks_uri
field to a local file. For example,/etc/nginx/my_okta_jwk.json
- In
/etc/nginx/conf.d/frontend.conf
, change the second parameter of theset $oidc_jwt_keyfile
directive to the local file path of the JWK file. - Confirm that the user named by the user directive in the NGINX Plus configuration – usually found in
/etc/nginx/nginx.conf
– has read permission on the JWK file.
Test Your Setup
- In a browser, enter the address of your NGINX Plus instance. You should be directed to the okta login page, as shown in the example below.
- Try to log in using the credentials of a user who is part of your organization.
Note:
If you restricted access to a group of users, be sure to select a user who has access to the application.
Troubleshooting
Refer to the Troubleshooting section in the nginx-openid-connect
repository on GitHub.
Revision History
- Version 3 (March 2022) – Full edit incorporating updates to Configuring Okta and Configuring NGINX Plus
- Version 2 (March 2020) – Updates to Configuring NGINX Plus section
- Version 1 (April 2019) – Initial version (NGINX Plus Release 17)