Skip to content

Latest commit

 

History

History
66 lines (41 loc) · 3.98 KB

usage.md

File metadata and controls

66 lines (41 loc) · 3.98 KB
Raw

Usage

The contract for using Wonderwall is fairly straightforward.

For any endpoint that requires authentication:

  1. Validate the Authorization header, and any tokens within.
  2. If the Authorization header is missing, redirect the user to the login endpoint.
  3. If the JWT access_token in the Authorization header is invalid or expired, redirect the user to the login endpoint.
  4. If you need to log out a user, redirect the user to the logout endpoint.

Note that Wonderwall does not validate the access_token that is attached; this is the responsibility of the upstream application. Wonderwall only validates the id_token in accordance with the OpenID Connect Core specifications.

Scenarios

1. Login

When you must authenticate a user, redirect to the user to the /oauth2/login endpoint.

1.1. Autologin

The auto-login option will configure Wonderwall to enforce authentication for all requests, except for the paths that are explicitly excluded.

If the user is unauthenticated or has an inactive or expired session, all requests will be short-circuited (i.e. return early and not proxied to your application). The short-circuited response depends on whether the request is a top-level navigation request or not. A top-level navigation request has the following properties:

  1. Is a GET request
  2. Has the Fetch metadata headers Sec-Fetch-Dest=document and Sec-Fetch-Mode=navigate

If the user agent does not support the Fetch metadata headers, we look for an Accept header that includes text/html, which all major browsers send for navigation requests. Internet Explorer 8 won't work with this of course, so hopefully you're not in a position that requires supporting this browser.

A top-level navigation request results in a HTTP 302 Found response with the Location header pointing to the /oauth2/login endpoint. The redirect parameter in the login URL is set to the value found in the Referer header, so that the user is redirected back to their intended location after login. If the Referer header is empty, the redirect parameter is set to the matching ingress path for the original request.

Other requests are considered non-navigational requests, and they will result in a HTTP 401 Unauthorized response with the Location header set as described above.

For defence in depth, you should still check the Authorization header for a token and validate the token even when using auto-login.

2. Logout

When you must log out a user, redirect to the user to the /oauth2/logout endpoint.

The user's session with the sidecar will be cleared, and the user will be redirected to the identity provider for global/single-logout, if logged in with SSO (single sign-on) at the identity provider.

2.1 Local Logout

If you only want to perform a local logout for the user, perform a GET request from the user's browser / user agent to the /oauth2/logout/local endpoint.

This will only clear the user's local session (i.e. remove the cookies) with the sidecar, without performing global logout at the identity provider. The endpoint responds with a HTTP 204 after successful logout. It will not respond with a redirect.

A local logout is useful for scenarios where users frequently switch between multiple accounts. This means that they do not have to re-enter their credentials (e.g. username, password, 2FA) between each local logout, as they still have an SSO-session logged in with the identity provider. If the user is using a shared device with other users, only performing a local logout is thus a security risk.

Ensure you understand the difference in intentions between the two logout endpoints. If you're unsure, use /oauth2/logout.

3. Advanced: Session Management

See the session management page for details.