diff --git a/rfd/0103-application-access-web-ui-auth-flow.md b/rfd/0103-application-access-web-ui-auth-flow.md new file mode 100644 index 0000000000000..29d99909dbbc0 --- /dev/null +++ b/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.