Logowanie przez OAuth

Asystent AI loguje się do Setherion przez OAuth zamiast kluczem API: osoba klika Allow na stronie Setherion, a asystent dostaje token. Ta strona to umowa dla budowy własnego klienta. Jeśli chcesz tylko połączyć Claude, ChatGPT, Cursor lub VS Code, skorzystaj z MCP: podłącz asystenta AI.

Przepływ to OAuth 2.1, tak jak wymaga tego specyfikacja autoryzacji MCP (2025-06-18):

• przepływ z kodem autoryzacji, z zawsze wymaganym PKCE (S256);
• tylko klienci publiczni, bez sekretu klienta;
• dynamiczna rejestracja klienta (RFC 7591), więc nikt nigdzie nie wkleja identyfikatora klienta;
• tokeny przypisane do jednego zasobu, punktu końcowego MCP (RFC 8707).

Tokeny działają na serwerze MCP i nigdzie indziej. Punkty końcowe REST tej dokumentacji przyjmują klucz API.

1. Wykrywanie

Wyślij żądanie do punktu końcowego MCP bez żadnych danych uwierzytelniających. Odpowiedź 401 wskazuje metadane zasobu (RFC 9728) w nagłówku WWW-Authenticate:

curl https://www.setherion.com/.well-known/oauth-protected-resource/api/mcp

{
  "resource": "https://www.setherion.com/api/mcp",
  "authorization_servers": ["https://www.setherion.com"],
  "bearer_methods_supported": ["header"],
  "scopes_supported": ["mcp"],
  "resource_name": "Setherion"
}

Ten sam dokument jest pod adresem /.well-known/oauth-protected-resource. Potem odczytaj metadane serwera autoryzacji (RFC 8414):

curl https://www.setherion.com/.well-known/oauth-authorization-server

{
  "issuer": "https://www.setherion.com",
  "authorization_endpoint": "https://www.setherion.com/oauth/authorize",
  "token_endpoint": "https://www.setherion.com/api/oauth/token",
  "registration_endpoint": "https://www.setherion.com/api/oauth/register",
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code", "refresh_token"],
  "code_challenge_methods_supported": ["S256"],
  "token_endpoint_auth_methods_supported": ["none"],
  "scopes_supported": ["mcp"]
}

Oba dokumenty, rejestracja i punkt końcowy tokenów odpowiadają każdemu originowi (Access-Control-Allow-Origin: *), więc klient na stronie w przeglądarce może je wywoływać.

2. Rejestracja

Rejestruj raz na instalację. Sama rejestracja niczego nie przyznaje: osoba nadal musi kliknąć Allow, a kod jest odsyłany tylko na dokładnie te adresy, które tu zarejestrowano.

curl -X POST https://www.setherion.com/api/oauth/register \
  -H "Content-Type: application/json" \
  -d '{ "client_name": "My assistant", "redirect_uris": ["http://localhost:8787/callback"] }'

Adres przekierowania musi być https albo http z powrotem do tego komputera (localhost, 127.0.0.1 lub [::1]). Nie może mieć fragmentu ani nazwy użytkownika. Jedyny adres, który nie jest https ani http, to cursor://anysphere.cursor-mcp/oauth/callback, dla starszych aplikacji Cursor.

Niezależnie od metody uwierzytelniania, o którą prosi klient, jest on rejestrowany jako klient publiczny bez sekretu, a odpowiedź to mówi:

{
  "client_id": "5f0c2a9d-4e30-4d7f-b8a5-6f1c2a9d4e30",
  "client_id_issued_at": 1790000000,
  "client_name": "My assistant",
  "redirect_uris": ["http://localhost:8787/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none"
}

Status to 201. Rejestracje są ograniczone do 20 na godzinę z jednego adresu sieciowego.

3. Zapytaj osobę

Otwórz punkt końcowy autoryzacji w przeglądarce osoby. To strona, a nie API: osoba loguje się do Setherion, jeśli jeszcze tego nie zrobiła, widzi zarejestrowaną przez ciebie nazwę i miejsce, do którego zostanie odesłana, i klika Allow albo Cancel.

https://www.setherion.com/oauth/authorize
  ?response_type=code
  &client_id=5f0c2a9d-4e30-4d7f-b8a5-6f1c2a9d4e30
  &redirect_uri=http%3A%2F%2Flocalhost%3A8787%2Fcallback
  &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
  &code_challenge_method=S256
  &state=af0ifjsldkj
  &resource=https%3A%2F%2Fwww.setherion.com%2Fapi%2Fmcp

Zrób weryfikator z 43 do 128 znaków spośród A-Z a-z 0-9 - . _ ~ i zachowaj go do kroku 4.

Osoba jest odsyłana do twojego redirect_uri z:

• po Allow: code, state i iss (issuer);
• po Cancel: error=access_denied, error_description=The request was declined., state i iss;
• przy problemie z żądaniem, gdy klient i adres są już uznane za prawdziwe: error, error_description, state i iss. Wartość error to unsupported_response_type, invalid_request (brak PKCE albo metoda nie jest S256) lub invalid_target (zasób nie jest punktem końcowym MCP).

Jeśli klient jest nieznany albo adres nie jest jednym z zarejestrowanych, strona mówi o tym osobie i nikogo nigdzie nie wysyła, więc tej strony nigdy nie można użyć do przekierowania kogoś na adres, którego nie zarejestrowano.

4. Wymień kod

Wyślij pola zakodowane jako formularz, tak jak określa OAuth. JSON z tymi samymi nazwami też jest przyjmowany.

curl -X POST https://www.setherion.com/api/oauth/token \
  -d grant_type=authorization_code \
  -d code=stc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \
  -d client_id=5f0c2a9d-4e30-4d7f-b8a5-6f1c2a9d4e30 \
  -d redirect_uri=http://localhost:8787/callback \
  -d code_verifier=YOUR_VERIFIER

{
  "access_token": "sto_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "str_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "scope": "mcp"
}

Wyślij token dostępu do serwera MCP jako Authorization: Bearer sto_.... Tokeny nigdy nie są buforowane: odpowiedź ma nagłówek Cache-Control: no-store.

5. Odświeżanie

Token dostępu działa godzinę. Zanim wygaśnie, albo gdy serwer MCP odpowie 401, wymień token odświeżania:

curl -X POST https://www.setherion.com/api/oauth/token \
  -d grant_type=refresh_token \
  -d refresh_token=str_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \
  -d client_id=5f0c2a9d-4e30-4d7f-b8a5-6f1c2a9d4e30

Odpowiedź jest taka sama jak w kroku 4, z nowym tokenem odświeżania. Stary przestaje działać, więc za każdym razem zapisuj nowy.

Błędy

Każdy błąd z punktu końcowego tokenów ma status 400, poza server_error, oraz treść { "error": "...", "error_description": "..." }.

Kończenie połączenia

Osoba może odłączyć asystenta w zakładce Settings, potem AI assistants and MCP. Każdy token tego połączenia, dostępu i odświeżania, przestaje działać przy następnym żądaniu, a nie dopiero gdy minie godzina. Wyświetlanie i kończenie połączeń jest możliwe tylko z zalogowanej sesji Setherion, więc nic, co trzyma asystent, nie może tego zrobić.

Zamiast tego klucz API

Klient, który potrafi wysłać tylko stały nagłówek, może pominąć to wszystko i wysłać klucz API do serwera MCP. Zobacz Uwierzytelnianie.