Configure OAuth timeouts
OAuth timeouts determine how long and how often OAuth clients have access to a server's resources. As a reminder:
-
Access tokens grant access to resources for a short period of time. After they expire, clients can request new access tokens.
-
Refresh tokens authorize clients to request access tokens for a period of time. After they expire, clients must re-authenticate (such as re-sign in) to acquire a new refresh token.
Companies should have a global policy for the OAuth timeouts defined on the Configuration screen. However, clients may — and in some cases must — override the settings on the Clients screen. Consider these use-cases.
These are the timeout properties:
- Access token lifetime (seconds)
- Access tokens grant access to resources for a short period of time. After they expire, clients can automatically request new access tokens. Set this to a short value, like 1 hour (3,600 seconds) to promote security.
- Refresh token lifetime (hours)
- (Session-timeout: how long a user can be signed in before automatically getting signed out.) Refresh tokens authorize clients to request access tokens for a period of time. After they expire, clients must re-authenticate (re-sign in) to acquire a new refresh token. Depending on the application, set this to a long value like 30 days (720 hours).
For unlimited refresh, use 0 (zero) to indicate an infinite life-time. Use unlimited refresh for applications accessing APIs, and use short values for users that should be forced to re-sign in periodically (such as every 30 days). See Unlimited access, below, for a discussion of this.
Note: Refresh tokens can be manually revoked by administrators on the Access and Refresh Tokens screen. Applications that use refresh tokens must store them securely. - Refresh token idle timeout (seconds)
- (Idle-timeout: how long a user can be idle before automatically getting signed out.) Refresh idle is how long the connection may be idle (inactive) before forcing the client to re-authorize (re-sign in). This setting must be longer than the Access token lifetime setting. See Idle timeout, below, for a discussion of setting this property. Important: While this setting can be applied globally to the instance, each client must specifically be configured to use this (or not) with the Expire refresh token after idle timeout property on the Clients screen.
- Authorization code lifetime (seconds):
- Authorization codes are one-time use-codes used during authorization. The OAuth server issues the code to the client, and the client must immediately return it to the OAuth server when requesting the first access token. This property specifies how long the server waits for the code before failing to authorize the client. Set this to a short value like 10 minutes (600 seconds).
Limited access
Use limited access to for the clients to have to re-authenticate periodically, Set the Refresh token lifetime to some reasonable period of time for the application. For example, you might grant mobile users the ability to remain signed-in for 30 days, or you might force them to re-sign in daily.
Unlimited access
Use unlimited access for applications accessing APIs on the resource server. Once the application has been authorized, it can then access the server indefinitely until the refresh token is manually revoked. Do this by setting the Refresh token lifetime to 0 (zero). The Access token lifetime should still be set to a short time to ensure the tokens get refreshed often, which promotes better security.
Idle timeout
Use idle timeout to force the client (usually a user) to revoke access and cause the client to have to re-authenticate when they have not access the resource server for some period of time. For example, a mobile application that has not accessed the server in the last 2 hours could have it's access revoked until the user re-signs in. When using this scenario, pick an idle-timeout that is longer than the access token timeout. Also, this option must explicitly be turned on for the clients with the Expire refresh token after idle timeout property on the Clients screen.
