OAuth refresh tokens and flow explained

OAuth Refresh

On this page

What is Refresh Token in OAuth?

A Refresh Token is a central part of OAuth, and consequently, OpenID Connect. It is a kind of token that can be used to get additional access tokens. It is a sort of "token granting token" in that it can be sent to the OAuth server to obtain new ones.

Refresh Tokens vs Access Tokens

Refresh and access tokens work in tandem. Access tokens typically have a shorter life span while refresh tokens have a longer one, requiring less frequent re-authentication of the user. Refresh tokens are used to obtain a new access and refresh token when the current access token has expired. As mentioned, the purpose of the refresh token is to obtain new tokens whereas the purpose of the access token is to gain access.

How Refresh Tokens Work

Refresh tokens can be thought of like a password of sorts. When you access a web site and don't yet have a session, you login with some sort of credential or token, like a password. This "token" is exchanged for another -- a session token -- that you can use to repeatedly access resources at that web site without having to login again. In the same way, a refresh token can be used to obtain access tokens. This is important because a client application will often want to extend a user's access period without having to log them in again. Using a refresh token, the client can obtain a new access token without involving the user, thus improving User Experience (UX).

When to Use a Refresh Token

Refresh tokens are used in user-facing applications. They enable you to keep access tokens that are sent to APIs short lived, minutes rather than hours, as a security best practice. When the access token expires, the refresh token enables you to seamlessly get a new access token to continue the API session, without asking the user to re-authenticate.

Refresh Token Expiration

The lifetime of refresh tokens is configured in the identity server for each client application. There is no fixed time, but it typically represents the length of time before a user needs to re-authenticate. For high-worth data refresh tokens are usually set to a lower time.

Flows that Include a Refresh Token

Not all flows will result in a refresh token being issued. The following table summarizes which ones do and do not:

FlowIncludes a Refresh Token
Code flowYes
Implicit flowNo
Assisted token flowNo, but not needed
Client credential flowNo
Resource owner password credential flowYes
Hybrid flowYes
Device flowYes
JWT Assertion flowYes

OAuth Refresh Flow Overview

Token Endpoint

Refresh Flow Diagram
  1. The client sends the refresh token along with credentials to the token endpoint
  2. The server responds with new a new access token and a new refresh token

Unlike some of the other OAuth flows, this one is a very simple request/response. The client application (or Relying Party, RP) makes a request to the OAuth server, including the refresh token in the payload. The response includes an access token and possibly a new refresh token.

Client Authentication

The client authenticates in the Token part of the flow. Client authentication can be done in many ways, the most common being client secret. The following authentication mechanisms are supported in Curity:

  • No authentication (public client)
  • Secret in post body
  • Secret using basic Authentication
  • Client Assertion JWT
  • Mutual TLS (mTLS) client certificate
  • Asymmetric Key
  • Symmetric Key
  • Credential Manager
  • JWKS URI

Re-using refresh tokens

The refresh_token in the response is not the same as the one that was sent. This is Curity's default behavior -- it creates a new refresh token with each redemption of an existing refresh token. This means that the client will have to store the refresh token from each response and use that in the next request. This is an extra security measure that is in place but can be relaxed. To reuse the same refresh token, in the admin UI, go to the OAuth profile's General page. There you will find a setting labeled Reuse Refresh Tokens.

Token re-use

It's possible to configure the server to re-use the refresh token. In that case the same refresh token is used on every refresh. This is considered less secure.

Rolling Refresh Token

Rolling refresh Tokens is a feature that can be enabled in the Curity Identity Server. This setting will use the Refresh Token Time to Live when a new refresh token is issued. It will do so until the Refresh Token Maximum Rolling Lifetime is reached. This allows the server to issue new refresh tokens but only for a set time period.

The Token Endpoint Request

Request Parameters

  • Method: POST
  • Content-Type: application/x-www-form-urlencoded
  • Response Type: json
ParameterValueMandatoryDescription
client_idThe Client IDyesThe ID of the requesting client
client_secretThe client secretyes*The secret of the client. *Mandatory if client authentication is of type secret, and the authentication is not done using basic authentication
grant_typerefresh_tokenyesTells the token endpoint perform refresh.
refresh_tokenThe refresh tokenyesThe current refresh token.
scopeSpace separated string of scopesnoCan be a subset of the original scopes requested.

Response

  • Response Type: application/json
ParameterValueMandatoryDescription
access_tokenA newly issued access tokenyesThe resulting access token from the refresh
refresh_tokenA newly issued refresh tokenyesThe next refresh token to use
expires_inExpiration in secondsyesThe time to live of the access token in seconds
scopeSpace separated stringnoIf not present the requested scopes where issued. If present the issued scopes may differ from the previous scopes.
token_typeBearer or other token typeyesDescribes how the token can be used. Most commonly Bearer token usage.

Conclusion

Access tokens and refresh tokens are used in pairs. When a user is successfully authenticated in some way an access and refresh token are issued. In order to limit the exposure the access token is typically short lived. How short depends on the use case. To provide a better user experience and avoid constant user re-authentication the refresh token can be used to obtain a new access token (and a new refresh token). This is possible because refresh tokens are typically configured to have a longer life span than an access token. For added protection the refresh token should only be allowed to be used one time.

Join our Newsletter

Get the latest on identity management, API Security and authentication straight to your inbox.

Start Free Trial

Try the Curity Identity Server for Free. Get up and running in 10 minutes.

Start Free Trial