Microsoft Entra SSO 인증 구성

팁

권장: 지원되는 프로 코드 선언적 에이전트 및 플러그인 시나리오에 대한 Work IQ Dev 도구 로 시작하십시오. WIQD 빠른 시작을 참조하세요. 도구 키트 기반 지침은 이를 필요로 하는 기존 프로젝트 및 워크플로에 계속 사용할 수 있습니다. 도구를 선택하기 전에 기능 및 대상 환경 지원을 확인하세요. WIQD는 사용자 지정 엔진 에이전트를 대상으로 하지 않습니다.

Microsoft Entra SSO(Single Sign-On) 인증을 통해 사용자는 기존 Microsoft Entra ID 자격 증명으로 인증할 수 있습니다. 이 통합은 액세스 관리를 단순화하고 추가 자격 증명 없이 MCP(Model Context Protocol) 서버 또는 API에 대한 보안 연결을 보장합니다. MCP 서버 또는 API는 Entra ID를 사용하여 액세스를 제어해야 합니다.

이 문서에서는 MCP 플러그인을 기본 연습으로 사용합니다. 명시된 부분을 제외하고 OpenAPI 문서에서 빌드된 API 플러그인에도 동일한 단계가 적용됩니다.

MCP 서버를 보호하기 위한 Entra 앱을 등록하고, 인증 구성을 만들고, Entra 앱 등록을 업데이트하고, API에 새 토큰 대상 그룹을 추가하는 네 단계로 Entra SSO 인증을 구성합니다.

1단계: MCP 서버를 보호하기 위해 Entra 앱 등록

MCP 서버 또는 API는 Entra 앱 등록으로 보호되어야 합니다. 아직 앱이 없는 경우 Microsoft Entra 관리 센터에서 앱을 등록합니다. 앱의 클라이언트 ID 를 기록해 둡니다 . 2단계에서 인증 구성을 만들 때 제공합니다.

2단계: Entra SSO 인증 구성 만들기

Entra SSO 인증은 Microsoft 365 Copilot이 MCP 플러그 인에 대한 토큰을 가져오는 데 사용하는 Microsoft Enterprise 토큰 저장소에 저장된 레코드인 인증 구성(인증 구성)에 의존합니다. 지원되는 프로 코드 프로젝트에 대해 WIQD로 시작합니다. 도구 키트, 개발자 기술 및 Teams 개발자 포털 절차를 대안으로 계속 사용할 수 있습니다.

어떻게 만들든 인증 구성에는 인증 구성 ID 와 애플리케이션 ID URI가 있습니다. 3단계와 4단계에서애플리케이션 ID URI를 사용합니다.

중요

인증 구성을 만드는 방법에 관계없이 3단계 와 4단계를 완료해야 합니다.

MCP 작업의 경우 와 함께 --mcp-server-url사용하고 wiqd agent add action--mcp-auth-type entra-sso1 --mcp-client-id 단계에서 Entra 앱의 클라이언트 ID로 설정합니다. OpenAPI 작업의 경우 및 --openapi-auth-client-id를 사용합니다--openapi-auth-identity-provider microsoft-entra. 다른 필수 작업 옵션은 WIQD 작업 명령 지침을 참조하세요.

기존 플러그 인 매니페스트의 경우 , , --auth-name및 --auth-type microsoft-entra와 함께 --plugin-manifest사용합니다wiqd agent add auth. 다음을 포함하여 --oauth-client-id해당 명령에 대해 문서화된 ID 공급자 옵션을 제공합니다. 프로젝트의 프로비저닝 워크플로를 완료하고, 인증 구성의 애플리케이션 ID URI를 얻은 다음, 3단계와 4단계를 계속 진행합니다.

Microsoft 365 에이전트 도구 키트 사용

Microsoft 365 에이전트 도구 키트에서 MCP 플러그 인을 사용하여 에이전트를 빌드할 때 MCP 서버 플러그 인을 추가할 때 도구 키트에서 인증 유형을 묻는 메시지를 표시합니다. Microsoft Entra SSO를 선택하고 1단계에서 Entra 앱의 클라이언트 ID를 제공합니다. Agents Toolkit은 엔터프라이즈 토큰 저장소에서 인증 구성을 생성하고, 인증 구성 ID를 생성하고, 플러그인 매니페스트에서 런타임 인증 개체 를 자동으로 업데이트합니다.

선언적 에이전트 개발자 기술 사용

선언적 에이전트 개발자 기술(declarative-agent-developer)은 선언적 에이전트를 빌드하는 데 필요한 지식을 패키지화한 Microsoft Work IQ 의 에이전트 기술입니다. 명령을 실행하거나 매니페스트를 직접 편집하는 대신 Copilot 또는 GitHub CLI에 원하는 내용을 자연어로 설명합니다. 이 기술은 선언적 에이전트를 스캐폴딩하고, MCP 플러그인을 추가하고, 인증 구성을 처리합니다. 이 기술은 MCP 플러그인만 지원합니다. Entra SSO를 사용하는 MCP 서버를 추가하면 기술이 엔터프라이즈 토큰 저장소에서 인증 구성을 생성하고 수동 단계 없이 플러그인 매니페스트를 업데이트합니다.

팁

선언적 에이전트 개발자 기술 사용에 대한 비디오 안내는 선언적 에이전트 개발자 기술로 선언적 에이전트 빌드를 참조하세요.

Teams 개발자 포털 사용

에이전트 도구 키트 또는 선언적 에이전트 개발자 기술을 사용하는 경우 Teams 개발자 포털에 등록하는 것은 선택 사항입니다. 인증 구성을 수동으로 생성하거나 보다 일반적으로 에이전트 도구 키트 또는 기술이 이미 생성한 인증 구성을 관리하려는 경우에 사용합니다. 포털에서 인증 구성을 특정 Teams 앱 또는 Microsoft 365 organization으로 제한하고 다른 속성을 수정할 수 있습니다.

  1. Teams 개발자 포털을 엽니다. 도구 선택 ->Microsoft Entra SSO 클라이언트 ID 등록.

  2. 기존 등록이 없는 경우 클라이언트 ID 등록을 선택합니다. 기존 등록이 있는 경우 새 클라이언트 등록을 선택합니다.

  3. 다음 필드를 입력합니다.

    • 등록 이름: 등록에 대한 식별 이름입니다.
    • 기본 URL: API의 기본 URL입니다. 이 값은 MCP 기반 플러그인에 대한 플러그인 매니페스트에 있는 MCP 서버 사양 개체 속성의 url URL 또는 API 플러그인에 대한 OpenAPI 문서의 배열 항목 servers 에 해당해야 합니다.
    • 조직별 사용 제한: API 엔드포인트에 액세스하기 위해 앱에 액세스할 수 있는 Microsoft 365 organization을 선택합니다.
    • 앱별 사용 제한: 최종 앱 ID를 모르는 경우 모든 Teams 앱을 선택합니다. 앱을 게시한 후 이 등록을 게시된 앱 ID와 바인딩합니다.
    • 클라이언트 ID: Entra에 등록된 앱의 클라이언트 ID입니다.
    • 범위: 플러그인이 Entra에 요청하는 권한입니다. OAuth 2.0과 마찬가지로 Entra 앱 및 API에 필요한 scope 값을 사용합니다.
  4. 저장을 선택합니다.

  5. 등록을 완료하면 인증 구성이 생성되고 인증 구성 ID(현재 Teams 개발자 포털에서 Microsoft Entra SSO 등록 ID로 레이블이 지정됨) 및 애플리케이션 ID URI가 생성됩니다.

플러그 인 매니페스트에 인증 구성 ID 추가

Teams 개발자 포털에서 수동으로 인증 구성을 만들 때 런타임 인증 개체의 속성을 로 설정 type 하고 OAuthPluginVault인증 구성 ID로 설정합니다reference_id. 에이전트 도구 키트 및 선언적 에이전트 개발자 기술이 이를 수행합니다.

"auth": {
  "type": "OAuthPluginVault",
  "reference_id": "auth config ID"
},

3단계: Entra 앱 등록 업데이트

2단계에서 인증 구성을 만든 방법에 관계없이 다음 단계를 완료합니다.

  1. Microsoft Entra 관리 센터를 엽니다. SSO 등록의 애플리케이션 ID URI를 사용하여 MCP 서버 또는 API를 보호하는 Entra 앱 등록을 업데이트합니다. 앱 등록에 매핑된 기존 애플리케이션 ID URI가 있는 경우 매니페스트 편집기를 사용하여 identifierUris 섹션에 다른 URI를 추가합니다.

    "identifierUris": [
      "<<URI1>>",
      "<<URI2>>"
    ]
    

    참고

    Entra 관리 센터의 UI를 통해 여러 URI를 추가할 수 없습니다. UI는 목록의 첫 번째 URI만 표시합니다. 여러 URI를 추가해도 기존 URI 및 범위가 UI에서 다르게 표시되더라도 영향을 주지 않습니다.

  2. 관리에서 인증을 선택합니다. 웹 플랫폼의 리디렉션 URI에 추가합니다https://teams.microsoft.com/api/platform/v1.0/oAuthConsentRedirect.

  3. 관리에서 API 노출을 선택합니다. 클라이언트 애플리케이션 추가를 선택하고 Microsoft Enterprise 토큰 저장소ab3be6b7-f5df-413d-ac2d-abf1e3fd9c0b의 클라이언트 ID를 추가합니다.

4단계: API에 새 토큰 대상 그룹 추가

새 식별자 URI를 토큰 대상 그룹으로 허용하도록 MCP 서버 또는 API를 업데이트합니다. MCP 서버 또는 API가 클라이언트 응용 프로그램 ID의 유효성을 검사하는 경우 Microsoft Enterprise 토큰 저장소의 클라이언트 ID(ab3be6b7-f5df-413d-ac2d-abf1e3fd9c0b)가 허용된 클라이언트 응용 프로그램으로 추가되었는지 확인합니다.

팁

MCP 서버 또는 API가 대 리 흐름 을 사용하여 사용자가 동의해야 하는 다른 웹 API에 액세스하는 경우 에이전트가 사용자에게 동의하기 위해 로그인하라는 메시지를 표시하는 오류를 반환 401 Unauthorized 합니다.