대화형 에이전트에서 사용자 인증

에이전트는 종종 에이전트를 사용하는 사용자를 대신하여 조치를 취해야 합니다. 대화형 에이전트를 빌드하는 첫 번째 단계는 사용자를 인증하는 것입니다. 이 문서에서는 사용자를 인증하는 간단한 웹 서비스를 빌드하는 프로세스를 안내합니다. 에이전트 아이디 설계도는 웹 서비스 보안을 위해 사용됩니다. 단계는 다음과 같습니다.

1. 클라이언트는 에이전트 ID 청사진에 대한 범위가 지정된 액세스 토큰을 가져옵니다.
2. 에이전트의 API에서 해당 토큰의 유효성을 검사합니다.
3. 권한 부여에 사용할 수 있는 사용자에 대한 클레임을 추출합니다.

필수 조건

에이전트 정체성 청사진. 에이전트 ID 설계도 앱 ID(클라이언트 ID)를 기록하십시오.

에이전트 ID 청사진에 대한 토큰 요청

사용자를 인증하려면 클라이언트 앱(예: 프런트 엔드 또는 모바일 앱)에서 OAuth 2.0 권한 부여 요청을 시작하여 대상 사용자가 에이전트 ID 청사진인 토큰을 가져와야 합니다.

1. 다음 매개 변수를 사용하여 사용자를 Microsoft Entra ID 권한 부여 엔드포인트로 리디렉션합니다.

   GET https://login.microsoftonline.com/<my-test-tenant>/oauth2/v2.0/authorize?client_id=<client-id>
   &response_type=code
   &redirect_uri=<redirect_uri>
   &response_mode=query
   &scope=api://<agent-blueprint-id>/access_agent
   &state=abc123
   

2. 사용자가 로그인하면 앱은 리디렉션 URI에서 권한 부여 코드를 받습니다. 액세스 토큰으로 교환합니다.

   POST https://login.microsoftonline.com/<my-test-tenant>/oauth2/v2.0/token
   Content-Type: application/x-www-form-urlencoded
   
   client_id=<client-id>
   grant_type=authorization_code
   code=<authorization_code>
   redirect_uri=<redirect_uri>
   scope=api://<agent-blueprint-id>/access_agent
   client_secret=<client-secret>  # Only if using a confidential client
   

   JSON 응답에는 에이전트의 API에 액세스하는 데 사용할 수 있는 액세스 토큰이 포함되어 있습니다.

에이전트의 API에서 토큰 유효성 검사

일반적으로 웹 API를 통해 노출되는 에이전트는 액세스 토큰의 유효성을 검사해야 합니다. 항상 승인된 라이브러리를 사용하여 토큰 유효성 검사를 수행하며 사용자 고유의 토큰 유효성 검사 코드를 구현해서는 안 됩니다.

1. Microsoft.Identity.Web NuGet 패키지를 설치합니다.

   dotnet add package Microsoft.Identity.Web
   

2. ASP.NET Core 웹 API 프로젝트에서 Microsoft Entra ID 인증을 구현합니다.

   // Program.cs
   using Microsoft.Identity.Web;
   
   var builder = WebApplication.CreateBuilder(args);
   
   builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
       .AddMicrosoftIdentityWebApi(builder.Configuration.GetSection("AzureAd"));
   
   var app = builder.Build();
   
   app.UseAuthentication();
   app.UseAuthorization();
   

3. appsettings.json 파일에서 인증 자격 증명을 구성합니다.

"AzureAd": {
"Instance": "https://login.microsoftonline.com/",
"TenantId": "<my-test-tenant>",
"ClientId": "<agent-blueprint-id>",
"Audience": "<agent-blueprint-id>",
"ClientCredentials": [
    {
    "SourceType": "ClientSecret",
    "ClientSecret": "your-client-secret"
    }
]
}

Microsoft.Identity.Web에 대한 자세한 내용은 공식 문서를 참조하세요.

사용자 클레임 유효성 검사

액세스 토큰의 유효성을 검사한 후 에이전트는 이제 사용자를 식별하고 권한 부여 검사를 수행할 수 있습니다. 이 예제 API 경로는 액세스 토큰에서 사용자 클레임을 추출하고 API 응답에서 반환합니다.

app.MapGet("/hello-agent", (HttpContext httpContext) =>
{   
    var claims = httpContext.User.Claims.Select(c => new
    {
        Type = c.Type,
        Value = c.Value
    });

    return Results.Ok(claims);
})
.RequireAuthorization();

관련 콘텐츠

토큰 클레임