Liaison de session d'URL d'autorisation OAuth 2.0

Invoquer un agent  : votre code d'agent invoque GetResourceOauth2Token l'API pour récupérer une URL d'autorisation, lorsqu'un utilisateur de l'agent d'origine souhaite accéder à une application ou à une ressource qui he/she en est propriétaire.

Générer une URL d'autorisation — AgentCore Identity génère une URL d'autorisation et un URI de session auxquels l'utilisateur peut accéder et autoriser l'accès.

Autoriser et obtenir un jeton d'accès — L'utilisateur accède à l'URL d'autorisation et autorise votre agent à accéder à la his/her ressource. AgentCore Identity redirige ensuite le navigateur de l'utilisateur vers le point de terminaison de votre application HTTPS avec des informations contenant l'utilisateur à l'origine de la demande d'autorisation. À ce stade, le point de terminaison de votre application HTTPS détermine si l'utilisateur de l'agent d'origine est toujours le même que l'utilisateur actuellement connecté de votre application. S'ils correspondent, le point de terminaison de votre application les invoque CompleteResourceTokenAuth pour qu' AgentCore Identity puisse récupérer et stocker le jeton d'accès.

Re-invoke agent pour obtenir le jeton d'accès — Une fois que l'application aura renvoyé une réponse valide, votre application d'agent sera en mesure de récupérer les jetons d' OAuth2.0 accès initialement demandés pour l'utilisateur. Si les utilisateurs ne correspondent pas, votre application ne fait simplement rien ou enregistre la tentative.

Création d'une URL d'application — Pour votre application de navigation orientée utilisateur, créez et hébergez une nouvelle URL accessible depuis le navigateur de l'utilisateur et capable d'accepter les demandes provenant de redirections de navigateur. Cette page doit soit rediriger vers une page d'application permettant à votre utilisateur de poursuivre sa session d'agent, SOIT afficher une page Web de base demandant à vos utilisateurs de rétablir leur session d'agent actuellement active. Dans les étapes ultérieures de la mise en œuvre, cette page est utilisée pour valider la session active de l'utilisateur actuel. Elle devrait donc également être en mesure d'accéder aux données de session utilisateur de votre application et de les gérer.

Par exemple, les utilisateurs de votre application peuvent interagir avec un agent sur une page d'application principale, par exemplehttps://myagentapp.com/assistant. Vous voudrez exposer une nouvelle URL comme celle-ci pour l'instant https://myagentapp.com/callback qui redirigera vers la page principale de l'application. La logique de code réelle de votre /callback terminal sera mise à jour ultérieurement lorsque vous suivrez ce guide.

Mettre à jour l'identité de la charge de travail avec l'URL de l'application — (Peut être ignoré si vous testez localement via la AgentCore CLI) Une fois que vous avez créé et hébergé une URL d'application vers laquelle AgentCore l'identité peut être redirigée, mettez à jour l'identité de votre charge de travail afin que l'URL de l'application soit enregistrée en tant AllowedResourceOauth2ReturnUrl que. Assurez-vous que les informations d'identification IAM utilisées sont autorisées à effectuer des appelsCreateWorkloadIdentity, que vous UpdateWorkloadIdentity créiez une nouvelle identité de charge de travail ou que vous mettiez à jour une identité existante.

Exemple d'appel d'UpdateWorkloadIdentityAPI :

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

Créer un fournisseur d'informations d'identification OAuth 2.0 dans AgentCore Identity — Pour enregistrer complètement le fournisseur d'informations d'identification OAuth 2.0, vous devez être autorisé à appeler et. CreateOauth2CredentialProvider UpdateOauth2CredentialProvider Procédez comme suit :

Ajouter un gestionnaire de code pour les appels CompleteResourceTokenAuth — Une fois que vous avez créé votre fournisseur d'informations d'identification OAuth 2.0, ajoutez du code et les autorisations IAM pour appeler l'CompleteResourceTokenAuthAPI dans le gestionnaire d'URL de votre application. Lorsque vous appelez l'CompleteResourceTokenAuthAPI, votre application doit présenter le jeton ou la user_id chaîne OAuth du fournisseur d'identité entrant d'origine qui a été utilisé pour générer le jeton d'accès à la charge de travail afin de représenter l'utilisateur et l'application agent impliqués dans le flux d'autorisation OAuth 2.0. Ces informations doivent être extraites de la session d'application active sur le navigateur de l'utilisateur (généralement via un cookie de navigateur ou dans la mémoire locale du navigateur) et NE doivent PAS être extraites du cache d'une session distante.

En outre, chaque URL d'autorisation générée par AgentCore Identity est identifiée de manière unique par son propre URI de session. Cet URI de session doit également être présenté à côté de l'identifiant de l'utilisateur pour lier la session à l'utilisateur prévu.

Exemple de code d'application :

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"})

Test  : une fois la configuration terminée, vous êtes prêt à tester l'intégration. Commencez par appeler GetResourceOauth2Token et, dans votre navigateur, accédez à l'URL d'autorisation qui vous est renvoyée. Après avoir terminé l'autorisation auprès du fournisseur de ressources OAuth 2.0, vous devriez voir le navigateur rediriger vers l'URL de votre application et invoquer l'API. CompleteResourceTokenAuth Une fois que l'application aura renvoyé une réponse valide, votre application d'agent sera en mesure de récupérer les jetons d'accès OAuth 2.0 initialement demandés pour l'utilisateur. Ces jetons peuvent être récupérés en appelant l'GetResourceOauth2TokenAPI.