Refresh and extend sessions

For certain use cases, sessions need to be refreshed on user activity or administrative action.

When you refresh a session, its expires property is set to a value that is the time when the refresh is triggered plus the amount of time defined by the value of /session/lifespan.

Forcing session refresh

You can force users to refresh session by prompting them to re-authenticate by interacting with the /self-service/login/browser or /self-service/login/api APIs and setting the refresh parameter to true.

When the user re-authenticates, the authenticated_at timestamp of the session is set to the time when user re-authenticated.

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

When forcing users to refresh sessions, you can also force them to refresh their second authentication factor. To do that, set refresh=true and aal=aal2:

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

Refreshing sessions as administrator

Administrators can refresh the session of a specific user using the extend session API from the SDK.

Go

extend-session.go

package session

import (
	"context"
	"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 RefreshSession(ctx context.Context, sessionId string) (session *client.Session, err error) {
	session, _, err = ory.IdentityApi.ExtendSession(ContextWithToken(ctx), sessionId).
		Execute()

	if err != nil {
		return nil, err
	}

	return session, err
}

TypeScript

extend-session-native.ts

import { Configuration, IdentityApi } from "@ory/client"

const identity = new IdentityApi(
  new Configuration({
    basePath: `https://${process.env.ORY_PROJECT_SLUG}.projects.oryapis.com`,
    accessToken: `${process.env.ORY_ACCESS_TOKEN}`,
  }),
)

export async function refreshSession(sessionId: string) {
  return await identity.extendSession({
    id: sessionId,
  })
}

tip

To get the Session ID, call the /sessions/whoami endpoint or toSession SDK method.

Refresh threshold

You can limit the time in which the session can be refreshed by adjusting the earliest_possible_extend configuration.

For example, if you set earliest_possible_extend to 24h, sessions can't be refreshed sooner than 24 hours before they expire.

If you need high flexibility when extending sessions, you can set earliest_possible_extend to lifespan, which allows sessions to be refreshed during their entire lifespan, even right after they are created.

warning

If you set earliest_possible_extend to lifespan, all sessions will constantly be refreshed!

Ory CLI

1. Download the Ory Identities config from your project and save it to a file:

   ## List all available projects
   ory list projects
   
   ## Get config
   ory get identity-config {project-id} --format yaml > identity-config.yaml

2. Update the configuration value for the property to the desired value. (Use hour (h), minute (m), second (s) to define interval, for example: 1h1m10s, 10s, 1h)

   config.yml

   session:
   cookie:
      domain: {project.slug}.projects.oryapis.com
      name: ory_session_{name}
      path: /
      persistent: false
      same_site: Lax
   lifespan: 720h0m0s
   earliest_possible_extend: 24h0m0s

3. Update the Ory Identities configuration using the file you worked with:

   ory update identity-config {project-id} --file identity-config.yaml