a2aproject / a2aproject/a2a-python

[Feat]: Improve client auth handling

Đang mở
#445 6 bình luận 0 reaction 0 người được giao Xem trên GitHub
Ngôn ngữ chính
Python
Star
2.1k
Fork
495
Merge trung bình
4 ngày 17 giờ
Pull request đã merge (30 ngày)
12

Mô tả

### Is your feature request related to a problem? Please describe.

Agents declare their authentication requirements via the [`security_schemes` and `security`](https://github.com/a2aproject/a2a-python/blob/main/src/a2a/types.py#L1807) fields in the AgentCard. Skills can also [declare required security](https://github.com/a2aproject/a2a-python/blob/main/src/a2a/types.py#L167).

Clients are responsible for understanding how to fulfill these authentication requirements. As of now, this is effectively left to the developer to roll this code themselves. However, in some cases, the SecuritySchemes object contains enough information to programmatically determine how to fulfill the auth requirements. We should provide a base implementation for this that handles common use cases (such as OAuth).

The [`AuthInterceptor` class](https://github.com/a2aproject/a2a-python/blob/main/src/a2a/client/auth/interceptor.py) class is a start, but we're missing pieces for easily using it. `AuthInterceptor` handles the work of placing the credential in the right HTTP header (if known). It's still up to the developer to set up a `CredentialService` and pass the `AuthInterceptor` in the right spots. We can do better.

### Describe the solution you'd like

Many auth schemes require, at minimum, some configuration in order to fulfill. For OAuth, if you want to generate access tokens on demand, you need a Client ID and Secret. For API Key authentication, you need the key to be sent. For mTLS, you need a client certificate to use. Once you have this, however, it's generally possible to handle the authentication with common code.

My idea for the interface is essentially:

1. Load up an object with a bunch of authentication configurations.
2. Provide this object to the [`ClientFactory`](https://github.com/a2aproject/a2a-python/blob/main/src/a2a/client/client_factory.py), perhaps via ClientConfig.
3. When a client is constructed, analyze the SecuritySchemes + security in the AgentCard to determine whether we have sufficient information to meet the authentication requirements for the agent.
4. If so, compose a credential handling object that wraps the logic needed to fulfill the authentication requirements and provide this to the client.
5. If not, we could raise a warning that we don't know how to fulfill the authentication for the agent. You can ignore this warning and continue, or treat this as an error and be unable to use the client.
6. When interacting with the client, authentication is handled as transparently as possible. There are cases where the code using the client needs to provide additional information, such as for OAuth Authorization Code access tokens.

I have not fully investigated how feasible this is or what the pieces I'm missing are. Authentication code is generally pretty complex, so for complicated cases I expect we'll need a lot of thought for creating an appropriate interface.

Here's a rough sketch of how the code could look:
```py
client_credential_manager = ClientCredentialManager()
# Methods for configuring well-known authentication types.
client_credential_manager.add_oauth_client(
id="google",
token_url="https://oauth2.googleapis.com/token",
authorization_url="https://accounts.google.com/o/oauth2/v2/auth",
client_config=(MY_CLIENT_ID, MY_CLIENT_SECRET),
use_authorization_code_flow=True,
)
client_credential_manager.add_mtls(
id="example-com-mtls",
certificate=MY_CLIENT_CERTIFICATE,
)
client_credential_manager.add_api_key(
id="cool-api-key",
host_domain="example.com",
api_key=MY_API_KEY,
)
# But generalized underpinnings to be extensible.
# Something like AuthScheme.matches(SecurityScheme) and AuthScheme.get_handler(AgentCard, SecurityScheme)
custom_auth_scheme = MyAuthScheme()
client_credential_manager.add_handler(
id="my-custom-auth",
scheme=custom_auth_scheme
)

client_config = ClientConfig(
# ... Normal config stuff,
credential_manager=client_credential_manager
)
client_factory = ClientFactory(client_config)
```

And using the client should be as transparent as possible:
```py
some_agent_card = AgentCard(
url="https://agents.example.com/magic",
# ...
security_schemes = {
"google_oauth": OAuth2SecurityScheme(
flows=OAuthFlows(
authorization_code=AuthorizationCodeOAuthFlow(
authorization_url="https://accounts.google.com/o/oauth2/v2/auth",
# ...
)
)
),
},
security=[{"google_oauth": []}, {}],
)

# Credential manager helps match and fulfill auth schemes.
client = client_factory.create(some_agent_card)
# Yay, it just works!
client.send_message(new_text_message("Hello!"))
```

Some additional thoughts:

- We should handle both patterns of statically configured credentials and dynamically sourced credentials. Users may want to use request-level context to choose what credentials are provided on a request.
- However, we should be able to know whether we have any chance at all of fulfilling auth requirements at client construction time.
- OAuth is a really big use case, so we should build out as much support for this as we can. This should include being able to retrieve access tokens stored in a secret manager or performing an authorization flow on demand.
- Our underlying abstractions should be pretty flexible -- be able to match an auth scheme against a SecurityScheme, and some kind of handler that alters outgoing requests to attach credentials. This gets a little complicated with our various transports -- JSON-RPC and REST use HTTP headers, gRPC uses Metadata. Something more esoteric might not have an equivalent side-channel, so there might be some interaction with `ClientTransport` implementations.

### Describe alternatives you've considered

We currently have some initial support for `ClientCallInterceptor`s. This was built with auth in mind, but hasn't been integrated as smoothly as we'd like and it isn't clear how it works with all transports. We may use `ClientCallInterceptors` and `ClientCallContext` under the hood, but it should be largely transparent to users.

There's some initial auth support in src/a2a/client/auth, but it's not as extensive as what I'm proposing. It's the right start, but needs to be cleaned up and better structured.

### Additional context

_No response_

### Code of Conduct

- [x] I agree to follow this project's Code of Conduct

Hướng dẫn đóng góp

Mở hướng dẫn đóng góp

Hướng nghiên cứu

Bắt đầu bằng cách đọc lớp AuthInterceptor hiện có trong src/a2a/client/auth/interceptor.py và ClientFactory trong src/a2a/client/client_factory.py. Tìm hiểu cách các lược đồ bảo mật của AgentCard được định nghĩa trong src/a2a/types.py. Mục tiêu là thiết kế một ClientCredentialManager có thể đối sánh các lược đồ bảo mật và tự động đính kèm thông tin xác thực. Kiểm tra cách các transport khác nhau (HTTP, gRPC) xử lý việc xác thực. Một proof of concept sẽ bao gồm việc mở rộng ClientConfig để chấp nhận một credential manager và sửa đổi luồng tạo client để inject các interceptor phù hợp.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Đánh giá

Công nghệ
python
Lĩnh vực
api, authentication, backend
Loại issue
Tính năng
Độ khó
4/5
Thời gian dự kiến
3-5 ngày
Mức độ hoạt động
Ít trao đổi
Độ rõ ràng
Khá rõ ràng
Mức phù hợp với người mới
45/100

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.