Skip to content

Commit

Permalink
fix: update JWT mentions across all docs (#1579)
Browse files Browse the repository at this point in the history
Closes #1576
  • Loading branch information
vinckr authored Oct 16, 2023
1 parent 02998eb commit 86723d1
Show file tree
Hide file tree
Showing 3 changed files with 18 additions and 22 deletions.
24 changes: 14 additions & 10 deletions docs/kratos/session-management/01_overview.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,8 @@ Sessions can be issued in two formats:
- **Ory Session Token** - when the system detects that the interaction is performed by a client other than a web browser, for
example a native mobile app, a session token is issued to the client.

You can also convert an Ory Session to a JWT, read more about this approach [here](#json-web-token-jwt-support).

:::note

For security reasons, you can't break the isolation between cookies and session tokens.
Expand Down Expand Up @@ -197,13 +199,7 @@ import nativeWhoAmI from "!!raw-loader!@site/code-examples/sdk/typescript/src/se

## JSON Web Token (JWT) support

:::warning

Ory doesn't issue sessions as JSON Web Tokens (JWTs).

:::

Sessions are not issued as JWTs for two main reasons:
Sessions are by default not issued as JWTs for two main reasons:

1. Sessions can end at any point in time, indicating that the user is no longer signed in. With JWTs, it's difficult to determine
if a session is still valid before the token expires.
Expand All @@ -213,10 +209,18 @@ Sessions are not issued as JWTs for two main reasons:
Ory Network employs a session caching mechanism to reduce the latency for `toSession` / `/sessions/whoami` endpoint calls across
the globe so that latency is not an issue for users. [Read more about session caching.](../../concepts/cache.mdx)

If you don't want to make repeated calls to `toSession` / `/sessions/whoami`, or you need to use JWTs in your setup, you can
convert sessions to JWTs on your entry point. There, you could add caching to further reduce the number of API calls made.
If you don't want to make repeated calls to `toSession` / `/sessions/whoami`, or you need to use JWTs in your setup, you have
several options:

- **Recommended**: Use [Session to JWT](../../identities/session-to-jwt-cors.mdx). Read more in the
[Session to JWT](../../identities/session-to-jwt-cors.mdx) documentation.
- Alternative: Convert sessions to JWTs on your entry point. You then have the option to add caching to further reduce the number
of API calls made. More information on this approach is available in the
[section below](#use-ory-oathkeeper-to-convert-sessions-to-jwts).

### Use Ory Oathkeeper to convert sessions to JWTs

:::tip
:::info

[Ory Oathkeeper](https://www.ory.sh/oathkeeper) is an API Gateway capable of converting sessions to JWTs.

Expand Down
14 changes: 3 additions & 11 deletions docs/security-model.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -156,18 +156,10 @@ Notable mentions are:

## What about JSON Web Tokens?

Currently, Ory Identities doesn't support JSON Web Tokens (JWTs) natively.
To learn how Ory Identities supports JSON Web Tokens (JWTs) to manage sessions read the
[Session mangagement documentation](./kratos/session-management/01_overview.mdx).

:::note

Do you need JWTs in your implementation? Let us know in
[this issue for Ory Identities (Kratos)](https://github.com/ory/kratos/issues/2487).

:::

[Ory Zero Trust Identity and Access Proxy (Ory Oathkeeper)](https://www.ory.sh/oathkeeper) can "convert" Ory Sessions to JSON Web
Tokens. Using Ory Oathkeeper is recommended when developing sophisticated applications with control over network traffic (think
Kubernetes, OpenShift).
To learn how to use Session to JWT, read the [Session to JWT documentation](./identities/session-to-jwt-cors.mdx).

## Can I use OAuth 2.0 / OpenID Connect?

Expand Down
2 changes: 1 addition & 1 deletion src/sidebar.js
Original file line number Diff line number Diff line change
Expand Up @@ -128,7 +128,7 @@ module.exports = {
"kratos/self-service/flows/account-recovery-password-reset",
{
type: "category",
label: "Managing sessions",
label: "Manage sessions",
items: [
{
type: "autogenerated",
Expand Down

0 comments on commit 86723d1

Please sign in to comment.