Autentificare cu OAuth

Un asistent AI se autentifică la Setherion cu OAuth în loc de o cheie API: persoana apasă Allow pe o pagină Setherion, iar asistentul primește un token. Pagina aceasta este contractul pentru când îți construiești propriul client. Dacă vrei doar să conectezi Claude, ChatGPT, Cursor sau VS Code, urmează MCP: conectează un asistent AI.

Fluxul este OAuth 2.1, așa cum îl cere specificația de autorizare MCP (2025-06-18):

• fluxul cu cod de autorizare, cu PKCE (S256) cerut mereu;
• doar clienți publici, fără secret de client;
• înregistrare dinamică a clientului (RFC 7591), așa că nimeni nu lipește un id de client nicăieri;
• tokenuri legate de o singură resursă, endpointul MCP (RFC 8707).

Tokenurile funcționează pe serverul MCP și nicăieri altundeva. Endpointurile REST din această referință folosesc o cheie API.

1. Descoperă

Trimite o cerere către endpointul MCP fără nicio credențială. Răspunsul 401 indică metadatele resursei (RFC 9728) în antetul 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"
}

Același document se află la /.well-known/oauth-protected-resource. Apoi citește metadatele serverului de autorizare (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"]
}

Ambele documente, înregistrarea și endpointul de tokenuri răspund oricărei origini (Access-Control-Allow-Origin: *), așa că un client dintr-o pagină de browser le poate apela.

2. Înregistrează

Înregistrează-te o dată pentru fiecare instalare. Înregistrarea nu dă nimic prin ea însăși: o persoană tot trebuie să apese Allow, iar codul este trimis înapoi doar la adresele exacte înregistrate aici.

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"] }'

O adresă de redirecționare trebuie să fie https, sau http înapoi spre această mașină (localhost, 127.0.0.1 sau [::1]). Nu poate avea fragment sau nume de utilizator. Singura adresă care nu este https sau http este cursor://anysphere.cursor-mcp/oauth/callback, pentru aplicațiile Cursor mai vechi.

Oricare ar fi metoda de autentificare pe care o cere un client, el este înregistrat ca client public fără secret, iar răspunsul spune asta:

{
  "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"
}

Statusul este 201. Înregistrările sunt limitate la 20 pe oră pentru fiecare adresă de rețea.

3. Cere acordul persoanei

Deschide endpointul de autorizare în browserul persoanei. Este o pagină, nu un API: persoana se autentifică la Setherion dacă nu este deja autentificată, vede numele pe care l-ai înregistrat și unde va fi trimisă înapoi și apasă Allow sau 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

Fă verifier-ul din 43 până la 128 de caractere din A-Z a-z 0-9 - . _ ~ și păstrează-l până la pasul 4.

Persoana este trimisă înapoi la redirect_uri al tău cu:

• la Allow: code, state și iss (issuer-ul);
• la Cancel: error=access_denied, error_description=The request was declined., state și iss;
• la o problemă cu cererea, după ce clientul și adresa sunt cunoscute ca autentice: error, error_description, state și iss. error este unsupported_response_type, invalid_request (lipsește PKCE sau metoda nu este S256) sau invalid_target (resursa nu este endpointul MCP).

Dacă clientul este necunoscut sau adresa nu este una dintre cele înregistrate, pagina îi spune asta persoanei și nu trimite pe nimeni nicăieri, așa că pagina aceasta nu poate fi folosită niciodată ca să redirecționeze pe cineva către o adresă pe care nu ai înregistrat-o.

4. Schimbă codul

Trimite câmpuri codate ca formular, așa cum specifică OAuth. Se acceptă și JSON cu aceleași nume.

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"
}

Trimite tokenul de acces către serverul MCP ca Authorization: Bearer sto_.... Tokenurile nu sunt păstrate niciodată în cache: răspunsul poartă Cache-Control: no-store.

5. Reîmprospătează

Un token de acces ține o oră. Înainte să se termine, sau când serverul MCP răspunde 401, schimbă tokenul de reîmprospătare:

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

Răspunsul este la fel ca la pasul 4, cu un token de reîmprospătare nou. Cel vechi încetează să mai funcționeze, așa că păstrează-l pe cel nou de fiecare dată.

Erori

Fiecare eroare de la endpointul de tokenuri are statusul 400, în afară de server_error, și corpul { "error": "...", "error_description": "..." }.

Încheierea unei conexiuni

Persoana poate deconecta un asistent din Settings, apoi AI assistants and MCP. Toate tokenurile conexiunii, de acces și de reîmprospătare, încetează să mai funcționeze la următoarea cerere, nu când se termină ora. Listarea și încheierea conexiunilor se pot face doar dintr-o sesiune Setherion autentificată, așa că nimic din ce ține un asistent nu le poate face.

Cu o cheie API în schimb

Un client care poate trimite doar un antet fix poate sări peste toate acestea și poate trimite o cheie API către serverul MCP. Vezi Autentificare.