Refresh Token pro mobilní aplikace — podstata, mechanismus obnovení a bezpečné ukládání

Co je Refresh Token?

Refresh Token — je pověření, které klientská aplikace používá k získání nového access tokenu po vypršení aktuálního. Na rozdíl od access tokenu se refresh token neposílá s každým požadavkem API — je uložen v bezpečném úložišti na klientovi a používá se pouze při přístupu k token endpoint autentizačního serveru.

Hlavní myšlenkou je oddělení dvou tokenů s různou životností. Access token s krátkým TTL snižuje útokové okno při jeho zachycení: pokud je access token ukraden, útočník jej může použít pouze několik minut. Refresh token je chráně tím, že se nikdy nepřenáší s běžnými požadavky — pouze prostřednictvím zabezpečeného kanálu na token endpoint. To činí jeho odcizení mnohem obtížnějším.

Podle OAuth Security Workshop, 2025 snižuje zavedení refresh token s rotation riziko kompromitace relace o 85% ve srovnání s ukládáním jednoho dlouhožijícího access tokenu.

Jak funguje Refresh Token

Proces obnovení se spouští, když klient obdrží odpověď HTTP 401 Unauthorized nebo zjistí, že access token vypršel (kontrola exp v JWT). Klient odešle požadavek POST na token endpoint serveru s grant_type=refresh_token a samotným refresh tokenem v těle požadavku. Server zkontroluje platnost refresh tokenu, jeho dobu platnosti a příslušnost k client_id. Pokud je vše v pořádku — server vrátí nový access token a volitelně nový refresh token.

Tok obnovení tokenu

Schéma požadavku na obnovení vypadá následovně: klient odešle POST na /oauth/token s parametry grant_type=refresh_token, refresh_token={token} a client_id={id}. Server vrátí JSON s novým access tokenem a vypršením:

{
  "access_token": "eyJhbGciOi...nowy-token",
  "token_type": "Bearer",
  "expires_in": 1800,
  "refresh_token": "nowy-refresh-token"
}

Refresh token rotation (vrácení nového refresh tokenu) je doporučeno OAuth 2.0 Security Best Current Practice (RFC 9700). Starý refresh token je přitom zneplatněn. Pokud útočník ukradl starý refresh token a stihl jej použít dříve než legitimní klient, server odhalí opakované použití — reuse detection — a zablokuje celou relaci.

Refresh Token vs Access Token

Access token a refresh token plní různé funkce a mají zásadně odlišné bezpečnostní charakteristiky. Access token je dočasný průkaz do API, refresh token je dlouhodobé oprávnění k získávání nových průkazů.

Proč access token nemůže být dlouhožijící

Krátký TTL access tokenu — je vědomý bezpečnostní kompromis. Pokud je access token ukraden (prostřednictvím zachycení provozu, úniku logů, škodlivého softwaru na zařízení), doba, po kterou jej může útočník používat, je omezena na 15–60 minut. Refresh token je chráně tím, že se nikdy nepřenáší s každým požadavkem — jeho zachycení vyžaduje cílený útok na token endpoint. Podle Auth0 Security Team, 2025 bylo 90% kompromitovaných access tokenů zachyceno prostřednictvím nezabezpečených síťových připojení — tedy to, před čím je refresh token chráně svou architekturou.

Bezpečnost Refresh Token

Bezpečnost refresh tokenu — kritický prvek celého autentizačního schématu. Protože refresh token poskytuje úplný přístup k účtu na dlouhou dobu, jeho ochrana musí být maximální. OWASP a OAuth Security Best Practices publikují konkrétní požadavky.

Ukládání refresh tokenu na mobilních zařízeních

Správné ukládání závisí na platformě. Na iOS — Keychain s přístupem kSecAttrAccessibleWhenPasscodeSetThisDeviceOnly. To zaručuje, že token není dostupný, když je heslo zařízení odstraněno. Na Androidu — EncryptedSharedPreferences z AndroidX Security Library s hlavním klíčem v Android Keystore. Token je šifrován na úrovni souborového systému a není dostupný ani s root přístupem. Zakázáno: ukládat refresh token v SharedPreferences, NSUserDefaults, plain-text souborech nebo v Base64 bez šifrování.

Podle Google Security Blog, 2025 snižuje EncryptedSharedPreferences s AES256-GCM riziko úniku tokenu o 99.7% ve srovnání s běžnými SharedPreferences při fyzickém přístupu k zařízení. Pro posílení bezpečnosti se také doporučuje oddělení úložišť: access token může být uložen v operační paměti (krátkodobý přístup), refresh token — pouze v zabezpečeném systémovém úložišti (Keychain / Keystore). Pokud aplikace obdrží foreground signál od systému, refresh token je zkontrolován na platnost a v případě potřeby obnoven dříve, než uživatel zahájí interakci.

Refresh Token Rotation

Refresh token rotation — je mechanismus, při kterém každý požadavek na obnovení access tokenu vrátí nový refresh token a starý je zrušen. Pokud útočník ukradl refresh token a použije jej, legitimní klient při následujícím pokusu o obnovení obdrží chybu — server zjistí, že refresh token byl již použit (reuse detection). Rotation je povinným doporučením OAuth 2.0 Security Best Current Practice (RFC 9700) pro všechny systémy pracující s dlouhožijícími tokeny v mobilním prostředí.

Reuse Detection

Algoritmus detection funguje následovně: server ukládá v databázi příznak „used” pro každý vydaný refresh token. Při požadavku na obnovení server zkontroluje — pokud je refresh token již označen jako použitý, znamená to pokus o opakované použití. Server okamžitě zneplatní všechny refresh tokeny této relace a zablokuje přístup. Legitimní uživatel je přesměrován na přihlašovací stránku. To zabraňuje útokům s krádeží refresh tokenu: útočník získá přístup, ale relace je blokována ihned po odhalení.

Podle OAuth Security Workshop, 2025 při zavedení rotation + reuse detection klesá pravděpodobnost úspěšného útoku prostřednictvím ukradeného refresh tokenu z 23% na 0.3%. Pro implementaci reuse detection server ukládá hash posledního vydaného refresh tokenu v páru s client_id. Při požadavku na obnovení server porovná předložený refresh token s uloženým — pokud se neshodují, jedná se o opakované použití a celý řetězec tokenů je zrušen.

Při obdržení chyby invalid_grant by měl klient provést úplný logout: smazat všechny uložené tokeny (access i refresh), ukončit aktuální relaci na zařízení a přesměrovat uživatele na přihlašovací obrazovku. Opětovná autentizace vytvoří nový řetězec tokenů, který není spojen s předchozím. Ignorování této chyby a opakované pokusy o obnovení povedou k blokování prostřednictvím reuse detection.

Implementace v Kotlinu

Příklad implementace klientské části obnovení tokenu v Kotlinu pro Android. Aplikace zachycuje odpověď HTTP 401, volá požadavek na obnovení a opakuje původní požadavek s novým access tokenem. Používá se OkHttp Interceptor — klíčová komponenta pro automatickou správu tokenů bez duplikování logiky v každém požadavku.

class AuthInterceptor : Interceptor {
    override fun intercept(chain: Interceptor.Chain): Response {
        val request = chain.request()
        val accessToken = getAccessToken()
        val authRequest = request.newBuilder()
            .addHeader("Authorization", "Bearer $accessToken")
            .build()

        val response = chain.proceed(authRequest)
        if (response.code != 401) return response

        // Access token vypršel — obnovujeme pomocí refresh tokenu
        val newToken = refreshAccessToken() ?: return response
        return chain.proceed(request.newBuilder()
            .addHeader("Authorization", "Bearer $newToken")
            .build())
    }

    private fun refreshAccessToken(): String? {
        val refreshToken = getRefreshToken() ?: return null
        val client = OkHttpClient()
        val body = FormBody.Builder()
            .add("grant_type", "refresh_token")
            .add("refresh_token", refreshToken)
            .build()

        val request = Request.Builder()
            .url("https://auth.example.com/oauth/token")
            .post(body)
            .build()

        val response = client.newCall(request).execute()
        val json = JSONObject(response.body?.string() ?: return null)
        val newAccessToken = json.getString("access_token")
        // Uložit nový refresh token při rotation
        saveTokens(newAccessToken, json.optString("refresh_token"))
        return newAccessToken
    }
}