Sessions with Actions

Using Sessions with Actions allows you to configure post-authentication risk detection and response capabilities to protect your applications and users against session hijacking. You can also dynamically customize the session lifetime limits.

To facilitate this, post-login Actions feature two key objects:

• event.session: Provides relevant information including unique id, created_at, expires_at, idle_expires_at, updated_at dates, clients, authentication_at, and device information, such as ASN, IP, and User_agent. 

• api.session: Allows you to manage existing sessions by revoking sessions or changing expiry dates.

The event.session and api.session objects both support interactive web-based flows, including authorization code flow, implicit flow, device code flow, as well as SAML and WS-Fed.

You can use the event.session object to review timestamps of the latest interactions and evaluate risks associated with the current transactions. You can also combine the event.session object with other event objects, such as event.authentication or event.request.

You can then use the api.session object to either reset the existing session expiry dates or revoke the session. 

To learn more about these objects, review:

• Event object: Learn about the session Event object and properties.

• API object: Learn about the session API object and methods.

The post-login api.session.revoke(reason, options) method allows you to react to risks associated with a transaction. This method includes an option to allow you to preserve the refresh tokens bound to the revoked transaction.

In addition to revoking the session, the method will also initiate a session-revoked OIDC Back-Channel Logout Initiator to log out users from all applications bound to the current session and log a session_revoked event in the tenant logs.

You can use this method to:

• Invalidate the current session transaction in Auth0 

• Deny the current transaction

• Revoke all refresh tokens associated with the existing session with a matching session_id value.

  • This is a customizable option; you can choose to preserve the refresh tokens rather than revoke them. This operation runs asynchronously and eventually becomes consistent.

The revoke operation adds the following log event in your tenant logs:

A session_revoked event code indicating a revoked session with its associated session_id attribute. 

You can modify session expiry dates with the following post-login methods:

• api.session.setExpiresAt(absolute) allows you to define a new absolute (Require log in after) session expiration date for a specified session.

• api.session.setIdleExpiresAt(idle) allows you to set a new inactivity timeout date for a specified session.

You can use these methods to dynamically customize the session lifetime and inactivity policies based on:

• A user’s organization

• A user’s Auth0 connection

• A specific user’s group membership or profile

• Risk assessment 

• Any other dynamic criteria available during the execution of the Action

Sessions issued before the release of the post-login API methods api.session.setExpiresAt(absolute) and api.session.setIdleExpiresAt(idle) will not contain the following event.session property: last_interacted_at.

Sessions issued before the release of the post-login API method api.session.revoke(reason, options) will not contain the following event.session.device properties:

• initial_ip

• initial_asn

• initial_user_agent

For security reasons, inactivity and absolute timeouts cannot be set above the session settings defined in the session lifetime limits for the tenant. If you attempt to set a date above the lifetime limits, the API methods will update up to the lifetime limits and log a warning event (w) in the tenant logs.

You can use Actions to configure risk detections and revoke risky sessions and their associated refresh tokens with the post-login api.session.revoke(reason, options) method and the event.session object.

You can use the post-login object properties, event.session.device.initial_asn and event.request.asn to bind session transactions to a specific autonomous system number (ASN) network for their duration and require a re-authentication if the ASN network changes. 

exports.onExecutePostLogin = async (event, api) => {
  const sessionInitialAsn = event.session?.device?.initial_asn;
  const sessionCurrentAsn = event.request.asn;

  // if there is a session and the ASN changes
  if (
    sessionInitialAsn &&
    sessionCurrentAsn &&
    sessionInitialAsn != sessionCurrentAsn
  ) {
    api.session.revoke( "Invalid network change. Login again from a trusted network" )
  }
};

In this example, a check occurs at the start of the Action to verify that the event.session.device.initial_asn and event.request.asn properties remain within the same ASN network during the transaction. If this check fails, the Action calls  api.session.revoke() to: 

• Invalidate the session

• Deny the current transaction

• Revoke all its associated refresh tokens

• Prompt for re-authentication

You can use the post-login object properties event.session.device.initial_ip and event.request.ip to ensure a session transaction stays with the same IP address for its duration. In this scenario, any IP change is considered a risk, and the user will be prompted to re-authenticate.

exports.onExecutePostLogin = async (event, api) => {
  const sessionInitialIp = event.session?.device?.initial_ip;
  const sessionCurrentIp = event.request.ip;

  // if there is a session and the IP changes
  if (
    sessionInitialIp &&
    sessionCurrentIp &&
    sessionInitialIp != sessionCurrentIp
  ) {
    api.session.revoke("Invalid IP change")
  }
};

In this example, a check occurs at the start of the Action to verify that the event.session.device.initial_ip and event.request.ip properties remain with the same IP address during the transaction. If the check fails, the Action then calls  api.session.revoke() to: 

• Invalidate the session

• Deny the current transaction

• Revoke all its associated refresh tokens

• Prompt for re-authentication

You can use Actions to customize session idle and absolute expiration dates. Specifically, you can configure the expiry dates for a particular session transaction using the post-login api.session.setExpiresAt(absolute) and api.session.setIdleExpiresAt(idle) methods and the event.session object.

You can use the following post-login object properties, to define a lifetime for the connection used to authenticate a user.  

• event.session.created_at

• event.session.expires_at

And using the Auth0 Management API to create a connection metadata , event.connection.metadata.session_timeout define a specific connection timeout.

exports.onExecutePostLogin = async (event, api) => {
  const created = Date.parse(event.session?.created_at ?? "");

  // desired session lifetime for this connection in milliseconds, configured as connection metadata
  const connection_lifetime = event.connection?.metadata?.session_timeout;

  // if there is a session lifetime defined for the connection, set it
  if (event.session?.id && connection_lifetime) {
    api.session.setExpiresAt(created + Number(connection_lifetime));
  }
};

In this example, a check occurs at the start of the Action to verify that there is a  session_timeout defined in the current connection. In that case, the Action sets the session expiration to be equal to when the session was created plus the connection_lifetime.

You can define a current_time variable and using a new Organization metadata called idle_session_timeout set the idle timeout desired for an organization.

exports.onExecutePostLogin = async (event, api) => {
  // The Organization metadata is configured with a shorter idle timeout for sessions (in milliseconds)
  const idle_organization_lifetime =
    event.organization?.metadata?.idle_session_timeout;

  // If the organization has an specific idle timeout defined, set the timeout
  if (event.session?.id && idle_organization_lifetime) {
    const current_time = new Date().getTime();

    api.session.setIdleExpiresAt(
      current_time + Number(idle_organization_lifetime),
    );
  }
};

In this example, if there is a specific idle timeout defined for the Organization, the Action sets the session inactivity timeout to be equal to the current_time plus the idle_organization_lifetime .