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

Admin session extension API (faster_session_extend)

• Who is impacted by this change?

This improvement may impact users who are using the /admin/sessions/{id}/extend endpoint (extendSession SDK operation) to extend their users' sessions. The new implementation may result in faster response times and improved performance when extending sessions.

• Why was this change made?

The change was made to improve the performance and efficiency of the session extension process. By decoupling the session extension from the retrieval of the updated session information, we can reduce the processing time and resource usage for extending sessions, especially in scenarios with high traffic or large session data.

• How to adapt to this change?

If your application is using the updated session returned by the /admin/sessions/{id}/extend endpoint after the session extension, you will need to update your implementation to retrieve the updated session information separately, using the /admin/sessions/{id} endpoint (getSession SDK operation) after the session extension.

After you reviewed your usage of this API, follow the instructions below based on your deployment type to ensure that you are benefiting from the improved session extension process.

Ory Network

Go to Project settings → Advanced in the Ory Console and enable the "Faster session extension" feature flag to benefit from this improvement.

Self-hosted (OSS or OEL)

Starting with Ory Kratos v1.3.0, the faster session extension process is enabled by default. If you need to disable this feature for any reason, you can set the feature_flags.faster_session_extend configuration option to false in your Kratos configuration file.

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.

danger

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 workspaces
   ory list workspaces
   
   ## List all available projects
   ory list projects --workspace <workspace-id>
   
   ## Get config
   ory get identity-config --project <project-id> --workspace <workspace-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 <project-id> --workspace <workspace-id> --file identity-config.yaml