Skip to main content

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.

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

danger

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

  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