모달 대화 상자를 추가하여 Microsoft 365 Copilot용 선언적 에이전트에서 적응형 카드 응답을 향상시킬 수 있습니다. 이러한 팝업 대화 상자는 사용자 지정 HTML/JavaScript를 호스트하거나 포커스된 대화형 환경 내에서 웹 페이지, YouTube 비디오 또는 Microsoft Stream 콘텐츠와 같은 iframe 기반 위젯을 표시할 수 있습니다.
이 문서에서는 적응형 카드 템플릿에서 모달 대화 상자를 시작하기 위해 사용(적응형 카드 스키마 버전 1.5에서 사용 가능)과 사용자 인증을 구성하는 방법을 설명합니다 Action.OpenUrlDialog .
참고
작업은 OpenUrlDialog 현재 미리 보기로 제공됩니다.
필수 구성 요소
을 사용하려면 Action.OpenUrlDialog다음과 같은 필수 구성 요소가 필요합니다.
- 적응형 카드 스키마 버전 1.5
- API 플러그인 매니페스트 버전 2.3
- Microsoft TeamsJS 라이브러리(인증 시나리오용)
적응형 카드 서식 파일 정의
모달 대화 상자 동작을 사용하려면 다음을 수행합니다.
- 플러그 인 매니페스트에 적응형 카드 템플릿을 추가합니다.
- 적응형 카드 정의에 스키마를 포함
Action.OpenUrlDialog합니다.
다음 예제에서는 의 스키마를 보여 줍니다.Action.OpenUrlDialog
"actions": [
{
"type": "Action.OpenUrlDialog",
"title": "OpenDialogWithDimension",
"url": "${url}",
"dialogHeight": "large",
"dialogWidth": "600px",
"dialogTitle": "task module"
}
]
스키마 참조 정보는 Action.OpenUrlDialog를 참조하세요.
대화 상자 크기 구성
dialogHeight 및 dialogWidth 속성을 사용하여 대화 상자의 높이와 너비를 설정합니다. 이러한 값은 사용자의 화면 해상도와 창 크기에 따라 동적으로 조정됩니다.
다음을 지정할 수 있습니다.
- 미리 정의된 크기 -
small,medium, 또는large. - 사용자 지정 픽셀 값(예:
400px,600px).
팁
픽셀 값을 사용하여 세밀하게 제어할 수 있습니다. 미리 정의된 크기는 사용 가능한 화면 공간에 상대적입니다.
다음 이미지는 에이전트가 반환한 적응형 카드 단추에서 호출되는 대화 상자의 예를 보여줍니다.
인증 구성
대화 상자 내에서 API에 대한 보안 액세스를 허용하려면 다음 방법 중 하나를 사용하여 인증을 구성합니다.
- Microsoft Entra ID
- OAuth 2.0(미리 보기)
Microsoft Entra ID 설정
API 인증에 Entra ID 인증을 사용하려면 다음 방법 중 하나를 사용합니다.
- Microsoft를 ID 공급자로 사용하여 Entra ID, OAuth 2.0 또는 API 키 기반 인증을 구성합니다.
- 다른 ID 공급자를 사용하고 Entra ID에 앱을 등록합니다.
SSO 기반 인증 구성
사용자가 여러 번 로그인할 필요 없이 API에 액세스할 수 있도록 SSO(Single Sign-On)를 구성합니다.
SSO를 사용하도록 설정하려면:
- Microsoft Entra ID 애플리케이션을 업데이트합니다.
- 애플리케이션 ID URI를 구성합니다.
- 범위 및 동의 설정을 구성합니다.
- 반복되는 동의 프롬프트를 방지하기 위해 신뢰할 수 있는 클라이언트 애플리케이션에 사전 권한을 부여합니다.
- 토큰 검색 및 유효성 검사 논리를 구현합니다.
- TeamsJS 라이브러리의 메서드를 사용하여
getAuthToken()액세스 토큰을 검색합니다. - 권한 부여 헤더에서 서버로 토큰을 보냅니다.
- 서버 쪽에서 토큰의 유효성을 검사합니다.
- TeamsJS 라이브러리의 메서드를 사용하여
- 앱 매니페스트를 업데이트합니다.
- SSO를 사용하도록 설정하려면 앱 매니페스트에 webApplicationInfo 속성을 추가합니다.
- 앱 매니페스트의 'validDomains 속성에 대화 상자 콘텐츠의 도메인을 추가합니다.
Microsoft Entra ID 애플리케이션 업데이트
범위를 구성하고 신뢰할 수 있는 클라이언트 애플리케이션에 권한을 부여하려면 다음과 같이 Microsoft Entra ID 애플리케이션을 업데이트합니다.
앱 매니페스트의 identifierUris 속성에 API URI를 추가합니다. 다음 예제와 같이 URI에 'api://fully-qualified-domain-name.com/{AppID} 형식을 사용합니다.
"identifierUris": [ "api://b4ab3a28-16da-4a19-a07a-51ab0f3553db", "api://4-213-70-45.ngrok-free.app/b4ab3a28-16da-4a19-a07a-51ab0f3553db", "api://auth-58bfdecc-2870-4cda-99b4-1d30383b952b/b4ab3a28-16da-4a19-a07a-51ab0f3553db" ],API의 scope 및 scope에 동의할 수 있는 사용자를 정의합니다. Microsoft Entra 관리 센터의이 API에서 정의한 범위 섹션에서 + scope 추가를 선택합니다.
- scope 이름을 입력합니다. 이 필드는 필수 필드입니다.
- 이 scope에 대해 동의할 수 있는 사용자를 선택합니다. 기본 옵션은 관리자만입니다.
- 관리 동의 표시 이름을 입력합니다. 이 필드는 필수 필드입니다.
- 관리자 동의에 대한 설명을 입력합니다. 이 필드는 필수 필드입니다.
- 사용자 동의 표시 이름을 입력합니다.
- 사용자 동의 설명에 대한 설명을 입력합니다.
- 상태 필드에서 상태에 대한 사용 옵션을 선택합니다.
- Add scope를 선택합니다.
사전 권한을 부여하려는 애플리케이션에 대해 승인된 클라이언트 ID를 만듭니다. 이렇게 하면 앱 사용자가 추가 동의 없이 구성한 앱 범위(사용 권한)에 액세스할 수 있습니다. 앱 사용자는 동의를 거부할 기회가 없으므로 신뢰할 수 있는 클라이언트 애플리케이션만 사전 승인합니다.
Microsoft Entra 관리 센터의 권한 있는 클라이언트 애플리케이션 섹션에서 + 클라이언트 애플리케이션 추가를 선택합니다.
권한을 부여할 애플리케이션의 Microsoft 365 클라이언트 ID를 입력합니다.
토큰 검색 및 유효성 검사 논리 구현
액세스 토큰을 처리하는 코드를 추가하고, Authorization 헤더에서 앱의 서버 코드로 토큰을 보내고, 액세스 토큰을 받을 때 유효성을 검사합니다.
현재 앱 사용자에 대한 앱 액세스 권한을 얻으려면 클라이언트 쪽 코드가 Teams를 호출하여 액세스 토큰을 가져와야 합니다. 다음 예제와 같이 유효성 검사 프로세스를 시작하는 데 사용할 getAuthToken() 클라이언트 쪽 코드를 업데이트합니다.
// Get auth token
// Ask Teams to get us a token from AAD
function getClientSideToken() {
return new Promise((resolve, reject) => {
display("1. Get auth token from Microsoft Teams");
microsoftTeams.authentication.getAuthToken().then((result) => {
display(result);
resolve(result);
}).catch((error) => {
reject("Error getting token: " + error);
});
});
}
Teams는 액세스 토큰을 받으면 필요에 따라 재사용할 토큰을 캐시합니다. 토큰이 만료될 때까지 Microsoft Entra ID를 다시 호출할 필요 없이 호출될 때 getAuthToken() 토큰이 사용됩니다.
대화 상자에 대한 사용자 동의
전화를 걸 getAuthToken() 고 사용자 수준 권한에 대해 사용자의 동의가 필요한 경우 로그인한 사용자에게 Microsoft Entra 대화 상자가 표시되고 사용자는 초기 동의를 한 번 제공해야 합니다.
사용자가 동의하면 대화 상자 웹 페이지에 액세스할 수 있습니다. 사용자 동의에는 다음 사항이 적용됩니다.
- 관리자가 테넌트를 대신하여 동의를 부여한 경우 앱 사용자에게 동의 요청이 필요하지 않습니다. 즉, 앱 사용자는 동의 대화 상자를 볼 수 없으며 앱에 원활하게 액세스할 수 있습니다.
- Microsoft Entra 앱이 Teams에서 인증을 요청하는 동일한 테넌트에 등록된 경우 앱 사용자는 동의를 요청할 수 없으며 즉시 액세스 토큰이 부여됩니다. 앱 사용자는 Microsoft Entra 앱이 다른 테넌트에 등록된 경우에만 이러한 권한에 동의합니다.
- 사용자는 API 액세스에 대한 동의를 제공해야 하고 사용자당 한 번만 동의가 필요하므로 대화 상자에 대한 추가 동의가 필요하지 않습니다.
앱 매니페스트 업데이트
SSO를 사용하도록 앱 매니페스트 파일에서 webApplicationInfo 속성을 구성합니다. 이렇게 하면 에이전트 사용자가 에이전트에 원활하게 액세스할 수 있습니다. 다음 표에는 webApplicationInfo 속성의 속성이 나열되어 있습니다.
| 속성 | 설명 |
|---|---|
| 아이디 | Microsoft Entra ID에서 만든 앱 ID(GUID)를 입력합니다. |
| 리소스 | scope를 만들 때 Microsoft Entra ID에서 만든 앱의 하위 도메인 URI와 애플리케이션 ID URI를 입력합니다. |
"webApplicationInfo": {
"id": "7c7c79df-bf9d-43b7-a464-1cb9995eb3b2",
"resource": "api://67ec-4-213-76-42.ngrok-free.app/7c7c79df-bf9d-43b7-a464-1cb9995eb3b2"
}
다음 예제와 같이 앱 매니페스트의 validDomains 속성에 있는 대화 상자에서 렌더링할 URL의 도메인을 지정합니다.
"validDomains": [
"contoso.com",
"mysite.someplace.com",
"othersite.someplace.com"
]
OAuth 2.0 설정(미리 보기)
Microsoft Entra ID 또는 기타 ID 공급자와 함께 OAuth 2.0을 사용하는 에이전트의 경우 TeamsJS 라이브러리의 함수를 사용하여 authentication.authenticate() 인증 흐름을 시작합니다.
API 플러그인 대화 상자에 OAuth 2.0 권한 부여를 활성화하려면 다음을 수행합니다.
- Microsoft Entra ID를 ID 공급자로 사용하도록 앱을 구성합니다.
- 코드를 변경하여 인증 흐름을 시작하고 토큰을 처리합니다.
Microsoft Entra ID를 ID 공급자로 사용하도록 앱 구성
Microsoft Entra ID를 사용하도록 앱을 구성하려면 다음을 수행합니다.
- Azure Portal에서 앱 등록으로 이동합니다.
-
인증 아래의 리디렉션 URI 섹션에서 인증 끝점에 리디렉션 URL을 추가합니다. 리디렉션 URL
https://<hostname>/auth/simple-start에는 다음 형식을 사용합니다.
인증 흐름 시작 및 토큰 처리
대부분의 ID 공급자는 콘텐츠를 iframe에 배치하는 것을 허용하지 않습니다. 즉, Copilot이 팝업 창 내에 표시하는 ID 공급자를 호스트하는 페이지가 필요합니다. 적응형 카드 단추가 선택되면 TeamsJS 라이브러리의 기능을 사용하여 authentication.authenticate() 이 페이지를 시작합니다.
참고
전달 authenticate() 하는 URL은 인증 흐름의 시작 페이지입니다. Azure Portal에 등록한 것과 일치해야 합니다.
인증 흐름은 도메인의 페이지에서 시작해야 합니다. 매니페스트의 validDomains 속성에 이 도메인을 나열해야 합니다.
import { authentication } from "@microsoft/teams-js";
authentication.authenticate({
url: window.location.origin + "/auth/simple-start",
width: 600,
height: 535
})
.then((result) => {
console.log("Login succeeded: " + result);
let data = localStorage.getItem(result);
localStorage.removeItem(result);
let tokenResult = JSON.parse(data);
showIdTokenAndClaims(tokenResult.idToken);
getUserProfile(tokenResult.accessToken);
})
.catch((reason) => {
console.log("Login failed: " + reason);
handleAuthError(reason);
});
팝업 페이지는 사용자가 로그인할 수 있도록 ID 공급자로 리디렉션됩니다. 에이전트는 Microsoft Entra 권한 부여 서비스를 호출하고 사용자가 Entra ID에 인증할 수 있도록 사용자 및 앱 정보를 전달합니다. 그러면 Entra ID가 사용자가 제공한 콜백 페이지를 호출합니다.
app.getContext().then((context) => {
// Generate random state string and store it, so we can verify it in the callback
let state = _guid(); // _guid() is a helper function in the sample
localStorage.setItem("simple.state", state);
localStorage.removeItem("simple.error");
// Go to the Azure AD authorization endpoint
let queryParams = {
client_id: "{{appId}}",
response_type: "id_token token",
response_mode: "fragment",
scope: "https://graph.microsoft.com/User.Read openid",
redirect_uri: window.location.origin + "/auth/simple-end",
nonce: _guid(),
state: state,
// The context object is populated by Teams; the loginHint attribute
// is used as hinting information
login_hint: context.user.loginHint,
};
let authorizeEndpoint = `https://login.microsoftonline.com/${context.user.tenant.id}/oauth2/v2.0/authorize?${toQueryString(queryParams)}`;
window.location.assign(authorizeEndpoint);
});
Entra ID에서 반환된 정보에 따라 인증 요청의 성공 또는 실패를 확인하고 중 authentication.notifyFailure()하나를 authentication.notifySuccess() 호출합니다. 로그인에 성공하면 사용자는 서비스 리소스에 액세스할 수 있습니다.