Skip to content

Latest commit

 

History

History

001-oidc-local-test

README.md

How To Set Up and Locally Test NGINX Plus OIDC

This is to provide how to set up IdP, NGINX Plus and locally test OIDC flow in your machine before implementing your frontend and backend application.

Note: The main README.md of this repo explains several options in detail. But this doc focuses on Quick Start Guide to quickly set up and test the OIDC flow locally using bundled frontend app and backend environment.

1. Prerequisites

  • Install and Run Docker in your local machine.

  • Edit hosts file in your laptop via if you want to locally test NGINX Plus OIDC:

    $ sudo vi /etc/hosts or notepad.exe c:\Windows\System32\Drivers\etc\hosts

127.0.0.1 www.example.com
127.0.0.1 host.docker.internal

    Note: In this example, Keycloak is used as it can be installed as one of Docker containers in your local machine.

  • Download NGINX Plus license files, and copy them to ./docker/build-context/ssl/

    nginx-repo.crt
nginx-repo.key

  • Clone the nginx-openid-connect/nginx-oidc-examples GitHub repository, or download the repo files.

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

  • Change the working directory.

    cd nginx-oidc-examples/001-oidc-local-test

2. Running a Docker Container

  • Start a Docker container:

    $ make start

    Note:

    • In this example, a Keycloak container image (jboss/keycloak:15.1.0) is used.
    • Please try another version of Keycloak container images in docker-compose.yml if you have any issue when starting it in your local machine.

  • Check Docker container's status:

    $ make watch

3. Running a Browser and Checking If Bundle Page Works

  • Run a Web Browser with http://www.example.com:8010/, and check if the bundle frontend landing page is shown:

4. Setting up an Identity Provider (IdP)

Choose one of your prefered IdPs, and set up your IdP by referencing the following guides:

Notes:

  • In this example, Keycloak is used as it can be installed as one of Docker containers in your local machine.
    • Client ID: my-client-id
    • Access Type: public for PKCE
    • Valid Redirected URIs:
      • http://www.example.com:8010/_codexch
      • http://www.example.com:8010/_logout
  • The above references will be eventually consolidated into the NGINX Docs. So feel free to contribute the repo to make better examples for each IdP as references.

5. Configuring NGINX Plus

Update the NGINX Plus configuration file if you want. Otherwise, skip the following steps for your quick test as the minimal config information is already provided in this repo.

  • In the openid_connect_configuration.conf, find and update $oidc_authz_endpoint, $oidc_token_endpoint, $oidc_jwt_keyfile, $oidc_logout_endpoint, $oidc_userinfo_endpoint, $oidc_client, $oidc_pkce_enable, $oidc_client_secret, and $oidc_scopes upon your setup in IdP.

      map $host $oidc_authz_endpoint {
      default "http://host.docker.internal:8080/auth/realms/master/protocol/openid-connect/auth";
  }

  map $host $oidc_token_endpoint {
      default "http://host.docker.internal:8080/auth/realms/master/protocol/openid-connect/token";
  }

  map $host $oidc_jwt_keyfile {
      default "http://host.docker.internal:8080/auth/realms/master/protocol/openid-connect/certs";
  }

  map $host $oidc_logout_endpoint {
      default "http://host.docker.internal:8080/auth/realms/master/protocol/openid-connect/logout";
  }

  map $host $oidc_userinfo_endpoint {
      default "http://host.docker.internal:8080/auth/realms/master/protocol/openid-connect/userinfo";
  }

  map $host $oidc_client {
      default "my-client-id";
  }

  map $host $oidc_pkce_enable {
      default 1;
  }

  map $host $oidc_client_secret {
      default "my-client-secret";
  }

  map $host $oidc_scopes {
      default "openid+profile+email+offline_access";
  }

  map $host $oidc_landing_page {
      # Where to send browser after successful login. This option is only
      # recommended for scenarios where a landing page shows default information
      # without login, and the RP redirects to the landing page after successful
      # login from the OP. If this is empty, then the RP redirects to $request_uri.
      default "";
      www.example.com $redirect_base;
  }

  map $host $post_logout_return_uri {
      # Where to send browser after the RP requests /logout to the OP, and after
      # the RP (/_logout) is called by the OP and cleans cookies. The following
      # If this is empty, then the RP redirects to $request_uri.

      default "";

      # Edit if you want to redirect to the landing page
      www.example.com $oidc_landing_page;

      # Edit if you want to redirect to a custom logout page
      #www.example.com $redirect_base/signout;

      # Edit if you want to redirect to an another complete URL
      #www.example.com https://www.nginx.com;
  }

  • In the openid_connect.server_conf, find the directive of $resolver and update it,

    resolver 127.0.0.11; # For local Docker DNS lookup
         #  8.8.8.8; # For global DNS lookup of IDP endpoint

  • Restart the instance of NGINX Plus

    docker exec -it nginxplus-oidc-keycloak bash
nginx -t
nginx -s reload

6. Testing NGINX Plus OIDC

  • Click Sign In button:

  • Click Call a Sample Proxied API button:

    Note:

    • In the frontend.conf, you can add additional API endpoints like:

      location /v1/private-api {
    auth_jwt "" token=$access_token;      # Use $session_jwt for Azure AD
    auth_jwt_key_request /_jwks_uri;      # Enable when using URL

    proxy_set_header Authorization "Bearer $access_token";
    proxy_pass http://my_backend;
}

    • So you can enter a different URI for testing your additional API endpoints via this bundled frontend tool.

  • Click Sign Out button:

    • Redirect to the original landing page if you configure $post_logout_return_uri with $oidc_landing_page as the following example:

      map $host $oidc_landing_page {
    default "";
    www.example.com $redirect_base;
}

map $host $post_logout_return_uri {
  default "";
  www.example.com $oidc_landing_page;
}

    • Redirect to the custom logout page if you configure $post_logout_return_uri with $redirect_base/signout such as a custom URI as the following example:

      map $host $post_logout_return_uri {
    default $redirect_base/signout;
}

7. Stop and Remove Docker Containers

  • Stop Docker containers

    $ make down

  • Remove Docker container images

    $ make clean