OAuth 2.0 권한 부여 URL 세션 바인딩

에이전트 호출 - 에이전트 코드는 원래 에이전트 사용자가 자신이 소유한 일부 애플리케이션 또는 리소스에 액세스하려는 경우 GetResourceOauth2Token API를 호출하여 권한 부여 URL을 검색합니다.

권한 부여 URL 생성 - AgentCore Identity는 사용자가 액세스로 이동하여 동의할 수 있는 권한 부여 URL 및 세션 URI를 생성합니다.

액세스 토큰 권한 부여 및 획득 - 사용자가 권한 부여 URL로 이동하여 에이전트가 리소스에 액세스할 수 있도록 동의를 부여합니다. 그런 다음 AgentCore 자격 증명은 권한 부여 요청의 원래 사용자가 포함된 정보와 함께 사용자의 브라우저를 HTTPS 애플리케이션 엔드포인트로 리디렉션합니다. 이 시점에서 HTTPS 애플리케이션 엔드포인트는 원래 에이전트 사용자가 애플리케이션의 현재 로그인한 사용자와 여전히 동일한지 확인합니다. 일치하는 경우 애플리케이션 엔드포인트는 AgentCore 자격 증명이 액세스 토큰을 가져오고 저장할 수 CompleteResourceTokenAuth 있도록를 호출합니다.

에이전트를 다시 호출하여 액세스 토큰 획득 - 애플리케이션이 유효한 응답을 반환하면 에이전트 애플리케이션은 원래 사용자에게 요청된 OAuth2.0 액세스 토큰을 검색할 수 있습니다. 사용자가 일치하지 않으면 애플리케이션이 아무 작업도 수행하지 않거나 시도를 기록합니다.

애플리케이션 URL 생성 - 사용자 대면 브라우저 애플리케이션의 경우 사용자 브라우저에서 액세스할 수 있고 브라우저 리디렉션의 요청을 수락할 수 있는 새 URL을 생성하고 호스팅합니다. 이 페이지는 사용자가 에이전트 세션을 계속할 수 있는 애플리케이션 페이지로 리디렉션하거나 사용자에게 현재 활성 에이전트 세션을 반환하도록 지시하는 몇 가지 기본 웹 페이지를 렌더링해야 합니다. 구현의 후반부에서이 페이지는 현재 사용자의 활성 세션을 검증하는 데 사용되므로이 페이지는 애플리케이션 사용자 세션 데이터에 액세스하고 유지할 수도 있어야 합니다.

예를 들어 애플리케이션은 사용자가와 같은 기본 애플리케이션 페이지에서 에이전트와 상호 작용하도록 https://myagentapp.com/assistant 할 수 있습니다. 이제가 기본 애플리케이션 페이지로 리디렉션https://myagentapp.com/callback할 것과 같은 새 URL을 노출하려고 합니다. /callback 엔드포인트의 실제 코드 로직은 나중에이 가이드를 따를 때 업데이트됩니다.

애플리케이션 URL로 워크로드 자격 증명 업데이트 - ( AgentCore CLI를 통해 로컬에서 테스트하는 경우 건너뛸 수 있음) AgentCore 자격 증명이 리디렉션할 애플리케이션 URL을 생성하고 호스팅한 후에는 애플리케이션 URL이 AllowedResourceOauth2ReturnUrl 로 등록되도록 워크로드 자격 증명을 업데이트합니다. 새 워크로드 자격 증명을 생성하는지 아니면 기존 워크로드 자격 증명을 업데이트하는지에 UpdateWorkloadIdentity 따라 사용된 IAM 자격 증명에 CreateWorkloadIdentity 또는를 호출할 수 있는 권한이 있는지 확인합니다.

샘플 UpdateWorkloadIdentity API 직접 호출:

aws bedrock-agentcore-control update-workload-identity --name GoogleCalendarAgent \
--allowed-resource-oauth2-return-urls https://myagentapp.com/callback

AgentCore 자격 증명에서 OAuth 2.0 자격 증명 공급자 생성 - OAuth 2.0 자격 증명 공급자를 완전히 등록하려면 CreateOauth2CredentialProvider 및 UpdateOauth2CredentialProvider를 호출할 권한이 필요합니다. 다음 단계를 따릅니다.

CompleteResourceTokenAuth를 호출하기 위한 코드 핸들러 추가 - OAuth 2.0 자격 증명 공급자를 생성한 후 애플리케이션 URL 핸들러에서 CompleteResourceTokenAuth API를 호출할 코드와 IAM 권한을 추가합니다. CompleteResourceTokenAuth API를 호출할 때 애플리케이션은 OAuth 2.0 권한 부여 흐름과 관련된 사용자 및 에이전트 애플리케이션을 나타내기 위해 워크로드 액세스 토큰을 생성하는 데 사용된 원래 인바운드 자격 증명 공급자 OAuth 토큰 또는 user_id 문자열을 제공해야 합니다. 이 정보는 사용자 브라우저의 활성 애플리케이션 세션(일반적으로 브라우저 쿠키 또는 브라우저 로컬 스토리지를 통해)에서 가져와야 하며 원격 세션 캐시에서 가져와서는 안 됩니다.

또한 AgentCore 자격 증명에서 생성되는 각 권한 부여 URL은 고유한 세션 URI로 고유하게 식별됩니다. 세션을 의도한 사용자와 바인딩하려면 사용자 식별자와 함께이 세션 URI도 표시해야 합니다.

샘플 애플리케이션 코드:

def _handle_3lo_callback(self, request: Request) -> JSONResponse:
    session_id = request.query_params.get("session_id")

    if not session_id:
        console.print("Missing session_id in OAuth2 3LO callback")
        return JSONResponse(status_code=400, content={"message": "missing session_id query parameter"})

    session_details = validate_session_cookies(request.cookies.get('my-application-cookie'))

    user_id = None
    if oauth2_config:
        user_id = session_details.get(USER_ID)

    if not user_id:
        console.print(f"Missing {USER_ID} in session_details")
        return JSONResponse(status_code=500, content={"message": "Internal Server Error"})

    console.print(f"Handling 3LO callback for workload_user_id={user_id} | session_id={session_id}", soft_wrap=True)

    region = agent_config.aws.region
    if not region:
        console.print("AWS Region not configured")
        return JSONResponse(status_code=500, content={"message": "Internal Server Error"})

    identity_client = IdentityClient(region)
    identity_client.complete_resource_token_auth(
        session_uri=session_id, user_identifier=UserIdIdentifier(user_id=user_id)
    )

    return JSONResponse(status_code=200, content={"message": "OAuth2 3LO flow completed successfully"})

테스트 - 설정을 완료하면 통합을 테스트할 준비가 된 것입니다. 먼저를 호출GetResourceOauth2Token하고 브라우저에서 반환되는 권한 부여 URL로 이동합니다. OAuth 2.0 리소스 공급자에서 권한 부여를 완료하면 브라우저 리디렉션이 애플리케이션 URL로 다시 표시되고 CompleteResourceTokenAuth API가 호출됩니다. 애플리케이션이 유효한 응답을 반환하면 에이전트 애플리케이션은 사용자에 대해 원래 요청된 OAuth 2.0 액세스 토큰을 검색할 수 있습니다. 이러한 토큰은 GetResourceOauth2Token API를 호출하여 가져올 수 있습니다.