Version: v0.5

Configuring And Checking for Login Sessions

A login session is created when a user signs in. The session is stored as a cookie or as a token, depending on the interaction type.

Login Session Configuration#

A session is valid for the session lifespan you specify in the ORY Kratos config:

session:
  lifespan: 720h # 30 days

Per default the session cookie has the max-age parameter set to the specified session lifespan. You may disable this behavior by setting:

session:
  cookie:
    persistent: false

note

The cookie max-age parameter behaves as follows:

The browser interprets the cookie to be removed when the session ends if max-age is not set as part of the Set-Cookie header. A session ends if the browser is terminated due to a reboot or when shutting down the browser.
The browser keeps the cookie until max-age is reached otherwise.

Once the lifespan is reached, the user needs to sign in again.

Checking for Login Sessions#

Browser Client#

The easiest way to check if a user is signed in is to call the http(s)://<kratos-public/sessions/whoami endpoint which will return either a 401 Unauthorized or HTTP 200 OK with the session.

note

Make sure to include the ORY Kratos Session Cookie when calling this endpoint. If you are calling this endpoint from a proxy or middleware, make sure to forward the cookies sent to the proxy/middleware. If you are calling this endpoint as an AJAX call, make sure to include credentials and configure CORS properly.

A typical session payload will look like this:

{
  "id": "8f660ce3-69ec-4aeb-9fda-f9230dc3243f",
  "active": true,
  "expires_at": "2020-08-25T13:42:15.7411522Z",
  "authenticated_at": "2020-08-24T13:42:15.7411522Z",
  "issued_at": "2020-08-24T13:42:15.7412042Z",
  "identity": {
    "id": "bf32596a-f853-47c4-91e6-a3f41cf4949d",
    "schema_id": "default",
    "schema_url": "http://127.0.0.1:4433/schemas/default",
    "traits": {
      "email": "api@user.org",
      "name": {
        "last": "User",
        "first": "API"
      }
    },
    "verifiable_addresses": [
      {
        "id": "f877db6c-7dfb-45e3-bbeb-ac8349348128",
        "value": "api@user.org",
        "verified": false,
        "via": "email",
        "verified_at": null,
        "expires_at": "2020-08-24T14:35:59.125873Z"
      }
    ],
    "recovery_addresses": [
      {
        "id": "065a908c-82be-4110-bf67-9910f36242b7",
        "value": "api@user.org",
        "via": "email"
      }
    ]
  }
}

Code Examples#

ExpressJS

import { PublicApi } from '@ory/kratos-client'

const publicEndpoint = new PublicApi(config.kratos.public)
const protect = (req: Request, res: Response, next: NextFunction) => {
  req.headers['host'] = config.kratos.public.split('/')[2]
  publicEndpoint
    .whoami(req)
    .then(({ body, response }) => {
      req.user = { session: body }
      next()
    })
    .catch(() => {
      // Redirect to login if not logged in
      res.redirect('/auth/login')
    })

// const app = express()
// ...

app.get('/', protect, dashboard)

API Client#

API clients receive and use ORY Kratos Session Tokens which can be checked by calling the /sessions/whoami endpoint and including the ORY Kratos Session Token as a bearer token in the HTTP Authorization Header:

$ sessionToken=oFZzgLpsacUpUy2cvQPtrGa2046WcXCR
$ curl -s -X POST -H  "Accept: application/json" \
    -H "Authorization: Bearer $sessionToken" \
    # OR: \
    # -H "X-Session-Token: $sessionToken" \
    http://127.0.0.1:4433/sessions/whoami | jq

{
  "id": "8f660ce3-69ec-4aeb-9fda-f9230dc3243f",
  "active": true,
  "expires_at": "2020-08-25T13:42:15.7411522Z",
  "authenticated_at": "2020-08-24T13:42:15.7411522Z",
  "issued_at": "2020-08-24T13:42:15.7412042Z",
  "identity": {
    "id": "bf32596a-f853-47c4-91e6-a3f41cf4949d",
    "schema_id": "default",
    "schema_url": "http://127.0.0.1:4433/schemas/default",
    "traits": {
      "email": "api@user.org",
      "name": {
        "last": "User",
        "first": "API"
      }
    },
    "verifiable_addresses": [
      {
        "id": "f877db6c-7dfb-45e3-bbeb-ac8349348128",
        "value": "api@user.org",
        "verified": false,
        "via": "email",
        "verified_at": null,
        "expires_at": "2020-08-24T14:35:59.125873Z"
      }
    ],
    "recovery_addresses": [
      {
        "id": "065a908c-82be-4110-bf67-9910f36242b7",
        "value": "api@user.org",
        "via": "email"
      }
    ]
  }
}