Skip to main content

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.

note

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"
}
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:

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.

note

Browser-based applications including single-page applications (SPAs) and server-side rendered apps should use session cookies instead of session tokens.

Checking current session
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>
  )
}

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.

note

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.

Checking current session
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
}

JSON Web Token (JWT) support​

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