OAuth2 dla aplikacji zewnętrznych

OAuth2 z przepływem PKCE dla aplikacji zewnętrznych i integracji wielu użytkowników — przez realm Keycloak footage.one.

Kiedy OAuth2 zamiast tokena API?

Scenariusz Zalecenie
Osobisty agent (Claude Desktop, własne n8n) Token API
Aplikacja zewnętrzna z wieloma użytkownikami końcowymi OAuth2 / PKCE
Custom GPT z Actions OAuth2 (wymagane przez OpenAI)

Przepływ

footage.one używa Authorization Code Flow z PKCE — odpowiedniego dla klientów publicznych (SPA, mobile, desktop) i klientów poufnych (serwer).

1. Aplikacja otwiera URL autoryzacji z code_challenge
2. Użytkownik loguje się w Keycloak
3. Callback zwraca kod
4. Aplikacja wymienia kod + code_verifier na tokeny
5. Access token → nagłówek Authorization dla /api/asset/

Endpointy

footage.one używa Keycloak. Realm: footageone. Sama aplikacja Asset Manager działa pod adresem https://app.footage.one i uwierzytelnia się w tym samym realm.

  • Issuer: https://auth.footage.one/realms/footageone
  • OIDC Discovery: https://auth.footage.one/realms/footageone/.well-known/openid-configuration — dostarcza wszystkie URL endpointów, obsługiwane zakresy i klucze podpisu w formie maszynowo czytelnej.
  • Authorize: https://auth.footage.one/realms/footageone/protocol/openid-connect/auth
  • Token: https://auth.footage.one/realms/footageone/protocol/openid-connect/token
  • Userinfo: https://auth.footage.one/realms/footageone/protocol/openid-connect/userinfo

Dla większości bibliotek OAuth2 wystarczy issuer — endpointy są ładowane automatycznie przez discovery.

Zakresy

Zakres Znaczenie
openid Wymagany — zgodność z OIDC
profile Dane profilu użytkownika
email Adres e-mail

Zakresy specyficzne dla zasobów (assets:read, albums:write, …) nie są aktualnie zaimplementowane — access token odzwierciedla uprawnienia zalogowanego użytkownika.

Rejestracja klienta

Klienci OAuth są rejestrowane przez wsparcie footage.one — bez samodzielnej rejestracji. Wyślij prośbę z następującymi informacjami:

  • Nazwa aplikacji zewnętrznej
  • URI przekierowania (możliwe wiele)
  • Klient publiczny czy poufny?
  • Opis przypadku użycia

Następnie otrzymasz client_id (i client_secret dla klientów poufnych).

Następne kroki

Tokeny APICookbook