OAuth Refresh

OAuth Refresh

develop

The OAuth Refresh Flow in Detail

Refresh Flow Overview

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 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).

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

Overview

Token Endpoint

Refresh Flow

  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

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.

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.

Was this page helpful?