팁
권장: 지원되는 프로 코드 선언적 에이전트 및 플러그인 시나리오에 대한 Work IQ Dev 도구 로 시작하십시오. WIQD 빠른 시작을 참조하세요. 도구 키트 기반 지침은 이를 필요로 하는 기존 프로젝트 및 워크플로에 계속 사용할 수 있습니다. 도구를 선택하기 전에 기능 및 대상 환경 지원을 확인하세요. WIQD는 사용자 지정 엔진 에이전트를 대상으로 하지 않습니다.
Microsoft 365 Copilot용 TypeSpec은 API 플러그 인을 보호하고 외부 서비스와 통합하기 위해 여러 인증 방법을 지원합니다. 지원되는 인증 유형은 다음과 같습니다.
- 퍼블릭 엔드포인트에 대한 인증 없음
- 간단한 토큰 기반 액세스를 위한 API 키 인증
- 안전한 타사 통합을 위한 OAuth2 인증 코드 흐름
- Microsoft 365 ID 통합을 위한 Microsoft Entra SSO(Single Sign-On) 인증
참고
이 설명서에서는 Microsoft 365 Copilot별 인증 시나리오를 다룹니다. 모든 네이티브 인증 데코레이터 및 패턴을 포함하는 포괄적인 TypeSpec 인증 설명서는 인증에 대한 TypeSpec 설명서를 참조하세요.
인증 없음(익명)
인증 자격 증명이 필요하지 않은 퍼블릭 엔드포인트입니다. API에는 특정 항목이 필요하지 않습니다. 데코레이터가 없으면 @useAuth 모든 API가 익명으로 간주됩니다.
예제
@service
@actions(ACTIONS_METADATA)
@server(SERVER_URL, API_NAME)
namespace API {
// Endpoints
}
API 키 인증
전체 네임스페이스에 적용되는 API 키 또는 개인용 액세스 토큰을 사용한 인증입니다. TypeSpec의 네이티브 ApiKeyAuth 를 사용합니다.
예제
@service
@actions(ACTIONS_METADATA)
@server(SERVER_URL, API_NAME)
@useAuth(ApiKeyAuth<ApiKeyLocation.header, "X-Your-Key">)
namespace API {
// Endpoints
}
Microsoft 365 에이전트 도구 키트는 API 키를 자동으로 등록하고 에이전트 도구 키트 프로젝트의 m365agents.yml에 작업을 추가할 apiKey/register 수도 있습니다.
# m365agents.yml
# After the typespec/compile step
- uses: apiKey/register
with:
name: ApiKeyAuth
appId: ${{TEAMS_APP_ID}}
apiSpecPath: ./appPackage/.generated/api-openapi.yml
writeToEnvironmentFile:
registrationId: APIKEYAUTH_REGISTRATION_ID
Microsoft 365 Copilot을 사용하여 수리 관리 샘플에서는 API 키 인증의 사용을 강조 표시합니다.
OAuth2 인증 코드 흐름
OAuth 2.0으로 보호된 서비스에서 사용자 데이터에 액세스하기 위한 사용자 위임 권한입니다. TypeSpec의 네이티브 OAuth2Auth 를 사용합니다. 통합하는 특정 API에 따라 , tokenUrl, refreshUrl, 및 scopes 를 authorizationUrl업데이트합니다.
에이전트 도구 키트를 사용하여 Microsoft Entra 앱 등록을 자동으로 만들고 등록이 완료되면 Microsoft Entra 앱 등록을 업데이트하는 방법을 알아봅니다.
예제
@service
@actions(ACTIONS_METADATA)
@server(SERVER_URL, API_NAME)
@useAuth(OAuth2Auth<[{
type: OAuth2FlowType.authorizationCode;
authorizationUrl: "https://contoso.com/oauth2/v2.0/authorize";
tokenUrl: "https://contoso.com/oauth2/v2.0/token";
refreshUrl: "https://contoso.com/oauth2/v2.0/token";
scopes: ["scope-1", "scope-2"];
}]>)
namespace API {
// Endpoints
}
Agents Toolkit은 OAuth2 구성을 자동으로 등록할 수 있으며 Agents Toolkit 프로젝트의 m365agents.yml에 작업을 추가할 oauth/register 수도 있습니다.
# m365agents.yml
# After the typespec/compile step
- uses: oauth/register
with:
name: OAuth2Auth
appId: ${{TEAMS_APP_ID}}
clientId: ${{AAD_APP_CLIENT_ID}}
clientSecret: ${{SECRET_AAD_APP_CLIENT_SECRET}}
apiSpecPath: ./appPackage/.generated/api-openapi.yml
flow: authorizationCode
writeToEnvironmentFile:
configurationId: OAUTH2AUTH_REGISTRATION_ID
Microsoft Graph API 샘플에 연결하는 Microsoft 365 Copilot용 TypeSpec을 사용하는 작업 에이전트는 권한 부여 코드 흐름에서 OAuth2를 사용하는 방법을 강조합니다.
Microsoft Entra SSO 인증
네이티브 통합 시나리오에 사용자의 기존 Microsoft 365 세션을 적용하는 인증입니다. SSO 등록을 완료하려면 일반 OAuth2Auth 흐름을 사용하고 수동 단계를 수행합니다.
등록된 인증 구성 사용
프로덕션 시나리오의 경우 인증 자격 증명을 TypeSpec 코드에 직접 포함하는 대신 Microsoft Teams 개발자 포털을 통해 등록하고 관리합니다. 데코레이터를 @authReferenceId 사용하여 고유 식별자로 사전 등록된 인증 구성을 참조합니다. 이 접근 방식은 코드베이스에서 중요한 정보를 노출하지 않고 자격 증명을 처리하는 안전한 방법을 제공합니다.
사용하는 @authReferenceId경우 개발자 포털에 구성된 OAuth 클라이언트 등록 또는 API 키 등록에서 등록 ID를 지정합니다. 이 접근 방식은 인증 구성을 코드와 분리하여 다양한 환경에서 더 나은 보안 사례와 보다 쉬운 자격 증명 관리를 가능하게 합니다.
예제
// Reference to OAuth2 client registration
@service
@actions(ACTIONS_METADATA)
@server(SERVER_URL, API_NAME)
@useAuth(Auth)
namespace API {
// Endpoints
}
@authReferenceId("NzFmOTg4YmYtODZmMS00MWFmLTkxYWItMmQ3Y2QwMTFkYjQ3IyM5NzQ5Njc3Yi04NDk2LTRlODYtOTdmZS1kNDUzODllZjUxYjM=")
model Auth is OAuth2Auth<[{
type: OAuth2FlowType.authorizationCode;
authorizationUrl: "https://contoso.com/oauth2/v2.0/authorize";
tokenUrl: "https://contoso.com/oauth2/v2.0/token";
refreshUrl: "https://contoso.com/oauth2/v2.0/token";
scopes: ["scope-1", "scope-2"];
}]>
// Reference to API key registration
@service
@actions(ACTIONS_METADATA)
@server(SERVER_URL, API_NAME)
@useAuth(Auth)
namespace API {
// Endpoints
}
@authReferenceId("5f701b3e-bf18-40fb-badd-9ad0b60b31c0")
model Auth is ApiKeyAuth<ApiKeyLocation.header, "X-Your-Key">