OAuth를 사용하도록 .NET 에이전트 구성

.NET 에이전트에 대한 OAuth는 먼저 Azure Bot 리소스 및 해당 앱 등록에 프로비전됩니다. 그런 다음 에이전트 런타임은 AgentApplication 자동 로그인 기능을 통해 사용자 토큰을 획득하고 새로 고칩니다. 자동 로그인은 전역적으로(모든 활동 형식) 또는 선택적으로 실행되어 특정 경로 또는 활동 유형만 토큰을 요청하도록 할 수 있습니다.

구성에서 여러 OAuth 처리기를 등록하고 특정 경로에 할당하거나 모든 곳에서 사용되는 단일 기본 처리기를 선언할 수 있습니다. 각 처리기는 Azure 쪽에 대해 설정된 경우 선택적으로 OBO(On-Behalf-Of) 교환을 수행할 수 있습니다. 빠른 시작을 위해 AutoSignIn 샘플을 참조하거나, 여기에 표시된 구성을 기존 에이전트에 적용하십시오.

다음 섹션에서는 [UserAuthorization를] 구성하는 방법, 전역과 경로별 접근 방식 중 어떤 것을 사용할지 결정하는 방법, 그리고 시퀀스 중에 토큰(표준 및 OBO)을 추출하는 방법을 설명합니다. 미국 이외의 배포에 대한 지역 지침도 제공됩니다.

.NET 에이전트는 appsettings 또는 Program.cs에서의 코드를 통해 구성됩니다. 이 문서에서는 appsettings를 사용하는 방법에 대해 자세히 설명합니다.

설정

내부 UserAuthorization 개체는 AgentApplication 사용자 토큰을 획득하는 방법을 제어합니다. 다음 JSON은 계층 구조를 보여주며, UserAuthorization 및 중첩된 Settings 객체의 각 속성을 설명하는 테이블도 포함하고 있습니다.

  "AgentApplication": {
    "UserAuthorization": {
      "DefaultHandlerName": "{{handler-name}}",
      "AutoSignIn": true | false,
      "Handlers": {
        "{{handler-name}}": {
          "Settings": {
            "AzureBotOAuthConnectionName": "{{azure-bot-connection-name}}",
            "OBOConnectionName": "{{connection-name}}",
            "OBOScopes": [
              "{{obo-scope}}"
            ],
            "Title": "{{signin-card-title}}",
            "Text": "{{signin-card-button-text}}",
            "InvalidSignInRetryMax": {{int}},
            "InvalidSignInRetryMessage": {{invalid-attempt-message}},
            "Timeout": {{timeout-ms}}
          }
        }
      }
    }
  }

UserAuthorization 속성

다음 표에서는 처리기를 선택하는 방법과 들어오는 각 작업에 대해 토큰을 획득하는 방법을 결정하는 최상위 UserAuthorization 속성을 나열합니다.

자동 로그인이 적용되는 활동을 제한하려면 다음과 유사한 Options.AutoSignIn = (context, ct) => Task.FromResult(context.Activity.IsType(ActivityTypes.Message));조건자를 설정합니다.

설정 속성

다음 표에서는 로그인 카드 프레젠테이션, 재시도 동작, 시간 제한 및 선택적 OBO 교환 구성을 제어하는 개별 OAuth 처리기에 적용된 Settings 중첩된 개체에 대해 설명합니다.

사용할 형식은 무엇입니까?

다음 표를 사용하여 시나리오에 적합한 방법을 결정합니다.

코드에서 토큰 사용(OBO가 아닌 경우)

이 섹션에서는 On-Behalf-Of 교환을 수행하지 않고 Azure Bot OAuth 연결에서 직접 반환된 사용자 토큰을 검색하고 사용하는 방법을 보여 줍니다. 전역 자동 로그인 또는 경로별 처리기를 선호하는지 먼저 결정합니다. 그런 다음 활동 처리기 내에서 SDK가 만료가 거의 되면 토큰을 새로 고칠 수 있도록 가능한 한 늦게 호출 UserAuthorization.GetTurnTokenAsync 합니다. 다음 예제에서는 두 패턴을 모두 보여 줍니다.

자동 로그인 전용 구성

전역 자동 로그인에서 경로별 처리기를 지정할 필요 없이 들어오는 모든 작업에 대한 토큰을 획득해야 하는 경우 이 구성을 사용합니다.

  "AgentApplication": {
    "UserAuthorization": {
      "DefaultHandlerName": "auto",
      "Handlers": {
        "auto": {
          "Settings": {
            "AzureBotOAuthConnectionName": "teams_sso",
          }
        }
      }
    }
  },

에이전트 코드는 다음과 같습니다.

public class MyAgent : AgentApplication
{
    public MyAgent(AgentApplicationOptions options) : base(options)
    {
        OnActivity(ActivityTypes.Message, OnMessageAsync, rank: RouteRank.Last);
    }

    public async Task OnMessageAsync(ITurnContext turnContext, ITurnState turnState, CancellationToken cancellationToken)
    {
        var token = await UserAuthorization.GetTurnTokenAsync(turnContext);

        // use the token 
    }
}

경로별 전용 구성

세분화된 제어를 원하는 경우 경로별 구성을 사용합니다. 명시적으로 표시한 경로만 토큰을 획득합니다. 경로별 구성은 불필요한 토큰 검색을 줄이고, 서로 다른 경로가 고유한 OAuth 연결(따라서 다른 리소스 또는 범위)을 대상으로 할 수 있게 하며, 동일한 에이전트 내에서 인증된 경로와 인증되지 않은 경로를 혼합할 수 있도록 합니다. 다음 예제에서는 전역 자동 로그인이 비활성화되고 단일 messageOauth 처리기가 메시지 경로에만 연결됩니다.

  "AgentApplication": {
    "UserAuthorization": {
      "AutoSignIn": false,
      "Handlers": {
        "messageOauth": {
          "Settings": {
            "AzureBotOAuthConnectionName": "teams_sso",
          }
        }
      }
    }
  },

에이전트 코드는 다음과 같습니다.

public class MyAgent : AgentApplication
{
    public MyAgent(AgentApplicationOptions options) : base(options)
    {
        OnActivity(ActivityTypes.Message, OnMessageAsync, rank: RouteRank.Last, autoSignInHandlers: ["messageOauth"]);
    }

    public async Task OnMessageAsync(ITurnContext turnContext, ITurnState turnState, CancellationToken cancellationToken)
    {
        var token = await UserAuthorization.GetTurnTokenAsync(turnContext, "messageOauth");

        // use the token
    }
}

GetTurnTokenAsync 사용

턴 중에 사용자 토큰이 필요할 때마다 호출 GetTurnTokenAsync 합니다. 여러 번 호출할 수 있습니다. 새로 고침 논리(필요한 경우)가 투명하게 처리되도록 사용하기 직전에 호출합니다.

코드에서 토큰 사용(OBO)

OBO(On-Behalf-Of)는 교환 가능한 토큰을 반환하는 초기 사용자 로그인을 사용합니다. 이를 위해서는 OAuth 연결의 범위가 다운스트림 API에 의해 노출되는 범위에 해당하는 범위를 포함해야 합니다(예: 노출된 범위인 defaultScopes경우 구성된 범위일 수 있습니다 api://botid-{{clientId}}/defaultScopes). 그런 다음 에이전트 SDK는 OBOConnectionName로 식별된 구성된 연결과 OBOScopes 목록을 사용하여 MSAL(Microsoft 인증 라이브러리) 교환을 수행합니다. 구성에 OBOConnectionName와 OBOScopes가 모두 포함되어 있으면 교환이 자동으로 수행되며, GetTurnTokenAsync를 통해 최종 토큰을 얻습니다. 둘 중 하나가 누락된 경우 런타임 ExchangeTurnTokenAsync에 명시적으로 교환을 수행하여 연결 또는 범위 목록을 동적으로 확인할 수 있습니다.

구성의 OBO

구성 시 필요한 다운스트림 리소스 및 범위를 알고 있는 경우 이 패턴을 사용합니다. OBOConnectionName 및 OBOScopes 둘 다 제공하면 SDK는 로그인 시 On-Behalf-Of 교환을 자동으로 수행합니다. 즉, 추가 런타임 코드 없이 OBO 토큰을 직접 반환하기 위한 GetTurnTokenAsync 후속 호출을 의미합니다.

  "AgentApplication": {
    "UserAuthorization": {
      "DefaultHandlerName": "auto",
      "Handlers": {
        "auto": {
          "Settings": {
            "AzureBotOAuthConnectionName": "teams_sso",
            "OBOConnectionName": "ServiceConnection",
            "OBOScopes": [
              "https://myservicescope.com/.default"
            ]
          }
        }
      }
    }
  },
  "Connections": {
    "ServiceConnection": {
      "Settings": {
        "AuthType": "FederatedCredentials",
        "AuthorityEndpoint": "https://login.microsoftonline.com/{{TenantId}}",
        "ClientId": "{{ClientId}}",
        "FederatedClientId": "{{ManagedIdentityClientId}}",
        "Scopes": [
          "https://api.botframework.com/.default"
        ]
      }
    }
  },

에이전트 코드는 다음과 같습니다.

public class MyAgent : AgentApplication
{
    public MyAgent(AgentApplicationOptions options) : base(options)
    {
        OnActivity(ActivityTypes.Message, OnMessageAsync, rank: RouteRank.Last);
    }

    public async Task OnMessageAsync(ITurnContext turnContext, ITurnState turnState, CancellationToken cancellationToken)
    {
        var token = await UserAuthorization.GetTurnTokenAsync(turnContext);

        // use the token
    }
}

런타임 시 OBO 교환

다운스트림 리소스, 범위 또는 사용해야 하는 연결이 구성에서 고정될 수 없는 경우(예: 범위가 테넌트, 사용자 역할 또는 기능 플래그에 의존하는 경우) 런타임 교환을 사용합니다. 이 모델에서는 OBOConnectionName을 옵션으로 구성한 다음, 턴타임에 결정한 범위로 ExchangeTurnTokenAsync을 호출하여 교환된 토큰을 받아 즉시 적용할 수 있습니다.

  "AgentApplication": {
    "UserAuthorization": {
      "DefaultHandlerName": "auto",
      "Handlers": {
        "auto": {
          "Settings": {
            "AzureBotOAuthConnectionName": "teams_sso",
            "OBOConnectionName": "ServiceConnection"
          }
        }
      }
    }
  },
  "Connections": {
    "ServiceConnection": {
      "Settings": {
        "AuthType": "FederatedCredentials",
        "AuthorityEndpoint": "https://login.microsoftonline.com/{{TenantId}}",
        "ClientId": "{{ClientId}}",
        "FederatedClientId": "{{ManagedIdentityClientId}}",
        "Scopes": [
          "https://api.botframework.com/.default"
        ]
      }
    }
  },

에이전트 코드는 다음과 같습니다.

public class MyAgent : AgentApplication
{
    public MyAgent(AgentApplicationOptions options) : base(options)
    {
        OnActivity(ActivityTypes.Message, OnMessageAsync, rank: RouteRank.Last);
    }

    public async Task OnMessageAsync(ITurnContext turnContext, ITurnState turnState, CancellationToken cancellationToken)
    {
        var scopes = GetScopes();

        var exchangedToken = await UserAuthorization.ExchangeTurnTokenAsync(turnContext, exchangeScopes: scopes);

        // use the token
    }
}

국가별 OAuth 설정

미국 이외의 지역의 경우 에이전트에서 사용하는 토큰 서비스 엔드포인트를 업데이트해야 합니다.

다음 항목을 appsettings.json에 추가합니다.

"RestChannelServiceClientFactory": {
   "TokenServiceEndpoint": "{{service-endpoint-uri}}"
}

의 경우 service-endpoint-url지정된 지역에 데이터가 상주하는 퍼블릭 클라우드 봇에 대해 다음 표의 적절한 값을 사용합니다.