Suporte de autenticação em TypeSpec para Microsoft 365 Copilot

Dica

Recomendado: Comece com o Work IQ Dev Tools para cenários de agente declarativo e plug-in pro-código suportados. Consulte o guia de início rápido do WIQD. As instruções baseadas em toolkits permanecem disponíveis para projetos e fluxos de trabalho existentes que o exigem. Verifique o suporte à capacidade e à experiência de destino antes de escolher uma ferramenta: o WIQD não tem como alvo agentes de mecanismo personalizados.

O TypeSpec for Microsoft 365 Copilot suporta vários métodos de autenticação para proteger plug-ins de API e integrar com serviços externos. Os tipos de autenticação suportados incluem:

Observação

Esta documentação abrange cenários de autenticação específicos Microsoft 365 Copilot. Para obter documentação abrangente de autenticação TypeSpec, incluindo todos os decoradores e padrões de autenticação nativos, consulte a documentação TypeSpec sobre autenticação.

Sem autenticação (anónimo)

Pontos finais públicos que não requerem credenciais de autenticação. A API não requer nada específico. Sem @useAuth decoradores, todas as APIs são consideradas anônimas.

Exemplo

@service
@actions(ACTIONS_METADATA)
@server(SERVER_URL, API_NAME)
namespace API {
  // Endpoints
}

Autenticação de chave de API

Autenticação usando chaves de API ou tokens de acesso pessoal aplicados a namespaces inteiros. Use o nativo ApiKeyAuth de TypeSpec.

Exemplo

@service
@actions(ACTIONS_METADATA)
@server(SERVER_URL, API_NAME)
@useAuth(ApiKeyAuth<ApiKeyLocation.header, "X-Your-Key">)
namespace API {
  // Endpoints
}

O Microsoft 365 Agents Toolkit pode registar automaticamente a sua chave API e também adiciona a apiKey/register ação para m365agents.yml no seu projeto Agents Toolkit.

# 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

O exemplo Gerenciar reparos usando Microsoft 365 Copilot mostra o uso da autenticação por chave de API.

Fluxo de código de autorização OAuth2

Permissões delegadas pelo utilizador para aceder aos dados do utilizador a partir de um serviço protegido por OAuth 2.0. Use o nativo OAuth2Auth de TypeSpec. Atualize o authorizationUrl, tokenUrl, refreshUrle scopes com base na API específica com a qual está a integrar.

Saiba como criar automaticamente o registro do aplicativo Microsoft Entra usando o Agents Toolkit e atualizar o registro do aplicativo Microsoft Entra quando o registro for concluído.

Exemplo

@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
}

O Agents Toolkit pode registrar automaticamente sua configuração OAuth2 e também adiciona a oauth/register ação para m365agents.yml em seu projeto do Agents Toolkit.

# 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

O Agente de Tarefas usando TypeSpec para Microsoft 365 Copilot que se conecta ao exemplo de APIs do Microsoft Graph destaca o uso de OAuth2 com fluxo de código de autorização.

Microsoft Entra autenticação SSO

Autenticação que aplica a sessão do Microsoft 365 existente do utilizador para cenários de integração nativa. Para concluir o registro SSO, use o fluxo regular OAuth2Auth e execute as etapas manuais.

Usando configurações de autenticação registradas

Em cenários de produção, registe e faça a gestão das credenciais de autenticação através do Portal do Programador do Microsoft Teams, em vez de as incorporar diretamente no código TypeSpec. Utilize o @authReferenceId decorador para referenciar configurações de autenticação pré-registadas através dos respetivos identificadores exclusivos. Essa abordagem fornece uma maneira segura de lidar com credenciais sem expor informações confidenciais em sua base de código.

Ao usar @authReferenceIdo , especifique a ID de registro dos registros de cliente OAuth ou registros de chave de API configurados no Portal do Desenvolvedor. Esta abordagem separa a configuração da autenticação do código, permitindo melhores práticas de segurança e uma gestão de credenciais mais fácil em diferentes ambientes.

Exemplo

// 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">