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.
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 other tokens, shorter-lived ones called 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).
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|
|Assisted token flow||No, but not needed|
|Client credential flow||No|
|Resource owner password credential flow||Yes|
|JWT Assertion flow||Yes|
OAuth Refresh Flow Overview
- 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.
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
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.
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.
The Token Endpoint Request
- Response Type:
|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||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 Type:
|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||yes||Describes how the token can be used. Most commonly Bearer token usage.|