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 two main 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 can only be used by confidential clients (i.e. clients able to authenticate)
  • 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 parameter is optional.

Further reading