Overview
When a user authenticates, for example by signing in with their username and password, they receive a session. The session is proof that the user is authenticated and allows to interact with the system without the need to re-authenticate for every request.
Sessions can be issued in two formats:
- Ory Session Cookie - when the system detects that the interaction is performed through a web browser, a cookie which represents the user's session is stored in the browser.
- 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.
For security reasons, you can't break the isolation between cookies and session tokens.
Ory session
This is a sample session:
{
"active": true,
"authenticated_at": "2019-08-24T14:15:22Z",
"authentication_methods": [
{
"aal": "aal1",
"completed_at": "2019-08-24T14:15:22Z",
"method": "password"
}
],
"authenticator_assurance_level": "aal1",
"devices": [
{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"ip_address": "string",
"location": "string",
"user_agent": "string"
}
],
"expires_at": "2019-08-24T14:15:22Z",
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"identity": {
"created_at": "2019-08-24T14:15:22Z",
"credentials": {
"property1": {
"config": {},
"created_at": "2019-08-24T14:15:22Z",
"identifiers": ["string"],
"type": "password",
"updated_at": "2019-08-24T14:15:22Z",
"version": 0
},
"property2": {
"config": {},
"created_at": "2019-08-24T14:15:22Z",
"identifiers": ["string"],
"type": "password",
"updated_at": "2019-08-24T14:15:22Z",
"version": 0
}
},
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"metadata_admin": {},
"metadata_public": {},
"recovery_addresses": [
{
"created_at": "2019-08-24T14:15:22Z",
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"updated_at": "2019-08-24T14:15:22Z",
"value": "string",
"via": "string"
}
],
"schema_id": "string",
"schema_url": "string",
"state": "active",
"state_changed_at": "2019-08-24T14:15:22Z",
"traits": null,
"updated_at": "2019-08-24T14:15:22Z",
"verifiable_addresses": [
{
"created_at": "2014-01-01T23:28:56.782Z",
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"status": "string",
"updated_at": "2014-01-01T23:28:56.782Z",
"value": "string",
"verified": true,
"verified_at": "2019-08-24T14:15:22Z",
"via": "string"
}
]
},
"issued_at": "2019-08-24T14:15:22Z"
}
| Property | Description |
|---|---|
active | When set to true, the Ory Session is active and can be used to authenticate requests. |
expires_at | Defines the time when the Session expires. This value depends on the session lifespan configuration. |
authenticated_at | Indicates the time of the most recent successful authentication. This value is updated when:
|
Using Ory Session Cookie
An Ory Session Cookie is issued when the user signs in through the browser-based login flow. To get the session payload, send a
request to the /sessions/whoami endpoint.
Browser-based applications including single-page applications (SPAs) and server-side rendered apps should use session cookies instead of session tokens.
- React
- cURL
import { Configuration, FrontendApi, Session } from "@ory/client"
import { useEffect, useState } from "react"
const frontend = new FrontendApi(
new Configuration({
basePath: "http://localhost:4000", // Use your local Ory Tunnel URL
baseOptions: {
withCredentials: true,
},
}),
)
export function checkSession() {
const [session, setSession] = useState<Session>(undefined)
useEffect(() => {
frontend
// the cookie is automatically sent with the request
.toSession()
.then(({ data: session }) => {
setSession(session)
})
.catch((error) => {
// The session could not be fetched
// This might occur if the current session has expired
})
}, [])
return session ? (
<table>
<tr>
<th>Session ID</th>
<th>Expires at</th>
<th>Authenticated at</th>
</tr>
<tr id={session.id}>
<td>{session.id}</td>
<td>{session.expires_at || ""}</td>
<td>{session.authenticated_at || ""}</td>
</tr>
</table>
) : (
<div>Loading session data...</div>
)
}
curl 'https://$PROJECT_SLUG.projects.oryapis.com/sessions/whoami' \
-H 'Accept: application/json' \
-H 'Cookie: ory_kratos_session=MTYzNDIyNzEzN3xEdi1CQkFFQ180SUFBUkFCRUFBQVJfLUNBQUVHYzNSeWFXNW5EQThBRFhObGMzTnBiMjVmZEc5clpXNEdjM1J5YVc1bkRDSUFJRTFDYWtvME5VNVlaVWxvYVZWeWJrUnZhSEF4YmxSV2VVRlhNMWwxVlVGenxXpsk2cL21Dclk3nCoXV41N6bFxvVJSt7CeICy_815Aw=='
Using Ory Session Token
An Ory Session Token is issued when the user authenticates through a client other than a web browser. To get the session payload,
send a request to the /sessions/whoami endpoint.
Native applications such as desktop applications, mobile applications, or terminal-based apps that do not run inside a browser should use session tokens instead of session cookies.
- Go
- TypeScript
- cURL
package frontend
import (
"context"
"fmt"
"os"
"github.com/ory/client-go"
)
type oryMiddleware struct {
ory *ory.APIClient
}
func init() {
cfg := client.NewConfiguration()
cfg.Servers = client.ServerConfigurations{
{URL: fmt.Sprintf("https://%s.projects.oryapis.com", os.Getenv("ORY_PROJECT_SLUG"))},
}
ory = client.NewAPIClient(cfg)
}
func CheckSession(ctx context.Context, sessionToken string) (session *client.Session, err error) {
session, _, err = ory.FrontendApi.ToSession(ctx).
XSessionToken(sessionToken).
Execute()
if err != nil {
// error revoking the session, for example due to expired token provided
return nil, err
}
return session, nil
}
import { Configuration, FrontendApi } from "@ory/client"
const frontend = new FrontendApi(
new Configuration({
basePath: `https://${process.env.ORY_PROJECT_SLUG}.projects.oryapis.com`,
}),
)
export async function checkSession(sessionId: string, token: string) {
return await frontend.toSession({
xSessionToken: token,
})
}
curl 'https://$PROJECT_SLUG.projects.oryapis.com/sessions/whoami' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer BRFbGMzTnBiMjVmZEcEdjM1J5YVc1bkRDSUFvME5VNVlaVeWJrUnZhSEF4YmxSV2VVRlhNMWwxVlVGenxXpsk2cLXV41N6bFxvVJSt7CeICy'
JSON Web Token (JWT) support
Sessions are by default not issued as JWTs for two main reasons:
- 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.
- Sessions can be updated and changed at any point in time, for example, when the user updates their profile. Such change can't be easily reflected in a JWT before it is refreshed.
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.
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. Read more in the Session to JWT 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
Ory Oathkeeper is an API Gateway capable of converting sessions to JWTs.