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#

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"
}
]
}
}
Last updated on by Vincent