Project: ORY Hydra (Provisioning / Key Management)
File: flow-cache-design-doc.md

This design doc outlines the proposed solution for caching the flow object in the OAuth2 exchange between the Client, Ory Hydra, and the Consent and Login UIs. The flow object contains the state of the authorization request. Currently, the flow object is stored in the database on the Ory Hydra server. This approach has several drawbacks: Each step of the OAuth2 flow (initialization, consent, login, etc.) requires a database query to retrieve the flow object, and another to update it. Each part of the exchanges supplies different values (login challenge, consent challenge, etc.) to identify the flow object. This means the database table has multiple indices that slow down insertions. The proposed solution is to store the flow object in client cookies and URLs. This way, the flow object is written only once when the flow is completed and the final authorization code is generated. The flow object must be stored in client cookies and URLs. The flow object must be secure and protect against unauthorized access. The flow object must be persistent, so that the flow can be resumed if the user navigates away from the page or closes the browser. The flow object must be scalable and able to handle a large number of concurrent requests. The proposed architecture for the flow cache is as follows: Store the flow object in an AEAD encrypted cookie. Pass a partial flow around in the URL. Use a secure connection to protect against unauthorized access. ```mermaid sequenceDiagram actor Client participant Hydra participant LoginUI as Login UI participant ConsentUI as Consent UI % participant Callback autonumber Client->>+Hydra: GET /oauth2/auth?clientid=CLIENTID&response_type=code&scope=SCOPES&state=STATE Hydra->>-Client: Redirect to <br> http://login.local/?loginchallenge=LOGINCHALLENGE Client->>+LoginUI: GET /?loginchallenge=LOGINCHALLENGE LoginUI->>Hydra: GET /admin/oauth2/auth/requests/login Hydra->>LoginUI: oAuth2LoginRequest alt accept login LoginUI->>Hydra: PUT /admin/oauth2/auth/requests/login/accept else reject login LoginUI->>Hydra: PUT /admin/oauth2/auth/requests/login/reject end Hydra->>LoginUI: oAuth2RedirectTo LoginUI->>-Client: Redirect to <br> http://hydra.local/oauth2/auth?clientid=CLIENTID&loginverifier=LOGINVERIFIER&response_type=code&scope=SCOPES&state=STATE Client->>+Hydra: GET /oauth2/auth?clientid=CLIENTID&loginverifier=LOGINVERIFIER&response_type=code&scope=SCOPES&state=STATE Hydra->>-Client: Redirect to <br> http://consent.local/?consentchallenge=CONSENTCHALLENGE Client->>+ConsentUI: GET /?consentchallenge=CONSENTCHALLENGE ConsentUI->>Hydra: GET /admin/oauth2/auth/requests/consent Hydra->>ConsentUI: oAuth2ConsentRequest alt accept login ConsentUI->>Hydra: PUT /admin/oauth2/auth/requests/consent/accept else reject login ConsentUI->>Hydra: PUT /admin/oauth2/auth/requests/consent/reject end Hydra->>ConsentUI: oAuth2RedirectTo ConsentUI->>-Client: Redirect to <br> http://hydra.local/oauth2/auth?clientid=CLIENTID&consentverifier=CONSENTVERIFIER&response_type=code&scope=SCOPES&state=STATE Client->>+Hydra: GET /oauth2/auth?clientid=CLIENTID&consentverifier=CONSENTVERIFIER&response_type=code&scope=SCOPES&state=STATE Hydra->>-Client: Redirect to <br>

Note over Hydra,Client: next, exchange code for token. % Client->>+Callback: GET /callback?code=AUTH_CODE&scope=SCOPES&state=STATE % Callback->>-Client: Return Authorization Code ``` Step 2: Set the whole flow as an AEAD encrypted cookie on the client The cookie is keyed by the `state`, so that multiple flows can run in parallel from one cookie jar Set the `LOGIN_CHALLENGE` to the AEAD-encrypted flow Step 5: Decrypt the flow from the `LOGIN_CHALLENGE`, return the `oAuth2LoginRequest` Step 8: Encode the flow into the redirect URL in `oAuth2RedirectTo` as the `LOGIN_VERIFIER` Step 11 Check that the login challenge in the `LOGIN_VERIFIER` matches the challenge in the flow cookie. Update the flow based on the request from the `LOGIN_VERIFIER` Update the cookie Set the `CONSENT_CHALLENGE` to the AEAD-encrypted flow Step 14: Decrypt the flow from the `CONSENT_CHALLENGE` Step 17: Encode the flow into the redirect URL in `oAuth2RedirectTo` as the `CONSENT_VERIFIER` Step 20 Check that the consent challenge in the `CONSENT_VERIFIER` matches the challenge in the flow cookie. Update the flow based on the request from the `CONSENT_VERIFIER` Update the cookie Write the flow to the database Continue the flow as currently implemented (generate the authentication code, return the code, etc.) For reference, these HTTP requests are issued by the client: ``` GET http://hydra.local/oauth2/auth?clientid=CLIENTID&nonce=NONCE&response_type=code&scope=SCOPES&state=STATE Redirect to http://login.local/?loginchallenge=LOGINCHALLENGE GET http://login.local/?loginchallenge=LOGINCHALLENGE Redirect to http://hydra.local/oauth2/auth?clientid=CLIENTID&loginverifier=LOGINVERIFIER&nonce=NONCE&response_type=code&scope=SCOPES&state=STATE GET http://hydra.local/oauth2/auth?clientid=CLIENTID&loginverifier=LOGINVERIFIER&nonce=NONCE&response_type=code&scope=SCOPES&state=STATE Redirect to http://consent.local/?consentchallenge=CONSENTCHALLENGE GET http://consent.local/?consentchallenge=CONSENTCHALLENGE Redirect to http://hydra.local/oauth2/auth?clientid=CLIENTID&consentverifier=CONSENTVERIFIER&nonce=NONCE&response_type=code&scope=SCOPES&state=STATE GET http://hydra.local/oauth2/auth?clientid=CLIENTID&consentverifier=CONSENTVERIFIER&nonce=NONCE&response_type=code&scope=SCOPES&state=STATE Redirect to http://callback.local/callback?code=AUTH_CODE&scope=SCOPES&state=STATE GET http://callback.local/callback?code=AUTH_CODE&scope=SCOPES&state=STATE ``` The implementation of the flow cache will involve the following steps: Modify the Ory Hydra server to store the flow object in an AEAD encrypted cookie. Modify the Consent and Login UIs to include the flow object in the URL. Use HTTPS to protect against unauthorized access. The proposed solution for caching the flow object in the OAuth2 exchange between the Client, Ory Hydra, and the Consent and Login UIs is to store the flow object in client cookies and URLs. This approach eliminates the need for a distributed cache and provides a scalable and secure solution. The flow object will be stored in an AEAD encrypted cookie and passed around in the URL. HTTPS will be used to protect against unauthorized access.