OIDC-conformant refresh tokens

Adoption Guide

This document is part of the adoption guide for OIDC-conformant authentication. If you haven't already, we strongly suggest reading the introduction before reading this document.

There are some changes to how refresh tokens are used in the OIDC-conformant authentication pipeline:

  • Using the implicit grant for authentication will no longer return refresh tokens. Use silent authentication (i.e. prompt=none) instead.
  • Refresh tokens should only be used by confidential clients. However, they can also be used by Native (public) clients to obtain refresh tokens for mobile apps.
  • The /delegation endpoint is considered deprecated. To obtain new tokens from a refresh token, the /oauth/token endpoint should be used instead:
POST /delegation
Content-Type: 'application/json'
{
  "grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer",
  "client_id": "...",
  "refresh_token": "...",
  "scope": "openid profile"
}
POST /oauth/token
Content-Type: application/json
{
  "grant_type": "refresh_token",
  "refresh_token": "...",
  "client_id": "...",
  "client_secret": "...",
  "scope": "openid profile",
  "audience": "https://api.example.com"
}
  • The audience and client_secret parameters are optional. The client_secret is not needed when requesting a refresh_token for a mobile app.

Please note that refresh tokens must be kept confidential in transit and storage, and they should be shared only among the authorization server and the client to whom the refresh tokens were issued.

Further reading