Soporte de autenticación en TypeSpec para Microsoft 365 Copilot

TypeSpec para Microsoft 365 Copilot admite varios métodos de autenticación para proteger los complementos de API e integrarlos con servicios externos. Los tipos de autenticación admitidos incluyen:

Nota:

Esta documentación abarca los escenarios de autenticación específicos de Microsoft 365 Copilot. Para obtener una documentación completa de autenticación de TypeSpec, incluidos todos los decoradores y patrones de autenticación nativos, consulte la documentación de TypeSpec sobre autenticación.

Sin autenticación (anónimo)

Puntos de conexión públicos que no requieren credenciales de autenticación. La API no requiere nada específico. Sin @useAuth decoradores, todas las API se consideran anónimas.

Ejemplo

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

Autenticación de clave de API

La autenticación mediante claves de API o tokens de acceso personal aplicados a espacios de nombres completos. Utilice lo nativo ApiKeyAuth de TypeSpec.

Ejemplo

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

El Kit de herramientas de agentes de Microsoft 365 puede registrar automáticamente la clave de API y también agrega la acción a m365agents.yml en el proyecto del Kit de herramientas para apiKey/register 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

El ejemplo Administrar reparaciones con Microsoft 365 Copilot resalta el uso de la autenticación de clave de API.

Flujo de código de autorización de OAuth2

Permisos delegados por el usuario para acceder a los datos de usuario desde un servicio protegido por OAuth 2.0. Utilice lo nativo OAuth2Auth de TypeSpec. Actualice el authorizationUrl, tokenUrl, refreshUrl, y scopes en función de la API específica con la que se esté integrando.

Obtenga información sobre cómo crear automáticamente el registro de la aplicación Microsoft Entra mediante Agents Toolkit y actualizar el registro de la aplicación Microsoft Entra una vez completado el registro.

Ejemplo

@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 puede registrar automáticamente su configuración de OAuth2 y también añade la oauth/register acción a m365agents.yml en su proyecto de 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

El agente de tareas que usa TypeSpec para Microsoft 365 Copilot que se conecta a la muestra de las API de Microsoft Graph resalta el uso de OAuth2 con el flujo de código de autorización.

Autenticación SSO de Microsoft Entra

Autenticación que aplica la sesión de Microsoft 365 existente del usuario a escenarios de integración nativa. Para completar el registro de SSO, use el flujo normal OAuth2Auth y realice los pasos manuales.

Uso de configuraciones de autenticación registradas

Para escenarios de producción, registre y administre las credenciales de autenticación a través del Portal para desarrolladores de Microsoft Teams en lugar de insertarlas directamente en código TypeSpec. Utilice el @authReferenceId decorador para hacer referencia a configuraciones de autenticación registradas previamente por sus identificadores únicos. Este enfoque proporciona una manera segura de controlar las credenciales sin exponer información confidencial en el código base.

Cuando use @authReferenceId, especifique el id. de registro de los registros de cliente OAuth o los registros de clave de API configurados en el Portal para desarrolladores. Este enfoque separa la configuración de autenticación del código, lo que permite mejores prácticas de seguridad y una administración de credenciales más sencilla en diferentes entornos.

Ejemplo

// 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">
  • Se actualizó por última vez el