RFD 103: Application Access Web UI Auth Flow

rfd/0103-application-access-web-ui-auth-flow.md

@@ -0,0 +1,74 @@
+---
+authors: Ryan Clark (ryan.clark@goteleport.com)
+state: draft
+---
+
+# RFD 103 - Application Access Web UI Auth Flow
+
+## What
+
+This is an overview of the flow used for setting the relevant cookies when a user logs in to an 
+application through Teleport Web UI.
+
+## Why
+
+The method used to set cookies on a different domain requires a few changes to Teleport's default security 
+mechanisms. It's important these changes are documented and understood for future reference.
+
+## Details
+
+When a user wants to login to an application, a new application session is created in
+the auth service. This application session has two values (a name and a bearer token) that need to be provided 
+as cookies when the user navigates to the application's URL.
+
+The flow to be able to set the needed cookies from the application session across different domains is
+as follows:
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant Proxy UI
+    participant Application
+    participant Auth Service
+    User->>Proxy UI: Launch Application
+    Proxy UI->>Auth Service: Create App Session /v1/webapi/sessions/app
+    Auth Service->>Proxy UI: Returns two cookie values (app session & subject)
+    Proxy UI->>Application: CORS preflight request to appurl.com/x-teleport-auth
+    Application->>Proxy UI: Matches Origin against public proxy addresses & allows CORS if a match
+    Proxy UI->>Application: POST appurl.com/x-teleport-auth with the cookie values in the header
+    Application->>Proxy UI: Sets the cookies on appurl.com if they are valid
+    Proxy UI->>User: User is logged in, redirect to appurl.com
+```
+
+### CORS
+
+As we need to enable cross-origin requests from the proxy URL to the application URL, we add middleware
+before `/x-teleport-auth` to check the `Origin` header (this cannot be changed via a `fetch` request).
+
+We check the origin against the public addresses of the proxy, and if one is a match, we allow a cross-origin 
+request.
+
+The rules around the cross-origin request are strict and the absolute minimum needed:
+
+- Must be a `POST` request
+- Only allowed for the `/x-teleport-auth` endpoint
+- Only allows the headers `X-Cookie-Value` and `X-Subject-Cookie-Value` to be set
+- Only allowed from one of the public proxy addresses
+
+### Content Security Policy
+
+Teleport's default content security policy disallows cross-origin requests by setting `connect-src` to `'self' wss:`. 
+
+To allow for the request to the application's domain, we modify the content security policy for `/web/launch` URLs
+only. This changes `connect-src` to `'self' https://applicationfqdn:*`, which allows requests to both proxy as 
+normal, and the application's FQDN.
+
+### Cookie Validity Checking
+
+In the handler for `/x-teleport-auth`, we take the cookie values from the headers and use `X-Cookie-Value` to 
+look-up the application session created by the auth service.
+
+If this application session exists, we then check the value of the `X-Subject-Cookie-Value` header against the
+bearer token stored in the application session.
+
+If these both match, we set the relevant cookies to log the user in once they're redirected to the application.