Skip to main content

Overview

When an identity or end-user authenticates, for example by signing in with their username and password, they receive an Ory Session.

The session is a proof that the user is authenticated and allows to interact with the system without the need to authenticate again for every request.

Sessions can be issued in two formats:

  • Session cookie - when the system detects that the interaction is done through a web browser, a cookie which represents the user's Session is stored in the browser.
  • Session token - when the system detects a client other than a web browser, for example a native mobile app, a Session token is issued to the client.
note

For security reasons, you can't break the isolation between cookies and session tokens.

The Ory Session​

This is an sample Ory Session:

{
  "id": "1338410d-c473-4503-a96a-53efa06e2531",
  "active": true,
  "expires_at": "2021-10-15T15:58:57.683338Z",
  "authenticated_at": "2021-10-14T15:58:57.683338Z",
  "authenticator_assurance_level": "aal2",
  "authentication_methods": [
    {
      "method": "password",
      "completed_at": "2021-10-14T15:55:19.03621Z"
    },
    {
      "method": "lookup_secret",
      "completed_at": "2021-10-14T15:56:21.257867Z"
    },
    {
      "method": "lookup_secret",
      "completed_at": "2021-10-14T15:58:57.683337Z"
    },
    {
      "method": "lookup_secret",
      "completed_at": "2021-10-14T16:03:14.833192Z"
    }
  ],
  "issued_at": "2021-10-14T15:58:57.683338Z",
  "identity": {
    "id": "9496bbd5-f426-473f-b087-c7df853f274a",
    "schema_id": "default",
    "schema_url": "https://<your-project-slug>.projects.oryapis.com/schemas/default",
    "state": "active",
    "state_changed_at": "2021-10-14T17:55:17.885497+02:00",
    "traits": {
      "website": "https://www.ory.sh/",
      "email": "0.wz4yhr0zwyd@ory.sh"
    },
    "verifiable_addresses": [
      {
        "id": "4de14270-ca13-4efb-ac3f-8f03b1f649d8",
        "value": "0.wz4yhr0zwyd@ory.sh",
        "verified": false,
        "via": "email",
        "status": "sent",
        "created_at": "2021-10-14T17:55:17.886639+02:00",
        "updated_at": "2021-10-14T18:03:14.839009+02:00"
      }
    ],
    "recovery_addresses": [
      {
        "id": "fdab5a5f-5efc-4202-93b5-fd3ee632420b",
        "value": "0.wz4yhr0zwyd@ory.sh",
        "via": "email",
        "created_at": "2021-10-14T17:55:17.886831+02:00",
        "updated_at": "2021-10-14T18:03:14.839105+02:00"
      }
    ],
    "created_at": "2021-10-14T17:55:17.886237+02:00",
    "updated_at": "2021-10-14T17:55:17.886237+02:00"
  }
}
PropertyDescription
activeWhen set to true, the Ory Session is active and can be used to authenticate requests.
expires_atDefines the time when the Session expires. This value depends on the session lifespan configuration.
authenticated_atIndicates the time of the most recent successful authentication. This value is updated when:

The Session Cookie is issued when the user signs in through a web browser. To get the session payload, send a request to the /sessions/whoami endpoint:

curl 'https://{your-project-slug-here}.projects.oryapis.com/sessions/whoami' \
  -H 'Accept: application/json \
  -H 'Cookie: ory_kratos_session=MTYzNDIyNzEzN3xEdi1CQkFFQ180SUFBUkFCRUFBQVJfLUNBQUVHYzNSeWFXNW5EQThBRFhObGMzTnBiMjVmZEc5clpXNEdjM1J5YVc1bkRDSUFJRTFDYWtvME5VNVlaVWxvYVZWeWJrUnZhSEF4YmxSV2VVRlhNMWwxVlVGenxXpsk2cL21Dclk3nCoXV41N6bFxvVJSt7CeICy_815Aw=='

Session Token​

A 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.

You must pass the token in one of two ways:

  • In the Authorization HTTP header:

    curl 'https://{your-project-slug-here}.projects.oryapis.com/sessions/whoami' \
      -H 'Accept: application/json   -H 'Authorization: Bearer BRFbGMzTnBiMjVmZEcEdjM1J5YVc1bkRDSUFvME5VNVlaVeWJrUnZhSEF4YmxSV2VVRlhNMWwxVlVGenxXpsk2cLXV41N6bFxvVJSt7CeICy'

  • In the X-Session-Token HTTP header:

    curl 'https://{your-project-slug-here}.projects.oryapis.com/sessions/whoami' \
      -H 'Accept: application/json   -H 'X-Session-Token: BRFbGMzTnBiMjVmZEcEdjM1J5YVc1bkRDSUFvME5VNVlaVeWJrUnZhSEF4YmxSV2VVRlhNMWwxVlVGenxXpsk2cLXV41N6bFxvVJSt7CeICy'

Privileged Sessions​

To perform some profile changes, such as updating the email address, password, or adding/removing 2FA, the user must have a privileged session.

tip

This flow is similar to GitHub's sudo mode.

The session is considered privileged when its authenticated_at isn't older than the privileged_session_max_age value defined in the configuration.

This is how you update the privileged_session_max_age to 15m:

ory patch identity-config <your-project-id> \\
  --replace '/selfservice/flows/settings/privileged_session_max_age/lifespan="15m"' # 15 minutes

With this configuration in place, the user can perform the actions that require a privileged session up to 15 minutes after signing in. When this time passes, the user must re-authenticate to access these options.

Watch this video to see the flow in action:

Refreshing Sessions​

You can prompt the user to re-authenticate by interacting with the /self-service/login/browser or /self-service/login/api API and setting the refresh parameter to true. Once the user has re-authenticated, the authenticated_at timestamp of the Ory Session will be set to the current time.

https://{your-project-slug-here}.projects.oryapis.com/self-service/login/browser?refresh=true

If enabled, you can also refresh the second factor by setting both refresh and aal:

https://{your-project-slug-here}.projects.oryapis.com/self-service/login/browser?refresh=true&aal=aal2

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:

  1. Ory Sessions can end at any point in time, indicating that the user is no longer signed in. With JWTs it would not easily be possible to determine whether a session is still valid before the token expires.
  2. Ory Sessions can be updated and changed at any point in time (for example when the user updates their profile), which can't be easily reflected in a JWT before it is refreshed.

We are taking many steps to reduce the latency of toSession / /sessions/whoami endpoints across the globe for Ory Cloud, so that latency is not an issue for users.

However, 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 Ory Sessions to JWTs on your entry point. There, you could add caching to further reduce the amount of API calls made.

tip

Ory Oathkeeper is an API Gateway capable of converting Ory Sessions to JWTs.