TikTok Login Kit: OAuth-поток и жизненный цикл токенов

Как работает OAuth в TikTok?

Ключевые термины: client key, client secret, open_id и токены

client_key

Открытый идентификатор приложения. Передаётся в ссылке авторизации и в запросах токена.

client_secret

Секретный ключ приложения. Используется только в серверных запросах к /v2/oauth/token/ и /v2/oauth/revoke/; не попадает в браузер или мобильную сборку.

code

Код авторизации, который приходит на redirect URI после согласия пользователя. Обменивайте его на токены сразу.

access_token

Bearer-токен для API-запросов, действует 24 часа с момента выдачи.

refresh_token

Нужен для получения нового access token; действует 365 дней с первой выдачи. В ответе на обновление может прийти другой refresh token.

open_id

Уникальный идентификатор пользователя TikTok, приходит вместе с токеном. Используйте его как ключ подключённого аккаунта.

state

Случайное значение, которое создаётся перед редиректом и сверяется в callback, — защита от CSRF.

Как настроить OAuth TikTok для веб-приложения

1. 1

   Зарегистрируйте redirect URI

   В настройках Login Kit добавьте до 10 redirect URI. Каждый должен быть абсолютным, начинаться с https, быть короче 512 символов, статическим (без query-параметров) и без фрагмента #.

2. 2

   Создайте и сохраните state

   Для каждой попытки входа генерируйте случайную строку и храните её в сессии пользователя или короткоживущем cookie. Официальный веб-пример TikTok тоже использует короткоживущий cookie.

3. 3

   Перенаправьте на страницу авторизации

   Откройте https://www.tiktok.com/v2/auth/authorize/ с client_key, response_type=code, scope через запятую, redirect_uri и state. Чтобы окно согласия показывалось всегда, добавьте disable_auto_auth=1.

4. 4

   Проверьте callback

   TikTok возвращает code, scopes и state, а при ошибке — error и error_description. Отклоняйте запрос, если state не совпал, и сверяйте выданные scopes с запрошенными.

5. 5

   Обменяйте код на сервере

   Отправьте POST на https://open.tiktokapis.com/v2/oauth/token/ в формате application/x-www-form-urlencoded с client_key, client_secret, code, grant_type=authorization_code и тем же redirect_uri. Desktop- и mobile-приложения передают ещё code_verifier.

6. 6

   Надёжно сохраните токены

   Храните access_token, refresh_token, оба срока и open_id в зашифрованном виде. Веб-гайд TikTok прямо возлагает на сервер ответственность за безопасность client secret и refresh token.

Login Kit на Python

Обработчики не привязаны к фреймворку: session — хранилище сессии вашего веб-фреймворка.

import secrets
from socialift import TikTok

REDIRECT_URI = "https://app.example.com/oauth/tiktok/callback"
SCOPES = ["user.info.basic", "video.list", "video.publish"]

async def begin_login(session: dict) -> str:
    session["tiktok_state"] = secrets.token_urlsafe(32)
    async with TikTok.from_env() as tt:
        return tt.login_url(
            redirect_uri=REDIRECT_URI,
            state=session["tiktok_state"],
            scopes=SCOPES,
        )

async def finish_login(session: dict, code: str, state: str) -> dict:
    expected = session.pop("tiktok_state", "")
    if not expected or not secrets.compare_digest(state, expected):
        raise ValueError("OAuth state mismatch")
    async with TikTok.from_env() as tt:
        bundle = await tt.exchange_code(code, redirect_uri=REDIRECT_URI)
    return {
        "open_id": bundle.raw.get("open_id"),
        "access_token": bundle.access_token,
        "refresh_token": bundle.refresh_token,
        "expires_at": bundle.expires_at,
        "scopes": bundle.scopes,
    }

PKCE: веб, desktop и mobile

Desktop-гайд TikTok вычисляет code_challenge как SHA-256 от verifier в hex-кодировке, а не в base64url, как в RFC 7636.

PKCE для desktop-приложений

Verifier должен быть длиной 43–128 символов и состоять только из A–Z, a–z, 0–9 и символов -, ., _, ~.

import hashlib
import secrets
from socialift import TikTok

REDIRECT_URI = "http://127.0.0.1:3455/callback/"

def make_pkce() -> tuple[str, str]:
    verifier = secrets.token_urlsafe(48)                       # 64 символа
    challenge = hashlib.sha256(verifier.encode()).hexdigest()  # hex, как в документации TikTok
    return verifier, challenge

async def desktop_login(state: str) -> tuple[str, str]:
    verifier, challenge = make_pkce()
    async with TikTok.from_env() as tt:
        url = tt.login_url(
            redirect_uri=REDIRECT_URI,
            state=state,
            code_challenge=challenge,
            code_challenge_method="S256",
        )
    return url, verifier

async def desktop_callback(code: str, verifier: str):
    async with TikTok.from_env() as tt:
        return await tt.exchange_code(code, redirect_uri=REDIRECT_URI, code_verifier=verifier)

Сроки жизни токенов и что с ними делать

естьнет

Ежедневное обновление и отзыв при отключении

from datetime import datetime, timedelta, timezone
from socialift import ApiError, TikTok

async def ensure_fresh(account: dict) -> dict:
    left = account["expires_at"] - datetime.now(timezone.utc)
    if left > timedelta(hours=2):
        return account
    async with TikTok.from_env() as tt:
        try:
            bundle = await tt.refresh_token(account["refresh_token"])
        except ApiError:
            account["status"] = "reconnect_required"
            return account
    account.update(
        access_token=bundle.access_token,
        refresh_token=bundle.refresh_token or account["refresh_token"],
        expires_at=bundle.expires_at,
    )
    return account

async def disconnect(account: dict) -> None:
    async with TikTok.from_env() as tt:
        await tt.revoke(account["access_token"])

Scopes и согласие на практике

Чек-лист безопасности OAuth TikTok

• ▸Храните client secret и refresh token только на сервере и в зашифрованном виде.
• ▸Создавайте новый state для каждого входа и отклоняйте callback с несовпадающим значением.
• ▸Регистрируйте точные статические HTTPS redirect URI; контекст передавайте через state или сессию, а не query-параметрами.
• ▸В desktop-приложениях используйте PKCE с S256 и передавайте code_verifier при обмене.
• ▸Обновляйте access token по расписанию чаще, чем раз в 24 часа, и сохраняйте сменившиеся refresh token.
• ▸Отзывайте токен через /v2/oauth/revoke/, когда пользователь отключается в вашем продукте.
• ▸Пишите в лог log_id неудачных запросов для поддержки TikTok.