Add "How Clerk works" and "Client handshake" to initial concepts section #577
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
Hey @alexisintech, your docs preview is available.
|
|
I'll provide my review once the information is reviewed by an engineer more familiar with this information and is deemed technically correct :) |
kylemac
reviewed
Dec 20, 2023
Co-authored-by: Kyle MacDonald <kylemac@users.noreply.github.com>
|
Updated based on @SokratisVidros's feedback in the deploy preview. @alexisintech please do an editorial sweep and merge. |
Co-authored-by: Sokratis Vidros <SokratisVidros@users.noreply.github.com>
Co-authored-by: Sokratis Vidros <SokratisVidros@users.noreply.github.com>
BRKalow
reviewed
Jan 9, 2024
SokratisVidros
suggested changes
Jan 11, 2024
| ### Handshake payload | ||
|
|
||
| The handshake payload is a signed JWT that contains an array of `set-cookie` header directives. This allows us to transfer cookies from the FAPI domain to the application’s domain across environments without additional cookie setting logic embedded into our SDKs. In development, the payload is transported in the URL in a `__clerk_handshake` query parameter. In production, the payload is transported in a `__clerk_handshake` cookie. On returning from the handshake endpoint, the handshake payload is parsed and the cookie directives are set on the final response. | ||
|
|
There was a problem hiding this comment.
@BRKalow Please add an example of a Handshake payload.
There was a problem hiding this comment.
@alexisintech Please add the following example of the handshake payload:
"handshake": [
"__client_uat=; Path=/; Expires=Thu, 01 Jan 1970 00:00:00 GMT",
"__clerk_handshake=; Path=/; Domain=example.com; Expires=Thu, 01 Jan 1970 00:00:00 GMT",
"__client_uat=1706822359; Path=/; Domain=example.com; Max-Age=315360000; Secure; SameSite=Lax",
"__session=<...CLERK_SESSION_JWT...>; Path=/; Expires=Wed, 05 Feb 2025 09:08:53 GMT; Secure"
]
}```
| The `__session` cookie is set on the host application that is secured by Clerk (for example `https://dashboard.<example.com>`). It’s a JS cookie, it’s secure, and it contains a short-lived session JWT that lasts 60 seconds. This JWT contains the current session, user, and organization identifiers and must be sent to the application API to authenticate API requests. In SSR, the `__session` cookie travels automatically to the server. ClerkJS ensures that the `__session` cookie is automatically refreshed in Client Side Rendering (CSR) and Server Side Rendering (SSR), ensuring a fresh session is always available. | ||
|
|
||
| However, if a `__session` cookie is expired on a request to an application’s backend, the SDK doesn’t know if the session has ended, or if a new short-lived JWT needs to be issued. When an SDK gets into this state, it triggers Clerk's client handshake. | ||
|
|
There was a problem hiding this comment.
The __client_uat cookie
This __client_uat cookie is set on the host application that is secured by Clerk and hints Clerk SDKs about the timestamp of the latest authentication update of the current client.
There was a problem hiding this comment.
@alexisintech Please add this ☝️
Co-authored-by: Bryce Kalow <bryce@clerk.dev>
SokratisVidros
suggested changes
Feb 5, 2024
| ### Handshake payload | ||
|
|
||
| The handshake payload is a signed JWT that contains an array of `set-cookie` header directives. This allows us to transfer cookies from the FAPI domain to the application’s domain across environments without additional cookie setting logic embedded into our SDKs. In development, the payload is transported in the URL in a `__clerk_handshake` query parameter. In production, the payload is transported in a `__clerk_handshake` cookie. On returning from the handshake endpoint, the handshake payload is parsed and the cookie directives are set on the final response. | ||
|
|
There was a problem hiding this comment.
@alexisintech Please add the following example of the handshake payload:
"handshake": [
"__client_uat=; Path=/; Expires=Thu, 01 Jan 1970 00:00:00 GMT",
"__clerk_handshake=; Path=/; Domain=example.com; Expires=Thu, 01 Jan 1970 00:00:00 GMT",
"__client_uat=1706822359; Path=/; Domain=example.com; Max-Age=315360000; Secure; SameSite=Lax",
"__session=<...CLERK_SESSION_JWT...>; Path=/; Expires=Wed, 05 Feb 2025 09:08:53 GMT; Secure"
]
}```
| The `__session` cookie is set on the host application that is secured by Clerk (for example `https://dashboard.<example.com>`). It’s a JS cookie, it’s secure, and it contains a short-lived session JWT that lasts 60 seconds. This JWT contains the current session, user, and organization identifiers and must be sent to the application API to authenticate API requests. In SSR, the `__session` cookie travels automatically to the server. ClerkJS ensures that the `__session` cookie is automatically refreshed in Client Side Rendering (CSR) and Server Side Rendering (SSR), ensuring a fresh session is always available. | ||
|
|
||
| However, if a `__session` cookie is expired on a request to an application’s backend, the SDK doesn’t know if the session has ended, or if a new short-lived JWT needs to be issued. When an SDK gets into this state, it triggers Clerk's client handshake. | ||
|
|
There was a problem hiding this comment.
@alexisintech Please add this ☝️
Co-authored-by: Sokratis Vidros <SokratisVidros@users.noreply.github.com>
SokratisVidros
approved these changes
Feb 5, 2024
|
this PR is waiting on @kylemac and the decisions surrounding the new docs IA - converting back to draft for now. |
Merged
alexisintech
changed the title
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
We have an internal copy of this document we have talked about moving externally for some time. This is how that could look:
https://docs-preview-577.clerkpreview.com/docs/concepts/how-clerk-works
https://docs-preview-577.clerkpreview.com/docs/concepts/client-handshake
Related to PR-867 in the marketing repo which adds a lightbulb icon for the "Concepts" section in the sidenav.