Cách khắc phục cấu hình OpenID cho các MCP Connector
Tuần này tôi đã mất quá nhiều thời gian để sửa một MCP connector từ xa.
Connector này liên tục không tìm thấy máy chủ OAuth của tôi. Máy chủ vẫn hoạt động bình thường. Vấn đề chỉ nằm ở một route bị thiếu và một lệnh redirect.
Khi bạn sử dụng OAuth với MCP, bạn kỳ vọng các tài liệu khám phá (discovery documents) sẽ hoạt động. Hầu hết các công cụ đều tìm kiếm hai đường dẫn này:
- /.well-known/oauth-authorization-server
- /.well-known/oauth-protected-resource
Chúng cho client biết nơi tìm các endpoint ủy quyền (authorization) và token.
Vấn đề là nhiều client không tìm kiếm các đường dẫn cụ thể đó. Thay vào đó, chúng tìm kiếm /.well-known/openid-configuration.
Đây là một đường dẫn OpenID Connect. Nó là một spec khác, nhưng lại nằm cùng một vị trí. Package của tôi không đăng ký đường dẫn này vì nó tuân theo spec OAuth chứ không phải spec OIDC.
Client gõ cửa một cánh cửa không tồn tại. Nó nhận lỗi 404 và dừng lại.
Tôi có hai lựa chọn:
Sử dụng redirect qua reverse-proxy trong Nginx. Đây là một cách sửa lỗi "lười biếng". Nó đẩy logic của bạn ra khỏi mã nguồn và đưa vào hạ tầng. Cách này khó kiểm thử và dễ gây lỗi trong quá trình triển khai (deployment).
Sửa lỗi ngay trong ứng dụng. Đây là cách tốt hơn.
Tôi chọn cách làm cho ứng dụng phản hồi yêu cầu thăm dò đó. Tôi đã tạo một alias để redirect đường dẫn OpenID sang đường dẫn ủy quyền OAuth.
Tôi đã sử dụng mã 308 Permanent Redirect.
Một lệnh redirect 302 có thể chuyển một yêu cầu POST thành một yêu cầu GET. Trong khi đó, redirect 308 rất nghiêm ngặt. Nó yêu cầu client chuyển đến URL mới nhưng vẫn giữ nguyên method và body. Đây là cách chính xác để xử lý việc di chuyển vĩnh viễn.
Tôi cũng đặt tính năng này sau một configuration flag. Điều này cho phép người dùng tắt nó đi nếu họ tự chạy OIDC discovery riêng.
Bằng cách thực hiện việc này trong mã nguồn, tôi có thể viết các bài kiểm thử (tests):
- Một test kiểm tra xem việc redirect có diễn ra chính xác hay không.
- Một test thực hiện theo redirect để đảm bảo metadata là hợp lệ.
Điều này đảm bảo rằng nếu cấu trúc metadata thay đổi, các bài test của tôi sẽ thất bại ngay lập tức. Tôi sẽ phát hiện lỗi trong pipeline của mình thay vì đợi đến khi người dùng không thể kết nối mới biết.
Trong thực tế, các spec thường có sự khác biệt. Ngay cả khi hai tiêu chuẩn có cùng mục tiêu, các client vẫn sẽ chọn các đường dẫn khác nhau. Với tư cách là một nhà phát triển máy chủ, bạn nên "mở cửa" cho cả hai.
Hãy dẫn chúng về cùng một nơi, sử dụng mã redirect chính xác và củng cố bằng các bài kiểm thử.
Alias cấu hình OpenID .well-known giúp các MCP connector hoạt động trơn tru
Bạn đã bao giờ tự hỏi tại sao một số tích hợp lại hoạt động mượt mà trong khi những cái khác lại đòi hỏi cấu hình thủ công vô tận không?
Bí mật nằm ở một tiêu chuẩn nhỏ nhưng cực kỳ mạnh mẽ: endpoint .well-known/openid-configuration.
Phép màu của sự khám phá
Trong thế giới của OpenID Connect (OIDC) và OAuth 2.0, việc trao đổi thông tin giữa các bên (như ứng dụng khách và nhà cung cấp danh tính) là vô cùng quan trọng. Thay vì yêu cầu người dùng hoặc nhà phát triển phải nhập thủ công từng chi tiết kỹ thuật một (như URL endpoint đăng nhập, URL endpoint token, các phạm vi (scopes) được hỗ trợ, v.v.), chúng ta có một cơ chế khám phá tự động.
Endpoint .well-known/openid-configuration đóng vai trò như một "bản đồ" hoặc "tài liệu khám phá". Một khi hệ thống đã biết URL issuer, nó chỉ cần thêm .well-known/openid-configuration vào sau đó để lấy được toàn bộ metadata cần thiết.
Tại sao điều này lại quan trọng đối với MCP
Model Context Protocol (MCP) đang mở ra một kỷ nguyên mới trong việc kết nối các Mô hình Ngôn ngữ Lớn (LLM) với các nguồn dữ liệu và công cụ bên ngoài. Các MCP connector đóng vai trò là cầu nối giữa LLM và các dịch vụ này.
Khi một MCP connector cần truy cập vào một dịch vụ được bảo vệ bởi OIDC, thách thức lớn nhất là: Làm thế nào để connector biết cách xác thực một cách an toàn và chính xác mà không cần cấu hình thủ công quá nhiều?
Bằng cách tận dụng alias .well-known/openid-configuration, các MCP connector có thể:
- Tự động khám phá các endpoint: Thay vì phải cấu hình cứng (hardcode) các URL như
/authorizehoặc/token, connector chỉ cần URL của issuer. - Xác minh cấu hình: Nó có thể kiểm tra ngay lập tức các tham số được hỗ trợ, các thuật toán ký (signing algorithms) và các phạm vi (scopes) được cho phép.
- Giảm thiểu lỗi cấu hình: Tự động hóa quá trình này giúp loại bỏ các lỗi do nhập sai URL hoặc thiếu các tham số kỹ thuật.
Kết luận
Sự đơn giản của .well-known/openid-configuration là minh chứng cho sức mạnh của các tiêu chuẩn mở. Bằng cách tuân thủ các quy ước này, các nhà phát triển MCP có thể xây dựng các connector theo kiểu "cắm là chạy" (plug-and-play), giúp việc tích hợp các dịch vụ bảo mật trở nên dễ dàng hơn bao giờ hết.
Nếu bạn đang xây dựng các MCP connector, hãy đảm bảo tận dụng khả năng khám phá này để mang lại trải nghiệm mượt mà nhất có thể cho người dùng của mình.