Bỏ qua để đến nội dung
@aws/nx-plugin
Blog

DCR Proxy

Trình tạo DCR Proxy tạo ra một proxy OAuth Dynamic Client Registration (DCR) đặt trước Amazon Cognito User Pool.

Các client MCP (như Claude Code, Kiro CLI hoặc MCP Inspector) mong đợi xác thực với một máy chủ ủy quyền OAuth hỗ trợ Dynamic Client Registration và khám phá metadata. Amazon Cognito không hỗ trợ DCR một cách tự nhiên, và App Client secret của nó không bao giờ được phép lộ ra cho một public client. Proxy này bắc cầu khoảng cách đó: nó giữ nguyên luồng Cognito Hosted UI, triển khai DCR, chèn App Client secret ở phía máy chủ trong quá trình trao đổi token, và chuyển tiếp lưu lượng MCP đến máy chủ MCP upstream của bạn.

Cách sử dụng

Phần tiêu đề “Cách sử dụng”

Tạo một DCR proxy

Phần tiêu đề “Tạo một DCR proxy”
  1. Cài đặt Nx Console VSCode Plugin nếu bạn chưa cài đặt
  2. Mở Nx Console trong VSCode
  3. Nhấp Generate (UI) trong phần "Common Nx Commands"
  4. Tìm kiếm @aws/nx-plugin - ts#dcr-proxy
  5. Điền các tham số bắt buộc
    • Nhấp Generate

    Tùy chọn

    Phần tiêu đề “Tùy chọn”
    Tham sốKiểuMặc địnhMô tả
    name stringdcr-proxyTên của DCR proxy của bạn, được sử dụng cho dự án TypeScript handler, tên class construct/module, và thư mục của nó trong common/constructs hoặc common/terraform
    directory stringpackagesThư mục để lưu trữ dự án DCR proxy handler.
    subDirectory string-Thư mục con mà dự án handler được đặt trong đó. Mặc định là tên dự án.
    iac inherit | cdk | terraforminheritNhà cung cấp IaC ưu tiên (cdk hoặc terraform). Mặc định được kế thừa từ lựa chọn ban đầu của bạn.
    preferInstallDependencies booleantrueCó nên cài đặt dependencies sau khi generator chạy hay không. Đặt thành false để hoãn việc cài đặt khi chạy nhiều generator cùng lúc (việc cài đặt vẫn chạy nếu cần thiết để các generator tiếp theo có thể tính toán Nx project graph); cài đặt một lần vào cuối.

    Đầu ra của Trình tạo

    Phần tiêu đề “Đầu ra của Trình tạo”

    Trình tạo tạo ra một dự án TypeScript độc lập chứa các Lambda handler, và cơ sở hạ tầng để triển khai chúng dựa trên iac bạn đã chọn.

    • Thư mục<dcr-proxy-name>
      • Thư mụcsrc/
        • Thư mụchandlers/
          • authorization-server-metadata.ts Phục vụ /.well-known/oauth-authorization-server và /.well-known/openid-configuration
          • protected-resource-metadata.ts Phục vụ /.well-known/oauth-protected-resource
          • register.ts RFC 7591 Dynamic Client Registration
          • authorize.ts Chuyển hướng đến Cognito Hosted UI
          • token.ts Chèn App Client secret và trao đổi token
          • mcp-proxy.ts Proxy các yêu cầu /mcp đến máy chủ MCP upstream

    Các handler được đóng gói độc lập với Rolldown, và cả hai nhà cung cấp IaC đều tham chiếu đến đầu ra bundle kết quả.

    Cơ sở hạ tầng

    Phần tiêu đề “Cơ sở hạ tầng”

    Vì generator này cung cấp infrastructure as code dựa trên iac bạn đã chọn, nó sẽ tạo một dự án trong packages/common bao gồm các CDK constructs hoặc Terraform modules liên quan.

    Dự án infrastructure as code chung được cấu trúc như sau:

    • Thư mụcpackages/common/constructs
      • Thư mụcsrc
        • Thư mụcapp/ Constructs cho infrastructure cụ thể của một dự án/generator
          • …
        • Thư mụccore/ Constructs chung được tái sử dụng bởi các constructs trong app
          • …
        • index.ts Entry point xuất các constructs từ app
      • project.json Các build targets và cấu hình của dự án

    Để triển khai proxy, các tệp sau được tạo ra:

    • Thư mụcpackages/common/constructs/src
      • Thư mụcapp
        • Thư mụcdcr-proxies
          • Thư mục<dcr-proxy-name>
            • <dcr-proxy-name>.ts CDK construct triển khai proxy

    Cơ sở hạ tầng cung cấp một API Gateway HTTP API với các route sau:

    RouteMô tả
    GET /.well-known/oauth-protected-resourceProtected resource metadata
    GET /.well-known/oauth-authorization-serverAuthorization server metadata
    GET /.well-known/openid-configurationOpenID configuration (được phục vụ bởi authorization server metadata handler)
    POST /registerDynamic Client Registration
    GET /authorizeAuthorization (chuyển hướng đến Cognito Hosted UI)
    POST /oauth/tokenToken exchange (chèn App Client secret)
    ANY /mcpProxy đến máy chủ MCP upstream

    Chỉ có token handler được cấp quyền truy cập đọc vào Cognito App Client secret trong Secrets Manager.

    Triển khai DCR Proxy

    Phần tiêu đề “Triển khai DCR Proxy”

    Proxy không tạo các tài nguyên Cognito hoặc máy chủ MCP của bạn. Thay vào đó, bạn chèn các định danh của các tài nguyên được quản lý ở nơi khác (dù được tạo bởi plugin này hay được cung cấp riêng biệt), giữ cho proxy tách rời khỏi cách các tài nguyên đó được cung cấp.

    Bạn cung cấp:

    • Cognito User Pool id và App Client id
    • ARN của một Secrets Manager secret chứa App Client secret. Token handler đọc điều này tại runtime; giá trị không bao giờ được lộ ra cho client.
    • URL cơ sở của Cognito Hosted UI domain
    • URL đầy đủ của máy chủ MCP upstream của bạn

    Khởi tạo construct được tạo ra trong stack của bạn, truyền các thuộc tính bắt buộc:

    import { DcrProxy } from ':my-scope/common-constructs';
    

    new DcrProxy(this, 'DcrProxy', {
      userPoolId: userPool.userPoolId,
      userPoolClientId: userPoolClient.userPoolClientId,
      cognitoClientSecretArn: clientSecret.secretArn,
      cognitoHostedUiBase: userPoolDomain.baseUrl(),
      upstreamUrl: 'https://my-agentcore-runtime-url/mcp',
    });

    Construct này hiển thị các proxy endpoint (proxyUrl, mcpUrl, metadataUrl, tokenEndpoint, registrationEndpoint) dưới dạng các thuộc tính readonly.

    Đặt trước một Máy chủ MCP

    Phần tiêu đề “Đặt trước một Máy chủ MCP”

    Để đặt proxy trước một máy chủ MCP được tạo bằng trình tạo ts#mcp-server (hoặc py#mcp-server) sử dụng --auth cognito, truyền cùng User Pool và App Client cho cả máy chủ MCP và proxy, và sử dụng invocationUrl của construct máy chủ MCP làm upstreamUrl của proxy.

    import {
      DcrProxy,
      MyProjectMcpServer,
      UserIdentity,
    } from ':my-scope/common-constructs';
    import { OAuthScope } from 'aws-cdk-lib/aws-cognito';
    import * as secretsmanager from 'aws-cdk-lib/aws-secretsmanager';
    

    const identity = new UserIdentity(this, 'Identity');
    

    // Một confidential App Client mà proxy sử dụng cho trao đổi token. Đăng ký các
    // callback URL mà client của bạn sử dụng (xem bên dưới).
    const proxyClient = identity.userPool.addClient('DcrProxyClient', {
      generateSecret: true,
      oAuth: {
        flows: { authorizationCodeGrant: true },
        scopes: [OAuthScope.OPENID, OAuthScope.EMAIL, OAuthScope.PROFILE],
        callbackUrls: [
          'http://localhost:41100/callback',
          // Callback được sử dụng bởi Claude Desktop
          'https://claude.ai/api/mcp/auth_callback',
        ],
      },
    });
    

    // Lưu trữ App Client secret trong Secrets Manager để token handler đọc
    const clientSecret = new secretsmanager.Secret(this, 'ClientSecret', {
      secretStringValue: proxyClient.userPoolClientSecret,
    });
    

    // Máy chủ MCP, ủy quyền các JWT được phát hành cho cùng App Client
    const mcpServer = new MyProjectMcpServer(this, 'MyProjectMcpServer', {
      identity: {
        userPool: identity.userPool,
        userPoolClient: proxyClient,
      },
    });
    

    new DcrProxy(this, 'DcrProxy', {
      userPoolId: identity.userPool.userPoolId,
      userPoolClientId: proxyClient.userPoolClientId,
      cognitoClientSecretArn: clientSecret.secretArn,
      cognitoHostedUiBase: identity.userPoolDomain.baseUrl(),
      // Sử dụng invocation URL của construct máy chủ MCP thay vì hardcode nó
      upstreamUrl: mcpServer.invocationUrl,
    });

    Đặt trước một AgentCore Gateway

    Phần tiêu đề “Đặt trước một AgentCore Gateway”

    Để đặt proxy trước một AgentCore Gateway được tạo bằng trình tạo agentcore-gateway sử dụng --auth cognito, truyền cùng User Pool và App Client cho cả gateway và proxy, và sử dụng gatewayUrl của construct gateway làm upstreamUrl của proxy.

    import {
      DcrProxy,
      MyGateway,
      UserIdentity,
    } from ':my-scope/common-constructs';
    import { OAuthScope } from 'aws-cdk-lib/aws-cognito';
    import * as secretsmanager from 'aws-cdk-lib/aws-secretsmanager';
    

    const identity = new UserIdentity(this, 'Identity');
    

    // Một confidential App Client mà proxy sử dụng cho trao đổi token. Đăng ký các
    // callback URL mà client của bạn sử dụng (xem bên dưới).
    const proxyClient = identity.userPool.addClient('DcrProxyClient', {
      generateSecret: true,
      oAuth: {
        flows: { authorizationCodeGrant: true },
        scopes: [OAuthScope.OPENID, OAuthScope.EMAIL, OAuthScope.PROFILE],
        callbackUrls: [
          'http://localhost:41100/callback',
          // Callback được sử dụng bởi Claude Desktop
          'https://claude.ai/api/mcp/auth_callback',
        ],
      },
    });
    

    // Lưu trữ App Client secret trong Secrets Manager để token handler đọc
    const clientSecret = new secretsmanager.Secret(this, 'ClientSecret', {
      secretStringValue: proxyClient.userPoolClientSecret,
    });
    

    // Gateway, ủy quyền các JWT được phát hành cho cùng App Client
    const gateway = new MyGateway(this, 'MyGateway', {
      identity: {
        userPool: identity.userPool,
        userPoolClient: proxyClient,
      },
    });
    

    new DcrProxy(this, 'DcrProxy', {
      userPoolId: identity.userPool.userPoolId,
      userPoolClientId: proxyClient.userPoolClientId,
      cognitoClientSecretArn: clientSecret.secretArn,
      cognitoHostedUiBase: identity.userPoolDomain.baseUrl(),
      // Sử dụng URL của construct gateway thay vì hardcode nó
      upstreamUrl: gateway.gateway.gatewayUrl,
    });

    Cho phép Client Redirect URI

    Phần tiêu đề “Cho phép Client Redirect URI”

    Vì proxy triển khai Dynamic Client Registration một cách ảo — không có Cognito App Client riêng cho từng client — mọi client MCP đều xác thực thông qua App Client duy nhất mà bạn truyền cho proxy. Trong quá trình luồng OAuth, proxy chuyển tiếp redirect_uri của client đến Cognito Hosted UI không thay đổi, vì vậy Cognito thực hiện kiểm tra có thẩm quyền: callback phải được đăng ký là một callback URL trên App Client đó, nếu không Cognito sẽ từ chối đăng nhập.

    Đây là một tác dụng phụ của thiết kế DCR ảo. Một client có thể đăng ký bất kỳ redirect_uri nào với proxy, nhưng đăng nhập chỉ thành công nếu URL chính xác đó là một trong các callback URL của App Client. Cognito khớp các callback URL chính xác, bao gồm cả cổng, vì vậy các client lắng nghe trên một cổng tạm thời ngẫu nhiên không thể được bao phủ bởi một wildcard — bạn phải ghim mỗi client vào một callback URL cố định và đăng ký URL chính xác đó trên App Client.

    Thêm các callback URL mà client của bạn sử dụng khi bạn tạo App Client:

    const userPoolClient = userPool.addClient('DcrProxyClient', {
      generateSecret: true,
      oAuth: {
        flows: { authorizationCodeGrant: true },
        callbackUrls: [
          // Client cục bộ: ghim vào một cổng cố định, không phổ biến thay vì một cổng mặc định
          'http://localhost:41100/callback',
          // Callback được sử dụng bởi Claude Desktop
          'https://claude.ai/api/mcp/auth_callback',
        ],
      },
    });

    Sử dụng Máy chủ MCP được Proxy

    Phần tiêu đề “Sử dụng Máy chủ MCP được Proxy”

    Proxy cho phép các client MCP xác thực với Cognito User Pool của bạn mà không cần bất kỳ cấu hình cụ thể nào cho client ngoài URL proxy. Khi một client kết nối với endpoint /mcp, nó khám phá metadata OAuth (thông qua /.well-known/oauth-protected-resource và /.well-known/oauth-authorization-server), tự động đăng ký chính nó, và dẫn người dùng qua đăng nhập Cognito Hosted UI. Proxy chèn App Client secret trong quá trình trao đổi token, vì vậy client không bao giờ cần nó.

    Để kết nối một client, hướng nó đến mcpUrl của proxy (tức là <proxyUrl>/mcp). Các ví dụ bên dưới giả định proxy của bạn được triển khai tại https://my-proxy.example.com.

    Claude Code

    Phần tiêu đề “Claude Code”

    Thêm máy chủ được proxy bằng lệnh claude mcp add, sử dụng HTTP transport. Theo mặc định Claude Code lắng nghe trên một cổng callback ngẫu nhiên; truyền --callback-port để ghim nó vào cổng được đăng ký trên App Client của bạn (41100 trong các ví dụ trên). Claude Code luôn sử dụng đường dẫn /callback, vì vậy redirect URI kết quả là http://localhost:41100/callback:

    Terminal window
    claude mcp add --transport http --callback-port 41100 my-proxied-server https://my-proxy.example.com/mcp

    Khi bạn lần đầu tiên gọi một công cụ từ máy chủ, Claude Code mở Cognito Hosted UI để xác thực trước khi yêu cầu được proxy upstream.

    Kiro CLI

    Phần tiêu đề “Kiro CLI”

    Thêm máy chủ vào cấu hình MCP Kiro CLI của bạn, sử dụng HTTP transport. Không có oauth.redirectUri rõ ràng, Kiro chọn một cổng callback ngẫu nhiên; đặt nó thành URL được đăng ký trên App Client của bạn để cổng và đường dẫn khớp chính xác:

    {
      "mcpServers": {
        "my-proxied-server": {
          "type": "http",
          "url": "https://my-proxy.example.com/mcp",
          "oauth": {
            "redirectUri": "http://localhost:41100/callback"
          }
        }
      }
    }

    Kiro CLI kích hoạt đăng nhập Cognito Hosted UI khi sử dụng lần đầu và quản lý các token kết quả cho các yêu cầu tiếp theo.

    Tái sử dụng UserIdentity User Pool

    Phần tiêu đề “Tái sử dụng UserIdentity User Pool”

    Nếu bạn đã có User Pool từ trình tạo ts#website#auth (construct UserIdentity), bạn có thể đặt proxy trước một máy chủ MCP cho cùng những người dùng đăng nhập vào trang web của bạn. Tái sử dụng userPool của nó, nhưng thêm một App Client riêng biệt cho proxy: client của trang web là một public client không có secret, trong khi DCR proxy yêu cầu một confidential client (generateSecret: true) mà secret của nó được token handler chèn vào trong quá trình trao đổi token.

    UserIdentity cấu hình User Pool domain với Managed Login (phiên bản 2). Managed Login yêu cầu một branding style cho mỗi App Client, vì vậy bạn phải tạo một cái cho proxy client mới — nếu không trang đăng nhập hosted của nó sẽ trả về 403.

    import {
      DcrProxy,
      MyProjectMcpServer,
      UserIdentity,
    } from ':my-scope/common-constructs';
    import { OAuthScope, CfnManagedLoginBranding } from 'aws-cdk-lib/aws-cognito';
    import * as secretsmanager from 'aws-cdk-lib/aws-secretsmanager';
    

    // User pool được tạo bởi ts#website#auth cho người dùng trang web của bạn
    const identity = new UserIdentity(this, 'Identity');
    

    // Một confidential App Client trên CÙNG user pool cho DCR proxy
    const proxyClient = identity.userPool.addClient('DcrProxyClient', {
      generateSecret: true,
      oAuth: {
        flows: { authorizationCodeGrant: true },
        scopes: [OAuthScope.OPENID, OAuthScope.EMAIL, OAuthScope.PROFILE],
        callbackUrls: ['http://localhost:41100/callback'],
      },
    });
    

    // Managed Login cần một branding style cho client mới
    new CfnManagedLoginBranding(this, 'DcrProxyClientBranding', {
      userPoolId: identity.userPool.userPoolId,
      clientId: proxyClient.userPoolClientId,
      useCognitoProvidedValues: true,
    });
    

    const clientSecret = new secretsmanager.Secret(this, 'ClientSecret', {
      secretStringValue: proxyClient.userPoolClientSecret,
    });
    

    const mcpServer = new MyProjectMcpServer(this, 'MyProjectMcpServer', {
      identity: {
        userPool: identity.userPool,
        userPoolClient: proxyClient,
      },
    });
    

    new DcrProxy(this, 'DcrProxy', {
      userPoolId: identity.userPool.userPoolId,
      userPoolClientId: proxyClient.userPoolClientId,
      cognitoClientSecretArn: clientSecret.secretArn,
      // Construct UserIdentity luôn tạo một domain
      cognitoHostedUiBase: identity.userPoolDomain.baseUrl(),
      upstreamUrl: mcpServer.invocationUrl,
    });