Add Authentication RFD

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 `<agent_name> 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
+
+<!-- If there have been major updates to this RFD, you can include the git revisions and a summary of the changes. -->