Пасварды апдэтацы Keycloak і таймауты сесій: пояснення

Прыкладнікаў, які базуюцца на Keycloak, часам падчас апавержэння токена канцэнтры паказвае адпаведзь 400 Bad Request. Што можна сказаць прымусова, так гэта значыць, што працэс апавержэння не працуе. Частае прычына — Keycloak навмесна адмовляе: сэсія выйшла з актыўнасці, пасягнула максымальны тэрмін жыцця, была анульвана, або токен апавержэння больш не ўважаецца чынным. Гэтыя наследкі ёсць палітакай, а не дыфектамі.

У гэтым кярыранцы разбіраюцца найважлівейшыя аспекты для працы ў рэальных умовах: як функціонуюць токены доступу і апавержэння, як працюе працэс апавержэння з самага початку да канца, якія два таймеры сэсій карбуюць успешнае апавержэння, а таксама шаблоны і анты-шаблоны працы фронтэнду з рашэнням іншых сітуацый.

Чаму існуе гэтыя статты

Калі канцэнтра токена вяртае 400, команды часта фіксуюць баг у аўтэнтыфікацыі. Першы корыстны вопыт — якое правіло тэрміну жыцця чы анульвання спрацавала. Розумеўшы адпаведзь на гэты вопыт, можна ухіліцца ад таго, каб правільная адмова спрыяла выкліканню проблем.

1. Два токена, два абсалютна разныя завадзі

Пасля заходу ў сістэму Keycloak зазвычай выдае токен доступу, токен апавяржэння і токен ID. Кождадзённая праца залежыць ад першых двух.

• Токен доступу — Даўаецца праз звычныя запыты API, ў тым часе каб падтвердзіць, хто здаёць запыт. Ёго трымкі вялікія, часта меруюцца хвілінамі.
• Токен апавяржэння — Надаецца толькі Keycloak, каб быў выданы новы токен доступу. Ёго трымкі дэльнейшыя, зазвычай трыдцаць хвілін або больш.
• Токен для працы без інтэрнэту — Апшаронны токен дакладжэння, які можа працаваць дыяўольш час ад звычной сесіі SSO, і які рэгулюецца адзельной політыкай.

Практычны прыклад: токен доступу — гэта врэмяні бейдж, які паказваецца пры кожных входзе. Токен апавяржэння — гэта дакументы, які заменяе бейдж; ёго ніколі не паказваюць API-застосункам і ён павінен прыбываць толькі да тэрміналу токенав Keycloak.

2. Звычны алгорытм

Працэўлегчэнне аблогавання вяртае набор токенаў. Пасля чаго кліент пры кожным вызыве дадае токен адзыўку:

GET /api/products
Authorization: Bearer eyJ...

Трываласць дзеяння токенаў ёсць короткай — зазвычай пяць-пятнаццаць хвілін. Калі аблогаванне выкарыстоўвае токен адзыўкі на пяць хвілін і выкаана о 09:00, то да 09:05 наступны вызыв API вяртае 401 Unauthorized.

Гэты код 401 не означае негайнае выйшчы з сістэмы. Цэў сігнал да апавярнення токена.

3. Сам вызыв апавярнення

Кліент надае токен апавярнення на канцэнтры токенаў Keycloak:

POST /realms/{realm}/protocol/openid-connect/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
client_id=<client-id>
refresh_token=<refresh-token>

Успешны рэзультат выглядае так:

{
  "access_token": "new-access-token",
  "expires_in": 300,
  "refresh_token": "new-refresh-token",
  "refresh_expires_in": 1800
}

Кліент зберагае новы токен адзыўкі, прабуе зноў выкарыстоўваць первісны запіт, і корыстнік ніколі не бачыць гэтага перэходу.

4. Практыка апавярнення: заменіце збераганы токен апавярнення ў кожны раз

У адказе частаючы ўключаецца таксама нэвыпусканный токен абнавлення. Калі увімкнута ротацыя токенав абнавлення, пакананы токен абнавлення стае нэвалідным як толькі выдаёцца новы. Павторна адналежнае іспользованне старага значэння завершваецца неудачай пад наступной абнавленні.

// Correct
saveAccessToken(response.access_token);
if (response.refresh_token) {
  saveRefreshToken(response.refresh_token);
}

// Wrong — keeps using the token that rotation just invalidated
const refreshToken = originalRefreshToken;

Зберагчы пераранаванае значэння токена абнавлення пасля кожнага успеху — не толькі пасля заходжання — гэта і ўражае разлік межы сесіі, якая тыха абнавляецца гадзіны, і сесіі, якая завершваецца неудачай пад другой спробе.

5. Idle versus Max: часоўнікі, якія керуюць абнавленням

Realm-ы поставляюць прынеймна два часоўнікі сесій, і змена ўхіднасці яных вызывае большасць запытанняў тыпу «чаму аўтэнтыфікацыя злучылася»:

• SSO Session Idle — як дзялей сесія можа застацца без жадных дзеянняў, прычым Keycloak яе завершвае. Успешнае абнавлення лічыцца як дзеянне і скасоўвае гэты часоўнік.

Максымальны часы сесіі SSO — жорсткі ліміт па загальнай трываласці, вылічванай з момента пачатковага заходу. Актуалізацыя не скасоўвае яго. Нічога іншага таксама не робіць.

Корача кажучы:

IDLE = how long since the session was last active
MAX  = how long since the user originally logged in

З Idle = 30 хвілін і Max = 16 гадзін частая актуалізацыя дазволяе трываласці часу без дзейнасці заставацца маленькай пра весь дзень, але пасля 16 гадзін з момента заходу сесія завершваецца, нават калі корыстнік быў актываў ўсьмохвілінку раней. Ідэальны час актуалізацыі не можа перакрыць максымальны ліміт; ён толькі парадзюе трываласць внутры гэтага перыяда.

Налашчыкі Idle/Max для кожнага кліента адпавядаюць налашчыкам часоў рэйлма, але толькі для таго кліента. Праўяе значэння — гэта тое, якое ёсць строгейшым.

Чаму ў прыкладах паказана максімум 16 гадзін: каманда ERP, якая працуе практычна 12 гадзін, можа выбраць 12 гадзін працы плюс 4 гадзіны рэзерву, ўпэўніваючыся, што сесія будзе працаваць цэлы дзень без неабяжнага прабавання ўвайсу серэд задач і не будзе трываць безканечна. Гэта чысло — адны з бізнес-выбораў; важлівай спэцыяльнасцю ёсць знанне таго, каму паслужае гэты час.

Чаму трыдцятыхвілінны перыяд без дзеяння ўсё ж здывоўвае людэй: нават праз ўзніжаны максімум, довгі обед чы зустрэча можу раней завершыць перыяд без дзеяння. Калі корыстувачы маюць можлівасць вернуцца без прабавання ўвайсу, падход да перыяду без дзеяння трэба рассматрываць як аспект продукту/безпекі, а не толькі як прыемлівасць у кодзе кліента.

6. Чытанне 400 з тэндэнта токена без прыпуску аб перыводзе:

Неспяшанне апдэйту можа выглядаць так:

{
  "error": "invalid_grant",
  "error_description": "Token is not active"
}

Гэты пэйлоад можа аднасці да кальколька розных сітуацый:

• Аутэнтыфікацыйныя даны самі па сабе сталі нэваліднымі

Палітры бездзейнаўкі заверылі сесію SSO

Дасягнута максымальная трываласць з момента заходжання

Кінавы корыстувач або аператар выразна заверылі сесію

Адміністратыўнае анулюванне падрыхтавало сесію

Процэс ротацыі падрыхтаваў пакойны значэння апдатчыка, якое кліент усё ўтрымвае

Конкуруючыя працэсы апдатчыка спрычынілі тое, што адны выкорысталі крэдытнае паведамленне, якое ўжо было замененае іншым запытам

Ні адна з гэтых прычын не ўзначае, што “API не працуе”. Перад тым, як выдвігаць іншыя заключэння, прачытайце значэнні error і error_description.

7. Правільнае адкалканне на фронтэндзе

Стойкая схема:

401 on API request
  → try refresh, exactly once
      → success: save new tokens, retry the original request
      → failure: clear auth state, redirect to login

Не трэба безканечна прабаваць: 401, апдатчык, 400, зноў апдатчык. Адна нерабочая сесія можа спрычыніць наплыв запытоў на токены і стан спінера, які ніколі не завершыцца. Спрыймайце адказ пра няверны апдатчык як остатній — паслабіце крэдытнае паведамленне, ачысціце стан автэнтыкацыі, перадайце на экран заходжання і зупініце процэс.

8. Для фан-ауту 401-ых кодаў патрэбна адна спяльная процедура адрэнування

Дашборд, які адправляе пяць вызоў адразу з істэклым токенам доступу, отрымае пяць 401-ых кодаў. Калі кожны пат выкаанаць незалежна ў рамках ротацыі, першы успех уневажлівае токен, які ўсё ж застаўся у іншых чатырох — тады чатыры процедуры адрэнування збяжаюць з кодам 400 invalid_grant, нават калі сесія была нормальная.

Серыязаваць процедуру адрэнування: першы 401-ы код ачынае адну обяцанне; іншыя элементы чакаюць тую ж обяцанне і прабуюць знову пасля таго, як яна будзе выпаная.

if (tokenExpired) {
  if (!refreshInProgress) {
    refreshInProgress = refreshToken();
  }

  try {
    const tokens = await refreshInProgress;
    updateTokens(tokens);
    return retryOriginalRequest();
  } finally {
    refreshInProgress = null;
  }
}

Незалежна ад таго, чыяму замак ўтвораны з ручна стваранай обяцанні, з кола інтэрсептара Axios чы з абгорткі baseQuery RTK Query, правіла застаюцца незменнымі: адна процедура адрэнування ў выконанні, незалежна ад таго, сколькіх вызывачаў чакае.

9. Наладжэнні, якія здаюцца супаўзелеглымі, але не ёсць такімі: час тайма-ауту для заходжання і час тайма-ауту для дзеяння пад час заходжання

Іншыя два настройкі гэтаго рэгіону легка плутаць з тымчасавам дзеяння сесіі, але яны кантролююць толькі процэс заходжання:

• Жорсткі тымчасава заходжання — як дазейнае цэлы працэс аўтэнтыфікаціі (даныя праўа доступу, MFA, неабходныя дзеяння).
• Жорсткі тымчасава дзеяння пад час заходжання — як дазейнае адзін конкрэтны крок (напрыклад, экран з OTP) без адпаведнай рэакціі.

Ніякі з гэтых параметраў не прарабоцуе вялікага тымчасава дзеяння вясна аўтэнтыфікованай сесіі. Яны маюць значэнне толькі пакуль корыстнік яшчэ заходзіць у сістэму.

10. Сесіі па адключэнні — інструмент для іншай проблемы

Рэгіоны таксама можу ствараць сесіі па адключэнні за дапамою параметра scope=offline_access. Гэтыя сесіі дазваляюць отрымаць новыя токены доступу нават пасля заканчэння звычайной сесіі SSO — яны прызначаны для “заставы аутэнтыфікаціі завтра і наступнай недзелы”, а не толькі на адзіны рабочы дзень.

Для звычнага вядзення ў рабочы час (з перыодам адпачынку і рэзервам) зазвычай няма патрэбы ў афлайн-доступе. Налагоджаны параметр Session Max ёсць простэйшы і надзеяны. Афлайн-рэжым трэба выкорыстоўваць толькі тады, калі справжней патрэбай ёсць зберэжэння даных працоўніка пра гады або тыжні.

11. Спіс пераконтроўк для адлучэння бяга: калі пасля апдэта з’яўляецца код 400

Выконваюце крокі ў такой 순서:

1. Чытайце значэння error і error_description у адпаведзі.
2. Пораўняйце час заходжання з параметрам Session Max на рэлэме і кліянцы.
3. Пораўняйце перыод бездзейнасці з параметрам Session Idle на рэлэме і кліянцы.
4. Пераканайцеся, што кліянт выконвае свае настройкі пад раздэлам Clients → <client> → Advanced.
5. Пераканайцеся, што ўвімкнута замена токену апдэта.
6. Пераканайцеся, што не выконваліся кансультатыўныя запіты адразу.
7. Пераканайцеся, што кліянт зберагае найновейшы токен апдэта пасля кожнага апавершэння, а не толькі першы.

Пераканацеце, чы рэжым быў завершаны ручна аднойчы корыстнікам чы адміністратаром.

12. Ментальная мадэль, якую трэба падтрымваць

Тры слоі, пры чым залежнасці выконваюцца толькі ў аднам напрамку:

Access token                   → used for normal API calls
Refresh token                   → used to get a new access token
Keycloak session (Idle + Max)   → decides whether that refresh is allowed at all

Токен апавяржэння ніколі не ёсць незалежным ад свайго рэжыму. Калі рэжым знік — тое ў стане паціклування занадта давго, перасягнута максымальная трываласць, токен анульваны чы корыстнік выйшаў, — ніякі токен апавяржэння не можа яго воскрэсіць. Такая немагчымасць ўскладніла працу есць стандартным рэзультатам работы сістэмы.

Спіс пераканацэнняў

• Расследжваце заканчэнне тэрміну дзейнасці токена доступу окрэма ад завершэння рэжыму — спробавайце адно паўнергуванне, перш чым спрыяць код 401 як выхад з рэжыму.
• Зберагаце апавяржэнчы крэдытны токен пасля кожнага успеху, а не толькі новы токен доступу JWT.
• Памятаце пра два таймеры: аднойчы актыўнасць павяржае стан паціклування; таймер, які запускаецца з моменту заходжання, керуе максымальным тэрміном.
• Зробіце так, каб няудача паўнергування была остаточной — адна спроба, пасля чаго вычыстыце крэдытныя даныя і прабудзіце корыстніка да заходжання; ніколі не працаваце ў цыкле.

З’едыніць чатыры запіты з кодам 401 у адну спяльную обяву пра павынавленне замест пяці незалежных запытов.

Закаляць таймауты заходу ў сістэму і дзеяння пад час заходу ў сістэму ў кантэйнерэ процедуры заходу; яны не належаць да катэгорыі Idle/Max.

Зарэзерваваць сесіі па з’ўязку без інтэрнэту для потрэб довгачаснага застаўлення ў сістэме, а не для звычайнага SSO на трываласць змяны.

Спачатку прачытаць пакет даных з адзінкай пункту пры запуску; код 400 зазвычай абазаваны на конкрэтным адхіленні ад правіла, а не на збое.