feat: new endpoints(/login, /userinfo, /v2/logout)

[shawnhankim]

Issue Item:

• access token and new endpoints (/login, /userinfo, /v2/logout) nginxinc/nginx-openid-connect#55
• Request to configure the reference implementation to access_token , id_token  nginxinc/nginx-openid-connect#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).

• Splitted an example of quick start guide from this repo to an external repo to avoid confusion 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.

[shawnhankim]

• Per discussion with @route443 ,
  • I have consolidated this PR into feat: access token & enhanced endpoints (/login, /userinfo, /logout) nginxinc/nginx-openid-connect#62.
  • @jputrino : We are going to have a separate PR regarding the doc. We will use your commit, and I am going to create another issue for your convenience.

Thanks @route443 and @jputrino !