Authentication flow - guardian/support-frontend GitHub Wiki

sequenceDiagram
  autonumber
  Participant B as Browser
  Participant A as Maybe authenticated action
  Participant O as Auth server
  Participant API
  B->>A: Request
  alt Signed-out cookie, GU_SO, present
    A->>B: Without ID  
  else
    alt Token cookies present
      A->>A: Find auth tokens
      A->>API: Use access token
      A->>B: Use ID token
    else
      A->>O: Silent authentication
      alt User signed in
        A->>API: Use access token
        A->>B: Use ID token
      else
        A->>B: Without ID
      end
    end
  end

Notes

  1. Browser makes a request to a support-frontend endpoint that is wrapped in a MaybeAuthenticatedAction.
  2. As the user has recently signed out, the response is returned with any token cookies included in the request deleted. No calls to APIs will be possible and the response to the request will have no access to ID claims. Nevertheless, the response will still succeed.
    See https://github.com/guardian/support-frontend/blob/main/support-frontend/app/actions/UserFromAuthCookiesActionBuilder.scala#L86
  3. The request includes a GU_ID_TOKEN cookie and a GU_ACCESS_TOKEN cookie containing an ID and an access token respectively. These are verified and used to create a User instance, which is available for subsequent processing in the requested action.
    See https://github.com/guardian/support-frontend/blob/main/support-frontend/app/actions/UserFromAuthCookiesActionBuilder.scala#L111
  4. The action makes calls out to APIs using the access token provided in the cookie.
  5. The response to the request uses the claims in the ID token to populate user-specific fields.
  6. The request is redirected through a silent auth code with PKCE flow. This responds with ID and access tokens if the user is signed in to the auth server.
    See https://github.com/guardian/support-frontend/blob/main/support-frontend/app/controllers/AuthCodeFlowController.scala#L44-L68
  7. The action makes calls out to APIs using the access token provided by the auth flow.
  8. The response to the request includes new GU_ID_TOKEN and GU_ACCESS_TOKEN cookies. The claims in the ID token are used to populate user-specific fields in the response.
  9. As the user isn't signed in, no calls to APIs will be possible and the response to the request will have no access to ID claims. Nevertheless, the response will still succeed.