diff --git a/docs/rfds/auth.mdx b/docs/rfds/auth.mdx new file mode 100644 index 0000000..24306a3 --- /dev/null +++ b/docs/rfds/auth.mdx @@ -0,0 +1,167 @@ +--- +title: "AUTHENTICATION" +--- + +Author(s): [anna239](https://github.com/anna239) + +## Elevator pitch + +> What are you proposing to change? + +I suggest adding more information about auth methods that agent supports, which will allow clients to draw more appropriate UI. + +## Status quo + +> How do things work today and what problems does this cause? Why would we change things? + +Agents have different ways of authenticating users: env vars with api keys, running a command like ` login`, some just open a browser and use oauth. +[AuthMethod](https://agentclientprotocol.com/protocol/schema#authmethod) does not really tell the client what should be done to authenticate. This means we can't show the user a control for entering key if an aggent support auth through env var. + +## What we propose to do about it + +> What are you proposing to improve the situation? + +We can add different types of AuthMethods, so that clients can show some UI for them. For example, this auth method + +```json +{ + "id": "123", + "name": "OpenAI api key", + "description": "Provide your key", + "type": "envVar", + "varName": "OPEN_AI_KEY" +} +``` + +would allow client to prompt user to enter a key, then client can provide this key to an agent via `OPEN_AI_KEY` env variable. + +## Shiny future + +> How will things will play out once this feature exists? + +It will be easier for end-users to start using an agent from inside the IDE as auth process will be more straightforward + +## Implementation details and plan + +> Tell me more about your implementation. What is your detailed implementation plan? + +I suggest adding following auth types: + +1. Env variable + +A user can enter a key and a client will pass it to the agent as an env variable + +```json +{ + "id": "123", + "name": "OpenAI api key", + "description": "Provide your key", + "type": "envVar", + "varName": "OPEN_AI_KEY", + "link": "OPTIONAL link to a page where user can get their key" +} +``` + +2. Start argument + +A user can enter a key, and a client will pass it to the agent as a start parameter + +```json +{ + "id": "123", + "name": "OpenAI api key", + "description": "Provide your key", + "type": "startParam", + "paramName": "OPEN_AI_KEY", + "link": "OPTIONAL link to a page where user can get their key" +} +``` + +3. Agent auth + +Same as what there is now – agent handles the auth itself, this should be a default type if no type is provided for backward compatibility + +```json +{ + "id": "123", + "name": "Agent", + "description": "Authenticate through agent", + "type": "agent" +} +``` + +To better handle oauth scenarios, we can add a mechanism like (MCP-elicitation)[https://modelcontextprotocol.io/specification/2025-11-25/client/elicitation] +User sends authenticate request with method id; then server calls an `elicitation/create` method on a client, that includes a link to an oauth provider and `authenticateRequestId` so that we can clearly link the request with the auth request. + +```json +{ + "jsonrpc": "2.0", + "id": 3, + "method": "elicitation/create", + "params": { + "authenticateRequestId": "123", + "url": "https://mcp.example.com/ui/set_api_key", + "message": "Please provide your API key to continue." + } +} +``` + +Client then allows user to open a browser and authenticate themselves. Agent then responds to an elicitation request with a key: + +```json +{ + "jsonrpc": "2.0", + "id": 3, + "result": { + "action": "accept" + } +} +``` + +and then responds to the original `authenticate` request. + +4. Provided key + +User can enter the key and a client should pass it to the agent via [AuthenticateRequest](https://agentclientprotocol.com/protocol/schema#authenticaterequest) + +```json +{ + "id": "123", + "name": "OpenAI api key", + "description": "Provide your key", + "type": "enterKey", + "link": "OPTIONAL link to a page where user can get their key" +} +``` + +in this case [AuthenticateRequest](https://agentclientprotocol.com/protocol/schema#authenticaterequest) should also be updated. I suggest adding an optional authParams property + +```json +{ + "methodId": "123", + "authParams": { + "key": "...." + } +} +``` + +This approach also requires adding a new `elicitation` client capability. If the client does not support this capability, agent MUST NOT return such an authMethod in the `initialize` response. + +### AuthErrors + +It might be useful to include a list of AuthMethod ids to the AUTH_REQUIRED JsonRpc error. Why do we need this if they're already shared during `initialize`: +All supported auth methods are shared during `initialize`. When user starts a session, they've already selected a model, which can narrow down a list of options. + +## Frequently asked questions + +> What questions have arisen over the course of authoring this document or during subsequent discussions? + +### What alternative approaches did you consider, and why did you settle on this one? + +An alternative approach would be to include this information to an agent's declaration making it more static, see [Registry RFD](https://github.com/agentclientprotocol/agent-client-protocol/pull/289) + +There is also an alternative to adding a separate `elicitation` capability, which is to create a separate auth type for this. Then the client can decide themselves if they support it or not. + +## Revision history + +