Liaison de session avec URL d'autorisation OAuth 2.0

Invoquer l'agent — Le code de votre 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 en he/she 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é à votre application. S'ils correspondent, le point de terminaison de votre application CompleteResourceTokenAuth est invoqué afin qu' AgentCore Identity puisse récupérer et stocker le jeton d'accès.

Re-invoke agent pour obtenir un jeton d'accès — Une fois que l'application aura renvoyé une réponse valide, votre application 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 navigateur destinée aux utilisateurs, créez et hébergez une nouvelle URL accessible depuis le navigateur de l'utilisateur et capable d'accepter les demandes provenant des redirections du 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 retourner leur session d'agent actuellement active. Dans les étapes ultérieures de l'implémentation, 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 principale de l'application, par exemplehttps://myagentapp.com/assistant. Vous voudrez exposer une nouvelle URL comme celle-ci, https://myagentapp.com/callback qui redirigera pour l'instant vers la page principale de l'application. La logique du code réel de votre /callback point de terminaison sera mise à jour ultérieurement en suivant ce guide.

Mettre à jour l'identité de la charge de travail avec l'URL de l'application — (Peut être ignorée en cas de test local via la AgentCore CLI) Une fois que vous avez créé et hébergé une URL d'application vers laquelle AgentCore Identity doit ê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 à appeler CreateWorkloadIdentity ou UpdateWorkloadIdentity selon que vous créez une nouvelle identité de charge de travail ou que vous mettez à 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 le 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 le stockage local 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 accédez à l'URL d'autorisation renvoyée dans votre navigateur. Après avoir effectué l'autorisation auprès du fournisseur de ressources OAuth 2.0, le navigateur devrait être redirigé vers l'URL de votre application et invoquer l'CompleteResourceTokenAuthAPI. Une fois que l'application aura renvoyé une réponse valide, votre application agent pourra 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.