Skip to Content

Dynamiczna rejestracja klientów

Samodzielna rejestracja aplikacji klienckich przez OAuth 2.0 Dynamic Client Registration z użyciem tokenów Initial Access Token.

Uwaga: Dostępne w subskrypcjach Advanced i Pro. Otwarta rejestracja agentów AI wymaga planu Pro.

W przypadku dynamicznej rejestracji klientów aplikacja kliencka rejestruje się sama, zamiast być tworzona ręcznie w Admin Console. Wysyła swoje metadane (nazwę, URI przekierowań, sposób uwierzytelniania klienta) do punktu końcowego rejestracji i otrzymuje w odpowiedzi identyfikator klienta, a w przypadku klientów poufnych również client secret. Platforma implementuje OAuth 2.0 Dynamic Client Registration (RFC 7591) oraz protokół zarządzania, który pozwala klientowi później odczytywać, aktualizować i usuwać własną rejestrację (RFC 7592).

Domyślnie każda rejestracja wymaga wystawionego przez administratora tokenu Initial Access Token, dzięki czemu administrator decyduje, kto i jak często może rejestrować klientów. W przypadku agentów AI i innych klientów publicznych można dodatkowo zezwolić na otwartą rejestrację.

Tokenami Initial Access Token zarządza się w konsoli administracyjnej w sekcji Integracje → Aplikacje → Rejestracje dynamiczne.

Jak to działa

  1. Wystaw token Initial Access Token i przekaż go stronie, która rejestruje klienta, na przykład partnerowi lub potokowi wdrożeniowemu.
  2. Klient wysyła żądanie rejestracji do punktu końcowego rejestracji, z tokenem Initial Access Token jako tokenem Bearer.
  3. Platforma sprawdza metadane zgodnie z opisanymi poniżej regułami, tworzy aplikację i odpowiada danymi uwierzytelniającymi klienta, tokenem Registration Access Token oraz własnym adresem URL zarządzania klienta.
  4. Za pomocą tokenu Registration Access Token klient może odczytać, zaktualizować lub usunąć swoją rejestrację. Każda aktualizacja wystawia nowy token Registration Access Token i unieważnia poprzedni.

Zarejestrowany klient jest wyświetlany na karcie Rejestracje dynamiczne w sekcji Zarejestrowane aplikacje, wraz z informacją o sposobie rejestracji i ostatnim użyciu. Jego strona szczegółów jest taka sama jak w przypadku każdej innej aplikacji, z oznaczeniem Zarejestrowana dynamicznie. Nikt nie może się jeszcze do niej zalogować: jak w przypadku każdej nowej aplikacji dostęp trzeba najpierw przypisać.

Wystawianie tokenu Initial Access Token

  1. Przejdź do Integracje → Aplikacje i otwórz kartę Rejestracje dynamiczne.
  2. Wybierz Wystaw token.
  3. Wprowadź Nazwa, na przykład nazwę partnera lub systemu, dla którego przeznaczony jest token. Pojawia się ona na liście i w dzienniku audytu.
  4. Ustaw Ważność w dniach (od 1 do 365). Token wygasa po tym okresie.
  5. Pozostaw zaznaczoną opcję Jednorazowy, jeśli token ma umożliwiać dokładnie jedną rejestrację. Usuń zaznaczenie, aby zezwolić na dowolną liczbę rejestracji do czasu wygaśnięcia tokenu.
  6. Wybierz Wystaw token i skopiuj token. Jest on wyświetlany tylko raz i nie można go później ponownie pobrać.

Strona pokazuje również Punkt końcowy rejestracji, który należy przekazać razem z tokenem. Jest on także publikowany jako registration_endpoint w dokumencie discovery OpenID Connect.

Lista pokazuje dla każdego tokenu sposób użycia, liczbę dokonanych za jego pomocą rejestracji, datę wygaśnięcia i osobę, która go wystawiła. Odbierz blokuje użycie tokenu do nowych rejestracji. Aplikacje już zarejestrowane za jego pomocą pozostają nienaruszone. Wygasłe tokeny są usuwane automatycznie.

Otwarta rejestracja agentów AI

Uwaga: Dostępne w subskrypcji Pro.

Agenty AI, na przykład klienty Model Context Protocol (MCP), oraz narzędzia wiersza poleceń rejestrują się same w chwili, gdy użytkownik je łączy, bez przekazywania tokenu przez kogokolwiek. Każda instalacja zwykle rejestruje własnego klienta. Otwarta rejestracja umożliwia właśnie to w przypadku klientów publicznych, które nie mają client secret i logują użytkowników za pomocą przepływu authorization code z PKCE.

  1. Przejdź do Ustawienia → Zaawansowane.
  2. Na karcie Otwarta rejestracja włącz opcję Otwarta rejestracja klientów publicznych.
  3. W sekcji Użytkownicy uprawnieni do logowania wybierz katalogi, których użytkownicy mogą korzystać z takich klientów.
  4. Wybierz Zapisz zmiany.

W przypadku klientów zarejestrowanych w sposób otwarty:

  • Akceptowane są tylko klienty publiczne. Rejestracja bez tokenu Initial Access Token musi wysłać "token_endpoint_auth_method": "none", a klient pozostaje publiczny: późniejsza aktualizacja nie może dodać client secret. Klienty poufne nadal wymagają tokenu Initial Access Token.
  • Dostęp wynika z katalogów. Użytkownicy wybranych katalogów mogą się logować po wyrażeniu zgody, bez przypisania do każdej aplikacji. Wybór dotyczy nowych rejestracji; aplikacje już zarejestrowane zachowują katalogi, z którymi zostały zarejestrowane.
  • Liczba rejestracji jest ograniczona do 10 na godzinę na adres IP klienta i 200 na godzinę łącznie (20 w okresie próbnym).
  • Nieużywane rejestracje są usuwane. Klient, do którego nikt się nie zalogował, jest usuwany po 24 godzinach; to samo dotyczy klienta bez logowań ani żądań tokenów przez 90 dni. Każde usunięcie jest rejestrowane w dzienniku audytu.
  • Nie ma właściciela. Aplikacje zarejestrowane w sposób otwarty nie są przypisane do żadnego administratora.

Punkt końcowy rejestracji jest ogłaszany w dokumencie discovery, udostępnianym pod adresem /.well-known/openid-configuration oraz, dla klientów OAuth, które go tam szukają, pod adresem /.well-known/oauth-authorization-server. Jeśli agent żąda tokenu dostępu dla określonego zasobu, takiego jak serwer MCP, należy zarejestrować ten zasób jako API.

Wyłączenie otwartej rejestracji zatrzymuje nowe anonimowe rejestracje. Już zarejestrowane klienty nadal działają i mogą zarządzać swoją rejestracją. Bez subskrypcji Pro użytkownicy katalogów nie otrzymują już automatycznie dostępu do klientów zarejestrowanych w sposób otwarty: należy przypisać ich jawnie, w przeciwnym razie nieużywane klienty zostaną usunięte po 90 dniach.

Rejestrowanie klienta

Klient wysyła swoje metadane jako żądanie JSON POST:

curl -X POST https://id.example.com/oidc/register \
  -H "Authorization: Bearer <initial access token>" \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "Partner Portal",
    "redirect_uris": ["https://portal.partner.example/callback"],
    "post_logout_redirect_uris": ["https://portal.partner.example/"],
    "grant_types": ["authorization_code", "refresh_token"],
    "token_endpoint_auth_method": "client_secret_basic"
  }'

Udana rejestracja zwraca odpowiedź 201 Created:

{
  "client_id": "V1StGXR8_Z5jdHi6B-myT",
  "client_secret": "...",
  "client_name": "Partner Portal",
  "redirect_uris": ["https://portal.partner.example/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "client_secret_basic",
  "registration_client_uri": "https://id.example.com/oidc/register/V1StGXR8_Z5jdHi6B-myT",
  "registration_access_token": "..."
}

Klient przechowuje client_secret i registration_access_token w bezpieczny sposób. Żadnej z tych wartości nie można ponownie pobrać.

Zarządzanie rejestracją

Klient zarządza swoją rejestracją pod adresem registration_client_uri, uwierzytelniając się bieżącym tokenem Registration Access Token:

ŻądanieSkutek
GETZwraca bieżącą rejestrację.
PUTZastępuje rejestrację przesłanymi metadanymi. Treść musi zawierać client_id; pominięte pole zostaje usunięte. Odpowiedź zawiera nowy token Registration Access Token.
DELETEUsuwa aplikację. Jej użytkownicy nie mogą się już do niej logować.

Administrator może edytować lub usuwać dynamicznie zarejestrowaną aplikację w Admin Console tak jak każdą inną. Należy pamiętać, że następne żądanie PUT klienta nadpisuje pola, które należą do klienta (nazwa, URI przekierowań, typy grantów, uwierzytelnianie klienta, URI klienta i klucze klienta). Przypisania, polityki, właściciele i ustawienie zgody pozostają takie, jak ustawił je administrator.

Czym może być zarejestrowany klient

MetadaneReguła
token_endpoint_auth_methodclient_secret_basic (domyślnie), client_secret_post, private_key_jwt lub none.
Typ aplikacjiWynika z uwierzytelniania klienta: none tworzy aplikację jednostronicową (single-page application) albo aplikację natywną, gdy zostanie wysłane "application_type": "native" lub każdy URI przekierowania jest adresem loopback (http://127.0.0.1, http://[::1], http://localhost) albo schematem specyficznym dla aplikacji. Natywne przekierowanie loopback pasuje do dowolnego portu. Każda inna metoda tworzy aplikację webową. Klient natywny musi używać none.
grant_typesMusi zawierać authorization_code, może dodatkowo zawierać refresh_token. Granty implicit, client credentials, device i token exchange są odrzucane.
response_typesTylko code.
redirect_uris, post_logout_redirect_urisBez symboli wieloznacznych (wildcard), bez URI w domenie samego dostawcy tożsamości.
client_uriMusi używać https.
jwksTylko klucze publiczne, RSA o długości co najmniej 2048 bitów lub EC na krzywej P-256. Wymagane dla private_key_jwt.
jwks_uri, sector_identifier_uri, backchannel_logout_uri, request_urisOdrzucane, ponieważ platforma musiałaby sama wywoływać te adresy URL. Administrator może później ustawić odpowiednie opcje w aplikacji.
client_nameOpcjonalne. Bez nazwy aplikacja otrzymuje nazwę „Dynamic client”, po której następuje jej identyfikator klienta. Do nazwy, która jest już zajęta, dołączana jest część identyfikatora klienta.
default_max_ageAkceptowane.

Wszelkie inne metadane są ignorowane i nie są częścią odpowiedzi.

Niektóre ustawienia są zawsze określane przez platformę, niezależnie od zawartości żądania:

  • Opcja Wymagaj zgody użytkownika jest włączona. Użytkownicy potwierdzają żądany dostęp przy pierwszym logowaniu, a tokeny odświeżania są wystawiane tylko wtedy, gdy klient zażąda scope'u offline_access.
  • Nie jest stosowany żaden profil bezpieczeństwa. Administrator może go ustawić później, zobacz Bezpieczeństwo Financial-grade API.
  • Aplikacja nie jest wyświetlana w portalu aplikacji użytkowników.
  • Administrator, który wystawił token Initial Access Token, staje się właścicielem aplikacji. Aplikacje zarejestrowane w sposób otwarty nie mają właściciela.

Rejestracje wliczają się do limitu aplikacji w subskrypcji.

Dziennik audytu

ZdarzenieRejestrowane, gdy
INITIAL_ACCESS_TOKEN_CREATEDAdministrator wystawia token Initial Access Token.
INITIAL_ACCESS_TOKEN_REVOKEDAdministrator odbiera token Initial Access Token.
CONFIGURATION_UPDATEDAdministrator włącza lub wyłącza otwartą rejestrację albo zmienia jej katalogi.
APPLICATION_REGISTEREDKlient się rejestruje. Rejestrujący klient jest zapisywany jako aktor.
APPLICATION_UPDATEDKlient aktualizuje swoją rejestrację.
APPLICATION_DEREGISTEREDKlient usuwa swoją rejestrację, administrator usuwa aplikację lub usuwana jest nieużywana otwarta rejestracja.

Pełną listę zawiera strona Typy zdarzeń audytu.

Rozwiązywanie problemów

  • invalid_token podczas rejestracji: token Initial Access Token jest nieznany, wygasł, został odebrany lub token jednorazowy został już użyty. Należy wystawić nowy. Bez tokenu otwarta rejestracja jest wyłączona.
  • 429 przy anonimowej rejestracji: osiągnięto limit otwartej rejestracji. Należy spróbować później.
  • invalid_token przy odczycie, aktualizacji lub usuwaniu: token Registration Access Token został przy ostatniej aktualizacji zastąpiony nowszym lub aplikacja została usunięta.
  • invalid_client_metadata z komunikatem „dynamic client registration is not available”: subskrypcja nie obejmuje tej funkcji. Rejestracje i aktualizacje są odrzucane; odczyt i usuwanie istniejącej rejestracji nadal działają.
  • invalid_client_metadata: metadane naruszają jedną z powyższych reguł. Pole error_description wskazuje odpowiednie pole. Odrzucone żądanie nie zużywa tokenu jednorazowego.
  • Użytkownicy nie mogą się zalogować po rejestracji: aplikacja nie ma jeszcze przypisań. Przypisz użytkowników, grupy lub katalogi na karcie Przypisania aplikacji. W przypadku klienta zarejestrowanego w sposób otwarty sprawdź, czy użytkownik należy do jednego z jego katalogów.

Zobacz też

Na tej stronie