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

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

• Sem autenticação para pontos de extremidade públicos
• Autenticação de chave de API para acesso simples baseado em token
• Fluxo de código de autorização OAuth2 para integrações seguras que não são da Microsoft
• Autenticação de logon único (SSO) do Entra ID para integração perfeita de identidade do Microsoft 365

Sem autenticação (anônimo)

Pontos de extremidade públicos que não exigem 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 do 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 registrar automaticamente sua chave de API e também adicionará a apiKey/register ação ao m365agents.yml em 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 o Microsoft 365 Copilot destaca o uso da autenticação de chave de API.

Fluxo de código de autorização OAuth2

Permissões delegadas pelo usuário para acessar dados do usuário a um serviço protegido por OAuth2. Use o nativo OAuth2Auth do TypeSpec. Atualize o authorizationUrl, tokenUrl, refreshUrle scopes com base na API específica com a qual você está integrando.

Saiba como criar automaticamente o aplicativo Entra ID usando o Agents Toolkit e atualizar o aplicativo Entra ID assim que 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 Microsoft 365 Agents Toolkit pode registrar automaticamente sua configuração OAuth2 e também adicionará a oauth/register ação ao m365agents.yml em seu projeto 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 o Microsoft 365 Copilot que se conecta ao exemplo de APIs do Microsoft Graph destaca o uso do OAuth2 com o fluxo de código de autorização.

Autenticação SSO de ID de Entrada

Autenticação contínua aplicando a sessão existente do Microsoft 365 do usuário para cenários de integração nativa. Para concluir o registro do SSO, use o fluxo regular OAuth2Auth e execute as etapas manuais.

Usando configurações de autenticação registrada

Para cenários de produção, registre e gerencie as credenciais de autenticação por meio do Portal do Desenvolvedor do Microsoft Teams em vez de incorporá-las diretamente no código TypeSpec. Use o @authReferenceId decorador para fazer referência a configurações de autenticação pré-registradas por seus 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 @authReferenceId, especifique a ID de registro dos registros de cliente OAuth ou dos registros de chave de API configurados no Portal do desenvolvedor. Essa abordagem separa a configuração de autenticação do código, permitindo melhores práticas de segurança e gerenciamento 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">