Multiple cookies and tracking ID refactoring

[byewokko]

Breaking changes

• Clients that use cookie introspection need to have cookie_entry_uri configured.
• Authorize requests can have either openid or cookie in scope but not both.
• Authorize requests with cookie in scope redirect to cookie entry URI (which must be configured) and pass the original redirect URI in the query. The cookie entry point then redirects to the original redirect URI.
• The state mechanism in the Cookie service has been removed. Redirect URI is passed in the cookie entry query.
• Sessions within the same group do not share cookie value anymore. Each cookie session has its own unique cookie value.

Cookies

• Every cookie session has a unique cookie ID (cookie value). This ID alone is sufficient for locating a session.
• Client cookies have have a distinct cookie name of the format SeaCatSCI_<CLIENT_ID_HASH>, for example SeaCatSCI_KKJGBAVXYM2P2UQW.
• Track ID is now passed at the cookie entrypoint (for cookie sessions) or at the authorize endpoint (for oauth2 sessions).
• Root session is initially created without Track ID. It gets one at its first authorize or cookie entry call.

Cookie introspection setup

• Use the Seacat Admin API to create a client. Note your client_id.

  • If you want to enable redirection to any endpoint in your app, set the redirect_uri_validation_method to prefix_match and add your app's base URL to redirect_uris.
  • Fill in cookie_entry_uri, the endpoint where your app's cookie entrypoint will be available (after you set it up in Nginx). It needs to be located on the same hostname as your app's web interface. In this example, we set it to https://app.example.test/my_app_bouncer.

• Set up cookie introspection in Nginx. Replace <CLIENT_ID> with your actual client ID.

  location = /_my_app_auth {
  internal;
  proxy_method          POST;
  proxy_set_body        "$http_authorization";
  proxy_pass            http://seacat_auth_api/cookie/nginx?client_id=<CLIENT_ID>;
  # ... set up proxy caching, header filtering etc.
  }

• Set up cookie entry point in Nginx. Replace <CLIENT_ID> with your actual client ID.

  location /my_app_bouncer {
  proxy_method          POST;
  proxy_set_header      Content-Type "application/x-www-form-urlencoded";
  proxy_set_body        "client_id=<CLIENT_ID>&grant_type=authorization_code&code=$arg_code";
  proxy_pass            http://seacat_auth_api/cookie/entry;
  # ... set up caching, header filtering etc.
  }

• Set up your protected location in Nginx. Replace <CLIENT_ID> with your actual client ID.

  location /my_app {
  rewrite ^/my_app(/(.*))? /$2 break;
  proxy_pass http://my_app_api;
  
  auth_request /_my_app_auth;
  
  # Add ID token to Auth header
  auth_request_set      $authorization $upstream_http_authorization;
  proxy_set_header      Authorization $authorization;
  
  # Rewrite the Cookie header
  auth_request_set      $cookie $upstream_http_cookie;
  proxy_set_header      Cookie $cookie;
  
  # Set the Seacat Auth cookie
  auth_request_set   $set_cookie $upstream_http_set_cookie;
  add_header  Set-Cookie $set_cookie;
  
  # Perform authorization in case of 401 and redirect back
  error_page 401 https://auth.example.test/auth/api/openidconnect/authorize?response_type=code&scope=cookie%20&client_id=<CLIENT_ID>&redirect_uri=https://app.example.test$request_uri;
  }

Setting custom HTTP headers using a webhook

• Cookie entrypoint (bouncer) and anonymous introspection can trigger a synchronous webhook and set custom cookies from the webhook response.
• The client must have the cookie_webhook_uri attribute configured to a valid URL.
• The webhook URL must accept a PUT request with JSON-serialized session data and respond with a JSON objects that define the cookies that are to be set, for example:

  {
  "response_headers": {
  "X-Whatever": "important-header-text",
  "My-Custom-Header": "KKJGBAVXYM2P2UQW"
  }
  }

Setting custom cookies

The webhook can be used to setting custom cookies if Nginx is configured accordingly. The webhook must provide the cookie name and value and optionally other parameters. Seacat Auth will propagate that data in the auth request response header. You can then use the auth_request_set directive to extract the header value from the response and the add_header to create a new Set-Cookie header with that value. Example webhook payload:

{
 "response_headers": {
  "Set-My-Custom-Cookie": "MyCustomCookie=d75bj6czt5gi7d6xdrtvxrt; HttpOnly; Secure"
 }
}

Example nginx location config

location /protected {
  auth_request /my_app_anon_auth;
  # Set Seacat client cookie (no change here, same as before)
  auth_request_set   $set_cookie $upstream_http_set_cookie;
  add_header    Set-Cookie $set_cookie;
  # Set MyCustomCookie
  auth_request_set   $my_custom_cookie $upstream_http_my_custom_cookie;
  add_header    Set-Cookie $my_custom_cookie;
  ...
}

Client config

New client attributes have been added:

• cookie_entry_uri - cookie entrypoint uri, necessary for cookie requests
• cookie_webhook_uri - location where the cookie entrypoint sends webhook PUT requests
• anonymous_cid - credentials ID to use for anonymous sessions, necessary for anonymous access