Controlling SAML 2.0 Session Duration

This article describes how to control the duration of authenticated sessions for users who authenticate to Arpio with a SAML 2.0 identity provider

When Arpio successfully authenticates a user, it establishes an authenticated session with a defined expiration time. The session information, including the expiration time, is stored in a web browser cookie on the user's computer. After the session expires, Arpio will require the user to re-authenticate as soon as a protected resource is accessed.

The length of time that a user's authenticated session is valid is called the session duration. Arpio's default session duration is 7 days, but SAML 2.0 identity providers can set a different duration in the response they send to Arpio when a user authenticates.

<AuthnStatement SessionNotOnOrAfter="...">

The SAML 2.0 core specification describes the SessionNotOnOrAfter attribute, which an identity provider may set in its response to establish a time after which the user's session is no longer valid. When SessionNotOnOrAfter is set, Arpio uses the attribute's value as the session expiration time.

An example that shows SessionNotOnOrAfter establishing a session that expires 1 hour after the instant it was issued:

<saml:AuthnStatement AuthnInstant="2022-05-12T13:07:28Z" SessionNotOnOrAfter="2022-05-12T14:07:28Z">
    <saml:AuthnContext>
        <saml:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:Password</saml:AuthnContextClassRef>
    </saml:AuthnContext>
</saml:AuthnStatement>

Although SessionNotOnOrAfter is part of the SAML 2.0 core specification, many identity providers do not send this attribute in their responses. Some can be configured to send it, but others simply don't support it. If your identity provider doesn't support this attribute, or if the steps to enable it are cumbersome, you can use the DurationSeconds custom attribute instead, which is generally easier to configure.

DurationSeconds <Attribute>

Name Format:   urn:oasis:names:tc:SAML:2.0:attrname-format:basic
Value Format:  xs:string

You can configure your identity provider to send the DurationSeconds attribute in its response assertions to control the duration of the authenticated session. Since this is a custom attribute that Arpio looks for, and it isn't part of the SAML 2.0 specification, you must configure your identity provider to send it with an appropriate value if you want to use it. Most identity providers make it easy to set custom attributes per-user or per-group. Consult your identity provider's documentation for details.

The attribute's value is text containing a non-negative integer number of seconds that the session will be valid for.

If the attribute value cannot be interpreted as an integer number, the attribute is ignored and will not control the session duration.

This example shows the DurationSeconds attribute being used to set a session duration of 3600 seconds (1 hour):

<saml:Assertion ID="some-assertion-id" IssueInstant="2022-05-12T13:07:28Z" Version="2.0">
    <saml:Issuer Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity">...</saml:Issuer>
    <saml:AttributeStatement>
        <saml:Attribute Name="DurationSeconds" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
            <saml:AttributeValue xsi:type="xs:string">3600</saml:AttributeValue>
        </saml:Attribute>
    </saml:AttributeStatement>
</saml:Assertion>

In the rare case that the SAML response contains multiple attributes named DurationSeconds, Arpio uses the one with the smallest numeric value (shortest duration).

Control Priority

When a SAML 2.0 response does not include a value for either SessionNotOnOrAfter or DurationSeconds, Arpio uses a session duration of 7 days.

When the response includes a valid value for one of SessionNotOnOrAfter or DurationSeconds, but not both, Arpio uses the provided value to set the session duration.

When the response includes valid values for both SessionNotOnOrAfter and DurationSeconds, Arpio uses the value for DurationSeconds and ignores SessionNotOnOrAfter. It's typically easier to configure an identity provider to send a custom attribute like DurationSeconds than to change how it sends SessionNotOnOrAfter, so this rule makes administration more convenient.