Single Sign-On with OneLogin

Enable OpenID Connect-based single-sign for applications proxied by NGINX Plus, using OneLogin as the identity provider (IdP).

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

For more information about integrating OpenID Connect with NGINX Plus, see the documentation for NGINX’s reference implementation on GitHub.


The instructions assume you have the following:

  • A OneLogin subscription.

  • 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/;

Configuring OneLogin

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

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

  1. Log in to your OneLogin account at, where domain is the domain you chose when you created your account.

  2. Click  Applications  in the title bar and then click the  Add App  button in the upper right corner of the window that opens.

  3. On the Find Applications page that opens, type OpenID Connect in the search box. Click on the OpenID Connect (OIDC) row that appears.

  4. On the Add OpenId Connect (OIDC) page that opens, change the value in the Display Name field to NGINX Plus and click the  Save  button.

  5. When the save completes, a new set of choices appears in the left navigation bar. Click Configuration. In the Redirect URI’s field, type the URI of the NGINX Plus instance including the port number, and ending in /_codexch (in this guide it is Then click the  Save  button.


    • 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).

  6. When the save completes, click SSO in the left navigation bar. Click Show client secret below the Client Secret field. Record the values in the Client ID and Client Secret fields. You will add them to the NGINX Plus configuration in Step 4 of Configuring NGINX Plus.

  7. Assign users to the application (in this guide, NGINX Plus) to enable them to access it for SSO. OneLogin recommends using roles for this purpose. You can access the Roles page under  Users  in the title bar.

Configuring NGINX Plus

Configure NGINX Plus as the OpenID Connect relying party:

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

    $ git clone
  2. Copy these files from the clone to /etc/nginx/conf.d:

    • frontend.conf
    • openid_connect.js
    • openid_connect.server_conf

  3. Get the URLs for the authorization endpoint, token endpoint, and JSON Web Key (JWK) file from the OneLogin configuration. Run the following curl command in a terminal, piping the output to the indicated python command to output the entire configuration in an easily readable format. We’ve abridged the output to show only the relevant fields.

    $ curl https://<OneLogin-server-address> | python -m json.tool
        "authorization_endpoint": "https://<domain>",
        "jwks_uri": "https://<domain>",
        "token_endpoint": "https://<domain>",

  4. 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:

    • set $oidc_authz_endpoint – Value of authorization_endpoint from Step 3 (in this guide, https://<domain>
    • set $oidc_token_endpoint – Value of token_endpoint from Step 3 (in this guide, https://<domain>
    • set $oidc_client – Value in the Client ID field from Step 6 of Configuring OneLogin (in this guide, 168d5600-9224-0137-3b2b-0acf<xxx>)
    • set $oidc_client_secret – Value in the Client secret field from Step 6 of Configuring OneLogin (in this guide, c9210a67d09e85<xxx>)
    • set $oidc_hmac_key – A unique, long, and secure phrase
  5. Configure the JWK file. The method depends on which version of NGINX Plus you are using.

    • In NGINX Plus R17 and later, NGINX Plus can read the JWK file directly from the URL reported as jwks_uri in Step 3. 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 value reported in the jwks_uri field in Step 3 (in this guide, https://<domain>
    • 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 named in the jwks_uri field in Step 3 (in this guide, https://<domain> to a local file (for example, /etc/nginx/my_onelogin_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.
  6. 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.


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 7 of Configuring OneLogin).


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

Revision History

  • Version 2 (March 2020) – Updates to Configuring NGINX Plus section
  • Version 1 (July 2019) – Initial version (NGINX Plus Release 18)