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:
| Flow | Includes a Refresh Token |
|---|---|
| Code flow | Yes |
| Implicit flow | No |
| Assisted token flow | No, but not needed |
| Client credential flow | No |
| Resource owner password credential flow | Yes |
| Hybrid flow | Yes |
| Device flow | Yes |
| JWT Assertion flow | Yes |
OAuth Refresh Flow Overview
Token Endpoint
- The client sends the refresh token along with credentials to the token endpoint
- 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 as part of the token request. There are many ways for a client to authenticate, the most common being client secret. The Curity Identity Server supports the following authentication mechanisms for clients:
- 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
| Parameter | Value | Mandatory | Description |
|---|---|---|---|
| client_id | The Client ID | yes | The ID of the requesting client |
| client_secret | The client secret | yes* | The secret of the client. *Mandatory if client authentication is of type secret, and the authentication is not done using basic authentication |
| grant_type | refresh_token | yes | Tells the token endpoint perform refresh. |
| refresh_token | The refresh token | yes | The current refresh token. |
| scope | Space separated string of scopes | no | Can be a subset of the original scopes requested. |
Response
- Response Type:
application/json
| Parameter | Value | Mandatory | Description |
|---|---|---|---|
| access_token | A newly issued access token | yes | The resulting access token from the refresh |
| refresh_token | A newly issued refresh token | yes | The next refresh token to use |
| expires_in | Expiration in seconds | yes | The time to live of the access token in seconds |
| scope | Space separated string | no | If not present the requested scopes where issued. If present the issued scopes may differ from the previous scopes. |
| token_type | Bearer or other token type | yes | Describes 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.
Jacob Ideskog
Identity Specialist and CTO at Curity
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
