OAuth 2.0 인증 구성

팁

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

플러그 인은 기본적으로 사용하도록 설정된 PKCE(Proof Key for Code Exchange) 지원과 함께 OAuth 2.0 인증 코드 흐름을 통해 얻은 전달자 토큰을 사용하여 MCP(Model Context Protocol) 서버 또는 API에 액세스할 수 있습니다. 이 흐름에서 Microsoft 365 Copilot은 로그인 환경을 열고, OAuth 공급자는 Microsoft Teams에 권한 부여 응답을 반환하고, Teams는 토큰에 대한 권한 부여 코드를 교환합니다.

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

OAuth 클라이언트를 ID 공급자에 등록하고, 리디렉션 URI를 구성하고, OAuth 2.0 구성을 만드는 세 단계로 OAuth 2.0 인증을 구성합니다.

1단계: ID 공급자에 OAuth 클라이언트 등록

OAuth 2.0 공급자(ID 공급자)에 앱을 등록하여 클라이언트 ID 를 가져오고 기밀(웹) 클라이언트의 경우 클라이언트 암호를 가져옵니다. 3단계에서 OAuth 2.0 구성을 만들 때 이러한 값을 제공합니다.

권한 부여가 필요한 MCP 서버의 경우 런타임 인증 개체의 속성을 로 설정합니다type.OAuthPluginVault None 권한 ApiKeyPluginVault 부여가 필요한 MCP 서버에는 적용되지 않습니다. 인증 구성 ID만 매니페스트에 저장되며 클라이언트 ID, 클라이언트 암호 또는 토큰은 기록되지 않습니다. 클라이언트를 정적이 아닌 동적으로 등록하려면 DCR(동적 클라이언트 등록)을 통해 인증 구성을 유지하고 typeOAuthPluginVault 만듭니다. 이는 Microsoft Entra ID로 보호되는 서버에서는 사용할 수 없습니다.

참고

이러한 값은 선언적 에이전트 작업에 대한 MCP 플러그인 매니페스트에 적용됩니다. 대신 Microsoft 365 앱 매니페스트 OAuthPluginVault 를 통해 agentConnectors 플러그인의 원격 MCP 서버를 구성하는 경우 또는 DCRDynamicClientRegistration을 지원하는 서버에 대해 . 앱 매니페스트 스키마 1.29 및 1.30 AzureKeyVault에는 도 포함되어 있지만 스키마 수락은 대상 환경에서 지원을 설정하지 않습니다. 구성 및 호스트 요구 사항은 Microsoft 365 Copilot 플러그 인에 대한 원격 MCP 서버 구성을 참조하세요.

2단계: 리디렉션 URI 구성

OAuth 공급자 등록에 다음 리디렉션 URI(권한 부여 콜백 URL이라고도 함)를 추가합니다.

https://teams.microsoft.com/api/platform/v1.0/oAuthRedirect

사용자가 로그인한 후 OAuth 공급자가 권한 부여 응답을 보내는 URL입니다. Teams는 이 콜백 URL에서 응답을 받고 토큰에 대한 인증 코드를 교환합니다. 공급자에 이 리디렉션 URI를 등록하지 않으면 로그인에 실패합니다. 리디렉션 URI는 모든 플러그 인 및 공급자에 대해 동일합니다. - 앱별로 사용자 지정할 수는 없습니다.

3단계: OAuth 2.0 인증 구성 만들기

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

어떻게 만들든 인증 구성에는 플러그인 매니페스트에서 참조하는 인증 구성 ID 가 있습니다.

MCP 작업의 경우 및 --mcp-auth-type oauth와 함께 --mcp-server-url 사용합니다wiqd agent add action. 필요한 경우 --mcp-scopes및 를 --mcp-client-secret 통해 --mcp-client-id등록된 클라이언트의 세부 정보를 제공합니다. OpenAPI 작업의 경우 및 해당 --openapi-auth-client-id, --openapi-auth-client-secret, --openapi-auth-scopes 및 옵션을 사용합니다--openapi-auth-identity-provider oauth. 공급자가 지원하는 경우 해당 OpenAPI 경로 --openapi-auth-pkce 에 PKCE를 사용하도록 설정합니다. WIQD 작업 명령 지침을 참조하세요.

기존 플러그 인 매니페스트의 경우 , , --auth-name및 --auth-type oauth와 함께 --plugin-manifest사용합니다wiqd agent add auth. 해당 명령의 OAuth endpoint, scope 및 client 옵션을 사용합니다. PKCE 옵션은 --oauth-pkce입니다. 환경에 대한 프로젝트의 프로비저닝 워크플로를 완료합니다. 정적 OAuth 대신 자동 클라이언트 등록의 경우 WIQD DCR 경로를 따릅니다.

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

MCP 플러그 인을 사용하여 에이전트를 빌드하거나(서버에 인증이 필요한 경우) Microsoft 365 에이전트 도구 키트의 기존 OpenAPI 문서에서 API 플러그 인을 만들 때 도구 키트에서 OAuth 클라이언트 ID, 클라이언트 암호 및 범위를 묻는 메시지를 표시합니다. Agents Toolkit은 MCP 서버의 잘 알려진 엔드포인트(또는 API 플러그인용 OpenAPI 문서)에서 권한 부여, 토큰 및 새로 고침 엔드포인트를 가져오고, 엔터프라이즈 토큰 저장소에서 인증 구성을 만들고, 플러그인 매니페스트의 런타임 인증 개체 를 자동으로 업데이트합니다.

참고

API 플러그인의 경우 Agents Toolkit에서 OAuth 세부 정보를 읽을 수 있도록 OpenAPI 문서에서 속성을 정의 securitySchemes 해야 합니다. 자세한 내용은 OAuth 2.0을 참조하십시오.

securitySchemes:
  OAuth2:
    type: oauth2
    flows:
      authorizationCode:
        authorizationUrl: <authorization_url>
        tokenUrl: <token_url>
        refreshUrl: <refresh_url>
        scopes:
          scope: description

많은 조직에서 클라이언트 암호를 차단하기 때문에 PKCE는 기본적으로 사용하도록 설정됩니다. OAuth 공급자가 PKCE를 지원하지 않는 경우에만 에이전트를 프로비저닝하기 전에 에이전트 프로젝트에서 in m365agents.yml로 false 설정합니다isPKCEEnabled.

isPKCEEnabled: false

클라이언트 비밀을 완전히 방지하려면 웹 플랫폼이 아닌 단일 페이지 애플리케이션 플랫폼인 공용 클라이언트를 공급자에 등록하고 PKCE가 코드 교환을 보호하도록 합니다.

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

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

팁

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

Teams 개발자 포털 사용

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

Teams 개발자 포털의 OAuth 클라이언트 등록은 에이전트의 플러그인 구성을 MCP 서버 또는 API에 대한 토큰을 발급하는 OAuth 공급자 등록에 연결합니다. 이 등록의 값은 OAuth 공급자, 플러그인 매니페스트 및 보호된 API 엔드포인트와 일치해야 합니다. 기본 URL, 앱 제한 또는 인증 구성 ID가 일치하지 않으면 사용자가 로그인하지 못하거나 토큰 교환이 차단될 수 있습니다.

경고

등록을 모든 Teams 앱으로 제한합니다. 특정 Teams 앱으로 제한된 등록은 해당 Teams 앱 ID에 바인딩됩니다. Microsoft 365 Copilot은 MCP 서버를 호출할 때 해당 ID를 resolve 하지 않으므로 프로비전이 성공적으로 완료되면 모든 도구 호출이 오류를 반환합니다404.

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

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

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

    • 등록 이름: 등록에 대한 식별 이름입니다.
    • 기본 URL: API의 기본 URL입니다. 이 값은 MCP 기반 플러그인에 대한 플러그인 매니페스트에 있는 MCP 서버 사양 개체 속성의 url URL 또는 API 플러그인에 대한 OpenAPI 문서의 배열 항목 servers 에 해당해야 합니다.
    • 조직별 사용 제한: 이 OAuth 등록을 사용하여 API 엔드포인트에 액세스할 수 있는 Microsoft 365 조직을 선택합니다. 하나의 테넌트에서 개발 또는 테스트에만 My organization을 사용합니다. 플러그 인이 테넌트 간에 작동해야 하는 경우 Any Microsoft 365 organization을 사용합니다.
    • 앱별 사용 제한: 모든 Teams 앱을 선택합니다. MCP 서버의 기존 Teams 앱 ID 에 등록을 바인딩하지 마세요. 대신 Microsoft 365 에이전트 도구 키트를 사용하여 인증 구성을 프로비전하는 경우 m365agents.yml의 작업에서 oauth/register 해당하는 설정은 applicableToApps: AnyApp입니다. 비활성 요소가 되더라도 해당 작업 AnyApp 의 필드를 유지 appId 하십시오. 프로비저닝 드라이버가 무조건적으로 유효성을 검사하고 appId 이를 제거하면 프로비저닝이 중단되기 때문입니다.
    • 클라이언트 ID: OAuth 2.0 공급자가 발급한 클라이언트 ID 또는 애플리케이션 ID입니다.
    • 클라이언트 암호: OAuth 2.0 공급자가 발급한 클라이언트 암호입니다.
    • 인증 엔드포인트: 앱에서 인증 코드를 요청하는 데 사용하는 OAuth 2.0 공급자의 URL입니다.
    • 토큰 엔드포인트: 앱에서 액세스 토큰으로 코드를 사용하는 데 사용하는 OAuth 2.0 공급자의 URL입니다.
    • 엔드포인트 새로 고침: 앱에서 액세스 토큰을 새로 고치는 데 사용하는 OAuth 2.0 공급자의 URL입니다.
    • 범위: 플러그인이 OAuth 공급자에게 요청하는 권한입니다. 공급자 및 API에서 요구하는 scope 값을 사용합니다. 공급자가 Microsoft ID 플랫폼을 사용하고 플러그인에 새로 고침 토큰이 필요한 경우 API별 위임 범위에 포함 offline_access 합니다.
    • PKCE(코드 교환에 대한 증명 키) 사용: 이 설정을 사용하도록 둡니다. 기본적으로 켜져 있습니다. OAuth 공급자가 PKCE를 지원하지 않는 경우에만 사용하지 않도록 설정합니다.
  4. 저장을 선택합니다.

  5. 등록을 완료하면 인증 구성이 생성되고 인증 구성 ID (현재 Teams 개발자 포털에서 OAuth 클라이언트 등록 ID 로 레이블이 지정됨)가 생성됩니다.

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

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

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

Microsoft Entra ID 고려 사항

Microsoft Entra ID를 사용하여 MCP 서버를 보호하는 경우 도구에서 해결할 수 없는 세 가지 제약 조건이 적용됩니다.

  • 동적 클라이언트 등록을 사용할 수 없습니다. Microsoft Entra ID는 RFC 7591 등록 엔드포인트를 게시하지 않으므로 동적 클라이언트 등록에는 등록할 항목이 없습니다. 이 문서의 단계에 따라 OAuth 클라이언트를 정적으로 등록합니다.
  • 노드에 agentConnectors Microsoft Entra 권한 부여 유형이 없습니다. 달리 composeExtensions, Microsoft 365 앱 매니페스트의 노드에는 agentConnectors 권한 부여 유형이 없습니다 microsoftEntra . Microsoft Entra ID로 보호되는 MCP 서버에는 서버가 자사 Microsoft API를 사용하는 경우에도 항상 Microsoft Entra ID에 직접 등록하는 앱과 OAuth 인증 구성이 필요합니다.
  • 프로비전할 때 범위 동의가 확인되지 않습니다. 프로비전은 요청한 scope에 동의할 수 있는지 여부를 검사하지 않습니다. 프로비저닝에 동의할 수 없는 scope 나중에 관리자 승인 필요로 실패하고 리소스 앱은 사용자와 테넌트 관리자 모두에게 보이지 않을 수 있습니다. 프로비저닝하기 전에 관리자가 scope에 동의했는지 확인합니다.

인증 구성 관리

oauth/register m365agents.yml의 작업은 인증 구성을 만들거나 만들기를 건너뛰고 기존 레코드를 다시 작성하지 않습니다.

  • configurationId 이미 값이 있으면 아무 작업도 수행하지 않습니다.
  • 삭제한 등록을 가리키는 경우 configurationId 작업은 경고를 표시하고 아무 작업도 수행하지 않습니다.
  • 기존 등록의 값을 변경하려면 작업을 사용합니다.oauth/update
  • 등록을 삭제하려면 Teams 개발자 포털을 사용합니다. 삭제할 수 있는 유일한 위치입니다.

로그아웃하세요.

참고

사용자는 Chat 설정> 에이전트에서 Microsoft 365 Copilot에서 에이전트에서 로그아웃할 수 있습니다. 이 작업을 수행하면 저장된 OAuth 토큰이 지워집니다.