feat: new endpoints(/login, /userinfo, /v2/logout) and a bundle OIDC simulation environment

[shawnhankim]

Issue Item:

• https://github.com/nginxinc/nginx-openid-connect/issues/55
• https://github.com/nginxinc/nginx-openid-connect/issues/33

Background:

• Current NJS implementation doesn’t have /login and /userinfo endpoints for client apps (SPA) to interact with.
• Client Apps require /login function as part of relying party when a user clicks on login button from the landing page.
• Client Apps require /userinfo function as part of relying party when a user wants to verify the session cookie created by NGINX Plus is still valid or to get some user info about users which is needed for the Client Apps.
• The existing /logout function is required to extend the sign-off function on the IdP's end_session_endpoint. Afterwards the NGINX Plus' logout redirection URI (which is redirected by IdP after successful logout from IdP) can clear session cookies and redirect to the either original landing page or a custom logout page.

Description:

• Added /userinfo endpoint:

  • Add a map variable of $oidc_userinfo_endpoint as same as authz and token endpoints here (openid_connect_configuration.conf) .
  • Expose /userinfo endpoint here(openid_connect.server_conf) in a location block of NGINX Plus to interact with IdP's userinfo_endpoint which is defined in the endpoint ofwell-known/openid-configuration.
  • The nginx location block should proxy to the IdP’s userinfo_endpoint by adding access_token as a bearer token.

    Authorization : Bearer <access_token>

  • The response coming from IdP should be returned back to the caller as it is.

• Exposed /login endpoint:

  • Expose the /login endpoint as a location block here (openid_connect.server_conf)
  • Proxy it to existing IdP's authorization_endpoint configured in the map variable of $oidc_authz_endpoint in (openid_connect_configuration.conf).
  • This would outsource the login function to IdP as its configured.

• Exposed /v2/logout endpoint or enhance /logout endpoint:

  • Add a map variable of $oidc_end_session_endpoint as same as authz and token endpoints here (openid_connect_configuration.conf) .

  • Add a map of $post_logout_return_uri: After the successful logout from the IdP, NGINX Plus calls this URI to redirect to either the original page or a custom logout page. The default is original page based on the configuration of $redirect_base.

  • Exposed endpoints of /v2/logout and /v2/_logout

    • /v2/logout: NGINX Plus calls IdP's end session endpoint ($oidc_end_session_endpoint) to finish the session by IdP.
    • /v2/_logout (Callback endpoint):
    • 1. Redirected by IdP when IdP successfully finished the session.
    • 2. NGINX Plus: Clear session cookies.
    • 3. NGINX Plus: Redirect to either the original landing page or the custom logout page by calling `$post_logout_return_uri.

  • FYI. We can just enhance endpoints of /logout and /_logout without adding new endpoints of /v2/logout and /v2/_out if this doesn't block the existing customer, and if they can update this reference implementation in their configuration:

    • As-Is: NJS implementation provides an example of clearing cookie, and show a simple logout message. So customers need to implement full business logic to interact with IdP's end session endpoint.
    • To-Be: Existing customers can either keep the legacy business logic or replace the reference implementation from /v2/logout & /v2/_logout to /logout and /_logout.

  • Capture logout endpoint (oidc_logout_endpoint of IDP in a map variable as same as authz and token endpoints here (openid_connect_configuration.conf).

• Added a bundle SPA to simulate OIDC.

  • Provide a frontend application to easily simulate OIDC workflow.
    • Login button
    • Logout button
    • Call a proxied API button by adding a sample API endpoint to test an API resource using access token that is received by IDP.

  

  

• Added a Docker container environment to locally simulate OIDC.

• Added a doc of how to set up and locally test OIDC here.

Assumptions:

• IdP is configured with $oidc_logout_redirect_uri at the time of creating the resource credentials along with /_codexch.
• It is expected that NGINX Plus would always verify the token(s) validity and integrity before sending it to the client or backend.
• Developers replace a bundle SPA with their app after making sure the OIDC setup/test work among a bundle SPA, NGINX Plus and IdP.

[shawnhankim]

Per discussion with @route443 , I close this PR and have consolidated it into https://github.com/nginxinc/nginx-openid-connect/pull/62. The doc PR will be separately raised.