Refresh Token Flow

Refresh tokeny umožňují získat nové access tokeny bez nutnosti interakce uživatele. To je nezbytné pro udržování dlouhotrvajících relací.

Předpoklady

• Musíte požádat o scope offline_access během počáteční autorizace
• Refresh tokeny jsou vydávány pouze s Authorization Code flow (ne Client Credentials)

Požadavek na obnovení tokenu

curl -X POST https://your-sso-domain.com/connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "client_id=my-app" \
  -d "client_secret=my-secret" \
  -d "refresh_token=R2FtY2tqZ0hkY3BXcTk4dFZ3bE5mM2xEMkNq..."

Parametry:

Parametr	Povinný	Popis
grant_type	Ano	Musí být refresh_token
client_id	Ano	Client ID vaší aplikace
client_secret	Podmíněně	Vyžadováno pro confidential klienty
refresh_token	Ano	Refresh token z předchozí token odpovědi

Odpověď:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6ImF0K2p3dCJ9...(nový)",
  "token_type": "Bearer",
  "expires_in": 1800,
  "refresh_token": "S2p2N3RhR2FtY2tqZ0hkY3BXcTk4dFZ3bE5m...(nový)",
  "id_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...(nový)",
  "scope": "openid profile email offline_access"
}

Refresh token je neprůhledný

refresh_token je neprůhledný (opaque), šifrovaný řetězec – na rozdíl od access tokenu nejde o čitelný JWT. Nepokoušejte se ho dekódovat ani z něj číst claims (např. expiraci); zacházejte s ním jako s neprůhledným tajemstvím a pouze ho ukládejte a posílejte zpět na token endpoint.

Rotace tokenů

Klubero SSO implementuje rotaci refresh tokenů pro zvýšení bezpečnosti:

• Každý refresh požadavek vrací nový refresh token
• Starý refresh token je zneplatněn
• Vždy ukládejte a používejte nejnovější refresh token

Důležité

Vždy ukládejte nový refresh token z každé odpovědi. Použití starého refresh tokenu po rotaci selže.

Životnost tokenů

Typ tokenu	Životnost	Poznámky
Access Token	30 minut	Krátká životnost pro bezpečnost
Refresh Token	14 dní	Umožňuje získat nové access tokeny
Authorization Code	5 minut	Jednorázové použití

Když obnovení selže

Refresh tokeny se mohou stát neplatnými z důvodu:

1. Token vypršel (po 14 dnech)
2. Token byl zrušen (uživatel se odhlásil, změnil heslo nebo akce administrátora)
3. Relace byla zneplatněna (bezpečnostní událost)
4. Opětovné použití tokenu (použití starého tokenu po rotaci)

Když obnovení selže, přesměrujte uživatele na autorizační endpoint pro opětovnou autentizaci.

Chybová odpověď:

{
  "error": "invalid_grant",
  "error_description": "The refresh token is no longer valid."
}

Osvědčené postupy

// Proaktivní obnovení tokenu (před vypršením)
function isTokenExpired(token, bufferSeconds = 300) {
  const payload = JSON.parse(atob(token.split('.')[1]));
  const expiresAt = payload.exp * 1000;
  return Date.now() >= expiresAt - (bufferSeconds * 1000);
}

async function ensureValidToken() {
  if (isTokenExpired(accessToken)) {
    try {
      const newTokens = await refreshAccessToken();
      accessToken = newTokens.access_token;
      refreshToken = newTokens.refresh_token; // Vždy aktualizujte!
    } catch (error) {
      // Obnovení selhalo - přesměrovat na přihlášení
      redirectToLogin();
    }
  }
  return accessToken;
}