토픽에 최종 사용자 인증 추가

아티클
12/09/2024

에이전트 대화에서 직접 사용자 인증을 활성화할 수 있습니다. 이름 및 ID와 같은 사용자의 기본 속성을 변수에 할당할 수 있습니다. 또한 주제의 인증 노드를 사용하여 로그인하도록 사용자에게 요청하여 사용자 토큰을 검색한 다음 해당 토큰을 사용하여 백엔드 시스템에서 사용자 정보를 검색할 수 있습니다.

참고

Copilot Studio 및 Microsoft Teams 에서 생성된 에이전트는 자동으로 Microsoft Entra ID 인증을 위해 구성됩니다.

사용자가 수동으로 로그인할 필요가 없도록 싱글 사인온(SSO)을 구성할 수도 있습니다. 자세한 내용은 Microsoft Entra ID로 Single Sign-On 구성을 참조하세요.

고객이 대화에서 바로 로그인할 수 있도록 주제에 사용자 인증을 추가하세요. 그런 다음 사용자 변수로 대화를 개인화하고 사용자 대신 백엔드 시스템에 액세스할 수 있습니다.

Microsoft Entra ID로 수동 인증 구성

주제에서 인증을 사용하려면 먼저 Microsoft Entra ID로 사용자 인증을 구성해야 합니다.

Microsoft Entra ID로 사용자 인증 구성의 지침을 따르세요.

에이전트를 생성하면 Copilot Studio 로그인이라는 시스템 토픽가 자동으로 추가됩니다. 이를 사용하려면 에이전트의 인증을 수동으로 설정하고 사용자에게 로그인을 요구해야 합니다. 고객이 에이전트와 대화를 시작하면 로그인 토픽가 트리거되어 사용자에게 로그인하라는 메시지가 표시됩니다. 에이전트에 맞게 토픽의 로그인 을 사용자 정의할 수 있습니다.

중요

로그인 토픽은 Copilot Studio에서 제공하는 인증 방법을 제공하는 데에만 사용하는 것이 좋습니다. 다른 작업이나 흐름 또는 다른 인증 방법을 호출하도록 수정해서는 안 됩니다.

에이전트를 열고 Copilot Studio페이지 상단에서 설정 을 선택한 다음 보안을 선택하세요.
인증을 선택합니다.
수동으로 인증을 선택한 다음, 사용자가 로그인하도록 요구를 선택합니다.
필요에 따라 모든 수동 인증 필드를 구성합니다.
저장을 선택합니다.

사용자 정의 토픽으로 사용자 인증 추가

로그인 토픽은 대화 시작 시 사용자를 인증합니다. 사용자가 나중에 로그인할 수 있도록 사용자 정의 토픽에 인증 노드를 추가할 수 있습니다.

고객이 사용자 이름과 암호를 입력하면 확인 코드를 입력하라는 메시지가 표시될 수 있습니다. 로그인한 후에는 다른 인증 노드에 도달하더라도 다시 메시지가 표시되지 않습니다.

페이지 상단의 설정을 선택한 후, 보안을 선택하세요.
인증 타일을 선택합니다.

참고

사용자 지정 토픽에 사용자 인증을 추가하려면 수동으로 인증을 선택해야 합니다.
사용자가 로그인하도록 요구 확인란을 선택 취소합니다.
필요에 따라 모든 수동 인증 필드를 구성합니다.
저장을 선택합니다.
페이지 맨 위에서 토픽을 선택합니다.
노드 추가 ( ) >고급>인증을 선택합니다.
ID 공급자로 구성된 사용자를 사용하여 토픽을 테스트합니다.

팁

성공적인 로그인과 로그인 실패 모두에 대한 경로를 만드는 것이 중요합니다. ID 공급자의 로그인 환경 오류를 포함하여 여러 가지 이유로 로그인에 실패할 수 있습니다.

인증 변수

에이전트에 대한 사용자 인증을 구성할 때 토픽에서 인증 변수를 사용할 수 있습니다. 다음 표에서는 선택한 인증 옵션에 따라 이러한 변수의 가용성을 비교합니다.

변수에 대한 자세한 내용은 변수 작업을 참조하십시오.

인증 변수	인증 없음	Microsoft로 인증	수동으로 인증
User.DisplayName	사용할 수 없음	대화 가능	대화 가능
User.FirstName	사용할 수 없음	대화 가능	대화 가능
User.LastName	사용할 수 없음	대화 가능	대화 가능
User.PrincipalName	사용할 수 없음	대화 가능	대화 가능
User.Email	사용할 수 없음	대화 가능	대화 가능
User.Id	사용할 수 없음	대화 가능	대화 가능
User.IsLoggedIn	사용할 수 없음	대화 가능	대화 가능
User.AccessToken	사용할 수 없음	사용할 수 없음	대화 가능
SignInReason	사용할 수 없음	대화 가능	대화 가능

User.DisplayName

경고

이 변수는 값을 포함한다고 보장되지 않습니다. 주제가 올바르게 작동하는지 확인하려면 자격 증명 공급자의 사용자와 테스트하세요.

User.DisplayName 변수에는 ID 공급자에 저장된 표시 이름이 포함됩니다. 이 변수를 사용하면 사용자가 에이전트에 자신의 이름을 명시적으로 제공하지 않고도 인사하거나 사용자를 지칭할 수 있으므로 대화가 더 개인화됩니다.

Copilot Studio는 수동 인증이 구성되었을 때 profile 범위가 정의된 한 ID 공급자가 제공한 name 클레임에서 User.DisplayName 값을 자동으로 설정합니다. 범위에 대한 자세한 내용은 Microsoft Entra ID로 사용자 인증 구성을 참조하세요.

User.Id

경고

이 변수는 값을 포함한다고 보장되지 않습니다. 주제가 올바르게 작동하는지 확인하려면 자격 증명 공급자의 사용자와 테스트하세요.

User.Id 변수에는 ID 공급자에 저장된 사용자 ID가 포함됩니다. Power Automate 흐름에서 이 변수를 사용하여 UserID를 값으로 사용하는 API를 호출합니다.

Copilot Studio는 ID 공급자가 제공한 sub 클레임에서 User.DisplayName 값을 자동으로 설정합니다.

User.IsLoggedIn

User.IsLoggedIn은 사용자의 로그인 상태를 저장하는 부울 변수입니다. true 값은 사용자가 로그인했음을 나타냅니다. 이 변수를 사용하여 성공적인 로그인을 확인하는 분기 논리를 주제에 만들거나 사용자가 로그인한 경우에만 사용자 정보를 가져올 수 있습니다.

User.AccessToken

경고

신뢰할 수 있는 소스에만 User.AccessToken 변수를 전달하도록 하십시오. 여기에는 손상된 경우 사용자를 해칠 수 있는 사용자 인증 정보가 포함되어 있습니다.

User.AccessToken 변수는 사용자가 로그인한 후 얻은 사용자의 토큰을 포함합니다. 이 변수를 Power Automate 흐름에 전달하여 백엔드 API에 연결하고 사용자 정보를 가져오거나 사용자를 대신하여 작업을 수행할 수 있습니다.

메시지 노드 또는 신뢰할 수 없는 흐름에서 User.AccessToken을 사용하지 마세요.

SignInReason

SignInReason은 사용자가 로그인해야 하는 시기를 나타내는 선택형 변수입니다. 두 가지 가능한 값이 있습니다.

SignInRequired는 사용자가 로그인 시스템 토픽을 사용하여 대화를 시작할 때 로그인해야 함을 나타냅니다. 사용자 로그인 요구 가 켜져 있어야 합니다.
Initializer 사용자가 로그인하지 않은 상태에서 인증 변수를 사용하는 대화의 특정 지점에 도달하면 로그인하라는 메시지가 표시됨을 나타냅니다.

인증 변수

에이전트가 Microsoft로 인증 또는 수동 인증 옵션으로 구성된 경우 토픽에서 사용 가능한 인증 변수 세트가 있습니다. 에이전트에서 인증을 구성하는 방법에 대한 자세한 내용은 사용자 인증 구성 Copilot Studio을 참조하세요.

다음 표는 인증 구성 옵션별 인증 변수 가용성을 비교합니다.

인증 변수	인증 없음	Microsoft로 인증	매뉴얼
`User.DisplayName`	❌	✔️	✔️
`User.Id`	❌	✔️	✔️
`User.IsLoggedIn`	❌	❌	✔️
`User.AccessToken`	❌	❌	✔️

UserDisplayName 변수

User.DisplayName 변수에는 ID 공급자에 저장된 사용자의 표시 이름이 포함됩니다. 이 변수를 사용하면 사용자가 에이전트에 명확하게 알리지 않고도 인사하거나 참조할 수 있으므로 더욱 개인화할 수 있습니다.

이 필드 값은 Microsoft Entra ID name 클레임에서 가져옵니다. OAuth 공급자의 경우 이 값은 name 클레임에 저장됩니다. Copilot Studio는 이 필드를 변수로 자동 추출하므로 인증 범위 설정의 일부로 profile이 있는지 확인하십시오.

UserID 변수

User.Id 변수에는 ID 공급자에 저장된 사용자의 ID가 포함됩니다. Power Automate 흐름은 이 값을 사용하여 UserID를 값으로 사용하는 API를 호출할 수 있습니다. 이 필드 값은 Microsoft Entra ID sub 클레임에서 가져옵니다. OAuth 공급자의 경우 이 값은 sub 클레임에 저장됩니다. Copilot Studio는 자동으로 이 필드를 변수로 추출합니다.

경고

User.DisplayName 및 User.Id 변수는 채워지지 않을 수도 있으며 ID 공급자의 사용자 구성에 따라 빈 문자열일 수 있습니다. ID 공급자의 사용자와 함께 테스트하여 이러한 변수가 비어 있더라도 토픽이 올바르게 작동하는지 확인하십시오.

IsLoggedIn 변수

User.IsLoggedIn 변수는 사용자가 로그인했는지(로그인 결과 또는 이미 로그인되어 있는지, 로그인 성공 경로라고도 함) 또는 로그인하지 않았는지(로그인 실패 경로가 됨)를 나타냅니다.

User.IsLoggedIn은 사용자의 로그인 상태를 포함하는 부울 변수입니다. 이 변수를 사용하여 토픽에서 성공적인 로그인을 확인하는 분기 논리를 작성(예: 인증 노드 추가의 일부로 이미 제공된 템플릿)하거나, 사용자가 로그인한 경우에만 사용자 정보를 선택적으로 가져올 수 있습니다.

User.AccessToken 변수

User.AccessToken 변수는 사용자가 로그인한 후 얻은 사용자의 토큰을 포함합니다. 이 변수를 Power Automate 흐름에 전달하여 백엔드 API에 연결하여 사용자 정보를 가져오거나 사용자를 대신하여 조치를 취할 수 있습니다.

경고

메시지 노드 내부 또는 신뢰할 수없는 흐름에서는 User.AccessToken을 사용하지 마십시오.

인증 변수 테스트

기본적으로 테스트 봇 창은 현재 로그인한 사용자의 계정을 사용하여 User.DisplayName과 User.Id 변수를 채웁니다. 그러나 인증을 사용하는 주제를 테스트할 때 이러한 변수에 다른 값(또는 공백 값)을 사용할 수 있습니다.

예를 들어 특수 문자가 어떻게 사용되는지 또는 변수가 비어있는 경우 어떻게 되는지 테스트할 수 있습니다.

다음 표에는 이러한 변수를 채우는 명령이 나열되어 있습니다. 이러한 명령은 테스트 봇 창에만 적용됩니다. 채널에 배포된 게시된 에이전트에서는 사용할 수 없습니다.

일반적으로 에이전트로 채팅할 때처럼 원하는 명령을 테스트 봇 창에 입력하세요. 성공하면 에이전트에서 확인 메시지를 받게 됩니다. 에이전트가 인증을 사용하지 않으면 오류가 발생합니다.

테스트 봇 창을 재설정하면(또는 테스트 봇이 자동으로 재설정되도록 토픽 변경) 명령을 다시 보내야 합니다.

변수	사용자 지정 값 명령	빈(공백) 값 명령
`User.DisplayName`	`/debug set bot.UserDisplayName "Value"`	`/debug set bot.UserDisplayName ""`
`User.Id`	사용할 수 없음	`/debug set bot.UserID ""`

중요

보안상의 이유로 User.Id 변수를 사용자 지정 값(비어 있거나 빈 값 제외)으로 채울 수 없습니다.

"Microsoft로 인증"을 사용하는 경우 인증

인증 옵션이 Microsoft로 인증으로 설정된 경우 토픽에 인증을 명시적으로 추가할 필요가 없습니다. 이 구성에서 Microsoft Teams의 모든 사용자는 Teams 자격 증명을 통해 자동으로 로그인되며 인증 카드로 명시적으로 로그인할 필요가 없습니다. 인증 옵션이 수동으로 설정된 경우 인증 노드를 추가해야 합니다(Teams 채널의 경우에도 마찬가지입니다).

참고

인증 옵션이 Microsoft로 인증으로 설정된 경우 토픽에 인증을 명시적으로 추가하는 옵션은 없습니다.

토픽에 사용자 인증 추가

인증 노드는 사용자에게 로그인 카드로 로그인하라는 메시지를 표시합니다. 사용자가 일단 로그인하면 다른 인증 노드에 도달하더라도 다시 메시지가 표시되지 않습니다.

로그인 요청.

사용자가 프롬프트에 아이디와 비밀번호를 입력하면(ID 공급자가 호스팅함) 채널에 따라 인증 코드를 입력하라는 메시지가 표시될 수 있습니다. Microsoft Teams와 같은 일부 채널은 사용자의 유효성 검사 코드가 필요하지 않습니다.

에이전트에 SSO 가 구성된 경우 사용자에게 로그인하라는 메시지가 표시되지 않습니다.

토픽에 인증 노드를 추가하려면:

편집하려는 에이전트의 주제 페이지로 이동하세요.
인증 템플릿을 추가할 토픽을 엽니다.

참고

에이전트가 Dynamics 365 고객 서비스,에 연결되어 있는 경우 인증 노드는 에이전트가 사용자를 처음 맞이할 때 따르는 대화 경로에 포함될 수 없습니다. 그렇지 않으면 로그인 카드가 두 번 표시됩니다. 대신 사용자 응답에 의해 트리거되는 다른 토픽에 인증 노드를 추가해야 합니다.
노드 추가(+)를 선택하여 메시지 노드를 추가합니다. 에이전트에 로그인 환경이 곧 시작됨을 나타내는 내용을 입력하세요.
메시지 노드 아래에서 노드 추가(+)를 선택하고 작업 호출을 선택한 다음 인증을 선택합니다.

노트

인증 노드는 대화 트리(잎 노드) 끝에 있는 작업 선택기에서만 사용할 수 있습니다. 대화 상자 중간에 추가할 수 없습니다. 한번 추가되면 다른 노드를 그 아래에 추가할 수 있습니다.

새 노드가 자동으로 나타납니다. 상위 인증 노드 뒤에 성공 경로와 실패 경로에 대한 노드가 나타납니다.

인증 노드가 없는 User.AccessToken 사용법

작업 호출 메뉴 항목에서 제공한 템플릿을 사용하지 않아도 User.IsLoggedIn과 User.AccessToken 변수를 사용할 수 있습니다. 사용자가 먼저 인증 노드를 거치지 않고 User.AccessToken 변수를 전달하면 사용자에게 해당 단계에서 로그인하라는 메시지가 표시됩니다.

User.AccessToken 변수는 사용자가 항상 로그인할 것으로 예상하거나 다른 토픽에서 리디렉션되는 경우 유용할 수 있습니다. 사용자가 로그인하지 못하는 경우를 처리하기 위해 작업 호출 항목에서 제공한 템플릿을 사용하는 것이 좋습니다.

노트

토픽이 User.AccessToken 변수를 사용하는 노드에 도달한 경우 사용자가 대화 중간에 로그아웃하면 다시 로그인하라는 메시지가 표시됩니다.

성공 경로

성공 경로는 User.IsLoggedIn = True에 해당하며 사용자가 성공적으로 로그인했거나 이미 로그인한 시기를 설명합니다.

User.AccessToken 변수를 사용하는 논리가 있다면(예: 흐름을 사용하여 백엔드 시스템에 연결하여 사용자 정보를 검색하는 경우) 이 경로 아래로 이동해야 합니다.

실패 경로

실패 경로는 IsLoggedIn = True 이외의 조건에 해당합니다. 대부분의 경우 실패 경로는 사용자가 로그인에 실패했거나 잘못된 암호를 사용했거나 로그인을 취소했기 때문에 발생합니다.

이 경우를 처리할 논리를 추가하세요. 예를 들어, 재시도 또는 라이브 에이전트로 에스컬레이션할 수 있는 옵션을 제공하고 있습니다. 특정 시나리오 및 사용의 실패 경로 작업을 사용자 지정합니다.

토픽 테스트

ID 공급자에서 구성된 실제 사용자를 사용하여 토픽 테스트 진행하세요. 로그인 성공 및 실패 경로가 모두 실행되도록 하므로 사용자가 로그인하지 못하거나 ID 공급자로 로그인 경험에 오류가 있는 경우 놀라운 결과가 없습니다.

사용자가 수동으로 로그인할 필요가 없도록 싱글 사인온(SSO)을 구성할 수도 있습니다. 자세한 내용은 Microsoft Entra ID로 Single Sign-On 구성을 참조하세요.

다음을 통해 공유

토픽에 최종 사용자 인증 추가