Guide

Modify token lifetimes

Suggest Edits

Any time you’re issued an access token or a refresh token, those tokens come with a built-in expiration time: by default access tokens are valid for one hour (3600 seconds) and refresh tokens are valid for 90 days (7776000 seconds). What does that mean? Well, suppose you get an access token at 1:00 PM and you don’t refresh that token. At 2:30 PM (that is, more than hour after you received your token) you call the userinfo endpoint to retrieve some information. That API call is going to be denied. Why? That’s right: because your access token has expired. Nothing lasts forever, including access tokens and refresh tokens.

So do the default values of 1 hour for access tokens and 90 days for refresh tokens work for your organization? Needless to say, that’s something only you can answer. However, if those default values don’t work there's good news: you can change the time-to-live (TL) values of your access tokens and/or your refresh tokens. Just keep the following ground rules in mind:

  • Access tokens lifetimes can range from 1 minute (60 seconds) to one hour (3600 seconds). And yes, the default lifetime for access tokens is also the maximum lifetime for an access token.

  • Refresh token lifetimes can range from 1 minute (60 seconds) to one year (31557600 seconds).

So let’s assume that the default values don’t work for you: you’d prefer to limit the lifetime of access tokens to 30 minutes (1800 seconds) and the lifetime of refresh tokens to 30 days (2592000 seconds). That’s great, but how do you go about doing that? Let’s see if we can figure that out.

To begin with, token lifetimes are managed by using token policies; that’s why each of your OpenID Connect (OIDC) login clients must be associated with a token policy. Consequently, step 1 in this process is to determine the token policy (or policies) you need to modify.

📘

Does this mean that different users could have different token lifetimes, depending on which login client they use? Yes, they could; it just depends on whether those OIDC clients use different token policies. (The same token policy can be assigned to more than one login client.)

Without going into s lot of detail, you can use the /config/clients/{oidcClientId} endpoint to return the property values of a given OIDC client. Those property values will include the ID of the associated token policy:

{
   "id": "a123ef65-83dc-4094-a09a-76e1bec424e7",
   "name": "New Public Client",
   "redirectURIs": [
       "http://127.0.0.1",
       "https://localhost:3001/redirect_uri",
       "https://oidc-playground.akamai.com/redirect_uri",
       "https://openidconnect.net/callback",
       "https://documentation.akamai.com"
   ],
   "loginPolicy": "ad2cad34-e06f-463e-a43f-b5c8af0ee965",
    "tokenPolicy": "a7f902b3-6e63-4f60-87a6-6cf5a1bc8ff4",
    "type": "public",
   "_links": {
       "self": {
           "href": "/config/e0a70b4f-1eef-4856-bcdb-f050fee66aae/clients/a123ef65-83dc-4094-a09a-76e1bec424e7"
       },
       "application_client": {
           "href": "/config/79y4mqf2rt3bxs378kw5479xdu/clients/u74hp2xa4u75dq9s6wv8yyb28wkkux7m"
       }
   }
}

📘

You say you tried to call one of the OpenID Connect Configuration APIs, but you got an “Authentication required” or an “Access forbidden” error message? Then you need to read the article [Get an administrative access token for information on obtaining a configuration token for use when calling the OIDC Configuration APIs.

After you have the token policy ID, you can then use the GET method and the /config/clients/{tokenPolicyId} endpoint to return the current properties of the policy:

{
   "id": "a7f902b3-6e63-4f60-87a6-6cf5a1bc8ff4",
   "accessTokenLifetime": 3600,
   "allowedScopes": [
       "openid",
       "profile",
       "address"
   ],
   "refreshTokenLifetime": 7776000,
   "title": "GREG_DEMO Token Policy",
   "_links": {
       "self": {
           "href": "/config/e0a70b4f-1eef-4856-bcdb-f050fee66aae/tokenPolicies/a7f902b3-6e63-4f60-87a6-6cf5a1bc8ff4"
      }
   }
}

That’s a good question: do we really need to know all the properties of the token policy just to change a token lifetime? Believe it or not, yes, we do. In a moment, we’ll use the PUT method and the /config/clients/{tokenPolicyId} endpoint to change the values of the accessTokenLifetime and the refreshTokenLifetime properties. When we do that, however, we have to include all the other properties and property values (like title and allowedScopes) in our API call. Why? That's because the PUT method removes all the existing properties in a token policy and replaces them with all the properties and property values specified in the body parameter of your API call. In turn, that means that only the properties and property values specified in the API call will be included in the updated policy. Did you forget to include the allowedScopes property in your PUT call? If you did, then the allowedScopes property will be removed from the token policy. That’s just the way it works.

Because of that, a good approach is to use the GET method to return all the current property values, copy those values, then paste them into the body parameter of your API call. After that, you can then modify the properties that you want to change. In our case, we want to modify the two token lifetime properties:

{
   "id": "a7f902b3-6e63-4f60-87a6-6cf5a1bc8ff4",
    "accessTokenLifetime": 1800,
    "allowedScopes": [
       "openid",
       "profile",
       "address"
   ],
    "refreshTokenLifetime": 2592000,
    "title": "GREG_DEMO Token Policy",
}

Here’s what a full API call might look like for those of you using Curl:

curl -X PUT \
  'https://v1.api.us.janrain.com/e0a70b4f-1eef-4856-bcdb-f050fee66aae/config/tokenPolicies/a7f902b3-6e63-4f60-87a6-6cf5a1bc8ff4' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer miH-RGmpNL0aduvcBaaTp9fuTv7DiqAA0LxQODT8ihR_I7DY1bNSNfRefkZDCCcA' \
  -d '{
    "id": "a7f902b3-6e63-4f60-87a6-6cf5a1bc8ff4",
    "accessTokenLifetime": 1800,
    "allowedScopes": [
        "openid",
        "profile",
        "address"
    ],
    "refreshTokenLifetime": 2592000 ,
    "title": "GREG_DEMO Token Policy"
}'

After making a successful API call, your token lifetimes will be updated, and all newly-issued tokens will use the new time-to-live values.

📘

Does that mean that tokens that have already been issued will keep their old lifetime values? Yes, it does: these changes only affect tokens issued after the token policy has been changed. If you wanted to enforce these policies on everyone, including users who were issued access and refresh tokens before the policy was changed, you’d have to revoke all the existing tokens and force all your active users to reauthenticate.

Updated about 1 year ago