Compatibilidad con la 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:

• Sin autenticación para puntos de conexión públicos
• Autenticación de clave de API para un acceso simple basado en tokens
• Flujo de código de autorización de OAuth2 para integraciones seguras que no son de Microsoft
• Autenticación de inicio de sesión único (SSO) de Entra ID para la integración de identidades de Microsoft 365 sin problemas

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

Autenticación mediante claves de API o tokens de acceso personal aplicados a espacios de nombres completos. Use el nativo ApiKeyAuth de TypeSpec.

Ejemplo

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

Microsoft 365 Agents Toolkit puede registrar automáticamente la clave de API y también agregará la apiKey/register acción a m365agents.yml en el proyecto de 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

El ejemplo Administrar reparaciones mediante 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 de un servicio protegido de OAuth2. Use el nativo OAuth2Auth de TypeSpec. authorizationUrlActualice , tokenUrl, refreshUrly scopes en función de la API específica con la que se va a integrar.

Obtenga información sobre cómo crear automáticamente la aplicación Entra ID mediante Agents Toolkit y actualizar la aplicación Entra ID 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
}

Microsoft 365 Agents Toolkit puede registrar automáticamente la configuración de OAuth2 y también agregará la oauth/register acción a m365agents.yml en el proyecto del kit de herramientas 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

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

Autenticación de INICIO de sesión único de Entra ID

Autenticación sin problemas que aplica la sesión de Microsoft 365 existente del usuario para 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 el código TypeSpec. Use el @authReferenceId decorador para hacer referencia a las configuraciones de autenticación previamente registradas 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 identificador de registro de registros de cliente de OAuth o registros de claves 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 distintos 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">