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

O TypeSpec para 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:

• Sem autenticação para pontos finais públicos
• Autenticação de chave de API para acesso simples baseado em tokens
• Fluxo de código de autorização OAuth2 para integrações seguras que não sejam da Microsoft
• Autenticação de início de sessão único (SSO) do Entra ID para integração de identidade totalmente integrada do Microsoft 365

Sem autenticação (anónimo)

Pontos finais públicos que não necessitam de 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 da chave de API

Autenticação com chaves de API ou tokens de acesso pessoal aplicados a espaços de nomes inteiros. Utilize 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 Toolkit de Agentes do Microsoft 365 pode registar automaticamente a sua chave de API e também adicionará a apiKey/register ação a m365agents.yml no projeto Do Toolkit de Agentes.

# 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 Gerir reparações com Microsoft 365 Copilot realça a utilização da autenticação da chave de API.

Fluxo de código de autorização OAuth2

Permissões delegadas pelo utilizador para aceder a dados de utilizadores de um serviço protegido OAuth2. Utilize o nativo OAuth2Auth de TypeSpec. Atualize a authorizationUrl, tokenUrl, refreshUrle scopes com base na API específica com a qual está a integrar.

Saiba como criar automaticamente a aplicação Entra ID com o Toolkit de Agentes e atualizar a aplicação Entra ID assim que o registo estiver 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 Toolkit de Agentes do Microsoft 365 pode registar automaticamente a configuração do OAuth2 e também adicionará a oauth/register ação a m365agents.yml no projeto Do Toolkit de Agentes.

# 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 que utiliza o TypeSpec para Microsoft 365 Copilot que se liga ao exemplo de APIs do Microsoft Graph destaca a utilização do OAuth2 com o fluxo de código de autorização.

Autenticação do SSO do Entra ID

Autenticação totalmente integrada ao aplicar a sessão existente do Microsoft 365 do utilizador para cenários de integração nativos. Para concluir o registo do SSO, utilize o fluxo normal OAuth2Auth e execute os passos manuais.

Utilizar configurações de autenticação registadas

Para 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 pelos identificadores exclusivos. Esta abordagem fornece uma forma segura de processar credenciais sem expor informações confidenciais na sua base de código.

Quando utilizar @authReferenceIdo , especifique o ID de registo dos registos de cliente OAuth ou dos registos de chaves de API configurados no Portal do Programador. Esta abordagem separa a configuração de autenticação do código, permitindo melhores práticas de segurança e 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">