# OAuth DI programų kūrėjams

> Kaip DI programa prisijungia prie HRC pagalbos MCP: OAuth 2.1 aptikimas, dinaminė kliento registracija, PKCE S256, sutikimo langas ir žetonai.

Šis puslapis skirtas tiems, kurie kuria DI programą ar MCP klientą. Jei tik jungiate savo programą, skaitykite [DI agento prijungimas per MCP](https://hrc.lt/dokumentacija/ai-agentai/mcp).

HRC pagalbos MCP serveris naudoja OAuth 2.1 su dinamine kliento registracija (RFC 7591) ir PKCE. Kliento slaptažodžio nėra (`token_endpoint_auth_method: none`).

## Aptikimas

Kvietimas be žetono gauna `401` su nuoroda į išteklių aprašą:

```sh
curl -s -i https://mcp.hrc.lt/mcp -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"ping"}' | grep -i www-authenticate
# WWW-Authenticate: Bearer resource_metadata=
#   "https://mcp.hrc.lt/.well-known/oauth-protected-resource/mcp"

curl -s https://mcp.hrc.lt/.well-known/oauth-protected-resource/mcp
curl -s https://mcp.hrc.lt/.well-known/oauth-authorization-server
```

## Kliento registracija

Nuo 1 iki 20 `redirect_uris`: `https`, `http` tik `localhost`, `127.0.0.1` ar `[::1]`, arba programos schema (pavyzdžiui `cursor://...`).

```sh
curl -s https://mcp.hrc.lt/oauth/register \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "My AI app",
    "redirect_uris": ["https://app.example.com/oauth/callback"]
  }'
# 201 {"client_id":"...","token_endpoint_auth_method":"none",
#   "grant_types":["authorization_code","refresh_token"], ...}
```

## Autorizacija su PKCE

Nukreipkite naudotoją į autorizacijos adresą su `code_challenge_method=S256`:

```text
https://mcp.hrc.lt/oauth/authorize
  ?response_type=code
  &client_id=CLIENT_ID
  &redirect_uri=https%3A%2F%2Fapp.example.com%2Foauth%2Fcallback
  &code_challenge=BASE64URL_SHA256_OF_VERIFIER
  &code_challenge_method=S256
  &state=RANDOM_STATE
  &resource=https%3A%2F%2Fmcp.hrc.lt%2Fmcp
```

Naudotojas prisijungia prie [https://app.hrc.lt](https://app.hrc.lt/login?lang=lt) ir sutikimo lange pasirenka esamą DI agentą arba sukuria naują (pagal nutylėjimą su ruošiniu „Kasdien“), tada spaudžia „Leisti“. Prisijungimo prašymas galioja 10 minučių, gautas kodas 5 minutes ir tik vieną kartą.

![Sutikimo langas su DI programos pavadinimu](https://hrc.lt/screens/lt/oauth-consent.desktop.1600.25435f85.webp)

## Žetonai

Prieigos žetonas (`hrc_oat_...`) galioja 1 valandą, tada atnaujinkite jį su `refresh_token`. Atnaujinus senas prieigos žetonas iš karto nebegalioja.

```sh
curl -s https://mcp.hrc.lt/oauth/token \
  -d grant_type=authorization_code \
  -d code=CODE \
  -d client_id=CLIENT_ID \
  -d code_verifier=VERIFIER \
  -d redirect_uri=https://app.example.com/oauth/callback
# {"access_token":"hrc_oat_...","token_type":"Bearer","expires_in":3600,
#   "refresh_token":"...","scope":"hrc"}

curl -s https://mcp.hrc.lt/oauth/token \
  -d grant_type=refresh_token \
  -d refresh_token=REFRESH_TOKEN \
  -d client_id=CLIENT_ID
```

## MCP kvietimas

```sh
curl -s https://mcp.hrc.lt/mcp \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
    "params":{"name":"whoami","arguments":{}}}'
```

## Klaidos

- Registracija: `invalid_redirect_uri`, `invalid_client_metadata`.
- Žetonas: `invalid_request`, `invalid_grant`, `invalid_client`, `unsupported_grant_type`, `invalid_target`.
- Nežinomas `client_id` ar neregistruotas `redirect_uri` autorizacijoje parodo klaidos puslapį, be nukreipimo.