Configurar la autenticación en su agente

El paquete de la Biblioteca de autenticación de Microsoft (MSAL) del SDK de agentes de .NET le proporciona herramienta que le ayuda a crear tokens de acceso para clientes de agente y servicios externos desde un agente autohospedado del SDK de Microsoft 365 Agents.

El paquete Microsoft.Agents.Athentication.Msal proporciona la clase MsalAuth, que es el proveedor de autenticación principal. Puede configurarlo para los siguientes tipos de credenciales:

• Inquilino único con secreto de cliente y multiinquilino con secreto de cliente
• Certificado de cliente mediante huella digital
• Certificado de cliente mediante el nombre del asunto (incluido SN+I)
• Identidad administrada asignada a usuario
• Identidad administrada asignada por el sistema
• Credenciales federadas
• Identidad de carga de trabajo

Instalar el paquete de autenticación

Instale el paquete de autenticación MSAL desde NuGet:

dotnet add package Microsoft.Agents.Authentication.Msal

Inquilino único frente a multiempresa

La autenticación con secreto de cliente admite configuraciones tanto de inquilino único como de varios inquilinos.

Configurar una conexión de

El paquete de autenticación MSAL permite crear y usar varios clientes distintos con el motor de hospedaje de Agents Framework. Con el paquete de autenticación MSAL, se pueden definir varios configuraciones de conexión en el archivo de configuración de la aplicación. Cada configuración de conexión puede usarse para crear un cliente de autenticación con nombre que permita comunicaciones con servicios externos u otros agentes.

Variables de entorno para cada tipo de autenticación

El agente obtiene la configuración de MSAL en tiempo de ejecución a partir de variables de entorno.

A continuación se describen las configuraciones obligatorias y opcionales para cada uno de los tipos de autenticación compatibles con MSAL, junto con ejemplos de fragmentos de configuración para cada tipo.

Inquilino único con secreto de cliente

Utilice estos parámetros para establecer una conexión de inquilino único que se autentique con un secreto de cliente.

Este es un ejemplo de appsettings para único inquilino ClientSecret:

  "Connections": {
    "ServiceConnection": {
      "Settings": {
        "AuthType": "ClientSecret",
        "ClientId": "{{BOT_ID}}",
        "ClientSecret": "{{BOT_SECRET}}",
        "AuthorityEndpoint": "https://login.microsoftonline.com/{{BOT_TENANT_ID}}",
        "Scopes": [
            "https://api.botframework.com/.default"
          ],
      }
    }
  }

Multiempresa con secreto de cliente

Utilice estos parámetros de configuración para establecer una conexión multiinquilino que utiliza un secreto de cliente para autenticarse.

Aquí tiene un ejemplo de appsettings para multiempresa con secreto de cliente:

  "Connections": {
    "ServiceConnection": {
      "Settings": {
        "AuthType": "ClientSecret",
        "ClientId": "{{BOT_ID}}",
        "ClientSecret": "{{BOT_SECRET}}",
        "AuthorityEndpoint": "https://login.microsoftonline.com/botframework.com",
        "Scopes": [
            "https://api.botframework.com/.default"
          ],
      }
    }
  }

Identidad administrada asignada a usuario

Utilice estos parámetros para configurar la adquisición de tokens con una identidad administrada asignada por el usuario.

Este es un ejemplo de appsettings para Identidad administrada asignada por el usuario:

  "Connections": {
    "ServiceConnection": {
      "Settings": {
        "AuthType": "UserManagedIdentity",
        "ClientId": "{{BOT_ID}}",
        "Scopes": [
          "https://api.botframework.com/.default"
        ]
      }
    }
  }

Identidad administrada asignada por el sistema

Cuando usa SystemManagedIdentity, el agente ignora cualquier id. de cliente proporcionado y utiliza la identidad administrada por el sistema.

Este es un ejemplo de appsettings para el tipo de autenticación de identidad administrada System-Assigned:

  "Connections": {
    "ServiceConnection": {
      "Settings": {
        "AuthType": "SystemManagedIdentity",
        "Scopes": [
          "https://api.botframework.com/.default"
        ]
      }
    }
  }

Credenciales federadas

Utilice estos parámetros para configurar una conexión que intercambie credenciales federadas por tokens de acceso.

Este es un ejemplo de appsettings para Federated Credentials:

  "Connections": {
    "ServiceConnection": {
      "Settings": {
        "AuthType": "FederatedCredentials",
        "ClientId": "{{BOT_ID}}",
        "AuthorityEndpoint": "https://login.microsoftonline.com/{{BOT_TENANT_ID}}",
        "FederatedClientId": "{{BOT_FEDERATED_ID}}",
        "Scopes": [
          "https://api.botframework.com/.default"
        ]
      }
    }
  }

Identidad de carga de trabajo

Utilice estas opciones para configurar la autenticación de identidad de carga de trabajo mediante un archivo de token federado.

Este es un ejemplo de appsettings para único inquilino WorkloadIdentity:

  "Connections": {
    "ServiceConnection": {
      "Settings": {
        "AuthType": "WorkloadIdentity",
        "ClientId": "{{BOT_ID}}",
        "AuthorityEndpoint": "https://login.microsoftonline.com/{{BOT_TENANT_ID}}",
        "FederatedTokenFile": "{{BOT_FEDERATED_TOKENFILE}}",
        "Scopes": [
          "https://api.botframework.com/.default"
        ]
      }
    }
  }

Opciones opcionales de aserción de cliente de credenciales federadas o identidad de carga de trabajo

Utilice estas opciones opcionales para personalizar el contenido de la aserción del cliente en los flujos de credenciales federadas o identidad de carga de trabajo.

  "Connections": {
    "ServiceConnection": {
      "Settings": {
        "AuthType": "WorkloadIdentity",
        "ClientId": "{{BOT_ID}}",
        "AuthorityEndpoint": "https://login.microsoftonline.com/{{BOT_TENANT_ID}}",
        "FederatedTokenFile": "{{BOT_FEDERATED_TOKENFILE}}",
        "Scopes": [
          "https://api.botframework.com/.default"
        ],
        "AssertionRequestOptions": {
            "ClientId": null,
            "TokenEndpoint": null,
            "Claims": null,
            "ClientCapabilities": null,
        }
      }
    }
  }

Certificado mediante el nombre del asunto (incluido SN+I)

Utilice estos ajustes para configurar la autenticación basada en certificados por nombre del asunto, incluidos los escenarios SN+I.

Este es un ejemplo de appsettings para un certificado que usa el nombre del sujeto para Nombre de asunto y emisor (SNI) y para varios inquilinos:

  "Connections": {
    "ServiceConnection": {
      "Settings": {
        "AuthType": "CertificateSubjectName",
        "ClientId": "{{BOT_ID}}",
        "CertSubjectName": "{{BOT_CERT_SUBJECTNAME}}",
        "SendX5C": true,
        "AuthorityEndpoint": "https://login.microsoftonline.com/botframework.com",
        "Scopes": [
          "https://api.botframework.com/.default"
        ]
      }
    }
  },

Aquí tiene un ejemplo de appsettings para el nombre del sujeto del certificado para SN+I y un solo inquilino:

  "Connections": {
    "ServiceConnection": {
      "Settings": {
        "AuthType": "CertificateSubjectName",
        "ClientId": "{{BOT_ID}}",
        "CertSubjectName": "{{BOT_CERT_SUBJECTNAME}}",
        "SendX5C": true,
        "AuthorityEndpoint": "https://login.microsoftonline.com/{{BOT_TENANT_ID}}",
        "Scopes": [
          "https://api.botframework.com/.default"
        ]
      }
    }
  },

Certificado de cliente mediante huella digital

Utilice estos ajustes para configurar la autenticación basada en certificados mediante la huella digital del certificado.

Este es un ejemplo de appsettings para el certificado usando la huella digital del certificado:

  "Connections": {
    "ServiceConnection": {
      "Settings": {
        "AuthType": "Certificate",
        "ClientId": "{{BOT_ID}}",
        "CertThumbprint": "{{BOT_CERT_THUMBPRINT}}",
        "AuthorityEndpoint": "https://login.microsoftonline.com/botframework.com",
        "Scopes": [
          "https://api.botframework.com/.default"
        ]
      }
    }
  },

Proveedor de configuración predeterminado para MSAL

Para facilitar la configuración, proporcionamos una extensión del proveedor de servicios para agregar las opciones de configuración predeterminadas de MSAL al agente.

Este es un ejemplo del proveedor de configuración de MSAL predeterminado para un host principal de ASP.NET en una clase Program.cs.

Esto se administra mediante la instancia registrada IConnections. De manera predeterminada, se agrega la instancia de IConnections cuando usa AddAgent.

// Register your AgentApplication
builder.AddAgent<MyAgent>();

Sin embargo, si no está usando AddAgent, tiene que registrar explícitamente la instancia de IConnections.

    // Add Connections object to access configured token connections.
    builder.Services.AddSingleton<IConnections, ConfigurationConnections>();

Más opciones de configuración de MSAL

Hay varias opciones de configuración compartidas que controlan la configuración general para adquirir tokens de Microsoft Entra Identity.

Estos valores son:

Utilice las siguientes configuraciones compartidas para controlar el tiempo de espera de las solicitudes MSAL, el comportamiento de reintentos y el nivel de detalle del registro.

Esta configuración se comparte con todos los clientes que crean mediante el proveedor de autenticación msal. Estas opciones están pensadas para leerse desde un lector de IConfiguration, en una sección de configuración, una sección denominada "MSALConfiguration".

Este es un ejemplo de la entrada en un archivo appsettings.json:

{
  "MSALConfiguration": {
    "MSALEnabledLogPII": "true",
    "MSALRequestTimeout": "00:00:40",
    "MSALRetryCount": "1"
  },
}

En este caso, este bloque de configuración indicaría a todos los clientes MSAL creados con el proveedor MSAL que habilitaran el registro de datos personales, establecerían el tiempo de espera en 40 segundos y reducirían el número de reintentos a 1.

Esta extensión busca una sección de configuración denominada "MSALConfiguration" en su objeto IConfiguration y crea un objeto de configuración de MSAL a partir de él.

Si no se encuentra la sección MSALConfig, crea el objeto de configuración de MSAL con valores predeterminados.

    // Add default agent MsalAuth support
    builder.Services.AddDefaultMsalAuth(builder.Configuration);

    // Register your AgentApplication
    builder.AddAgent<MyAgent>();

Compatibilidad con el registro para la autenticación

El sistema de autenticación MSAL permite el registro independiente de flujos de autenticación para la integración de telemetría si necesita solucionar problemas de adquisición de tokens.

Para habilitar el registro, agregue una entrada para Microsoft.Agents.Authentication.Msal en la configuración de la aplicación para configurar un ILogger que notifique las operaciones de tokens de sus conexiones. Si agrega la opción MSALEnabledLogPII, esto también incluye datos personales de su conexión.

Este es un ejemplo del bloque de registro en este caso:

  "Logging": {
    "LogLevel": {
      "Default": "Warning",
      "Microsoft.Agents": "Warning",
      "Microsoft.Hosting.Lifetime": "Information",
      "Microsoft.Agents.Authentication.Msal": "Trace"
    }
  }

En este caso, el registro está habilitado para varios módulos, como Microsoft.Agents.Authentication.Msal, donde el nivel de seguimiento es "Seguimiento" para MSAL.

El SDK de JavaScript requiere un AuthenticationProvider para obtener JSON Web Tokens (JWT) y enviar actividades al canal objetivo. Para obtener más información, consulte Tokens de acceso de la plataforma de identidad de Microsoft.

El paquete @microsoft/agents-hosting proporciona un proveedor de autenticación predeterminado basado en la Biblioteca de autenticación de Microsoft (MSAL). Puede configurarlo para los siguientes tipos de autenticación:

• Inquilino único con secreto de cliente
• Multiempresa con secreto de cliente
• Identidad administrada del usuario
• Identidad administrada del sistema
• Credenciales federadas
• Identidad de carga de trabajo
• Certificado

Instalar el paquete de autenticación

Instale el paquete de autenticación MSAL usando npm:

npm install @microsoft/agents-hosting

Inquilino único frente a multiempresa

La autenticación mediante secreto de cliente y certificado de cliente admite configuraciones de inquilino único y multiempresa.

User Assigned Managed Identity, System Managed Identity, Federated Credentials y Workload Identity solo admiten configuraciones de inquilino único.

Configurar una conexión de

La biblioteca de autenticación MSAL le permite crear y usar varios clientes distintos con el motor de hospedaje de Agents Framework. Utilizando la biblioteca de autenticación MSAL, se pueden proporcionar múltiples configuraciones de conexión en el archivo de configuración de la aplicación. Cada configuración de conexión puede crear un cliente de autenticación con nombre para facilitar las comunicaciones con servicios externos u otros agentes.

Las siguientes secciones describen los parámetros de configuración requeridos y opcionales para cada uno de los tipos de autenticación admitidos por el proveedor de autenticación MSAL. También incluyen ejemplos de fragmentos de configuración para cada tipo.

Variables de entorno para cada tipo de autenticación

El agente obtiene la configuración de MSAL en tiempo de ejecución desde variables de entorno utilizando la función auxiliar loadAuthConfigFromEnv(): AuthConfiguration. El CloudAdapter se inicializa con el AuthConfiguration.

La configuración de conexión utiliza el formato CONNECTIONS__<CONNECTION_NAME>__SETTINGS__<PROPERTY>.

Cuando AUTHTYPE está presente, el SDK utiliza ese valor para seleccionar el flujo de adquisición del token. Cuando se omite AUTHTYPE, el SDK vuelve al comportamiento heredado e infiere el flujo de autenticación a partir de las propiedades configuradas de la credencial.

Inquilino único con secreto de cliente

Utilice estos parámetros para establecer una conexión de inquilino único que se autentique con un secreto de cliente.

CONNECTIONS__SERVICE_CONNECTION__SETTINGS__AUTHTYPE=ClientSecret
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID={app-id-guid}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTSECRET={app-registration-secret}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID={tenant-id-guid}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__SCOPE=https://api.botframework.com

La configuración recomendada para el desarrollo local es un único inquilino con secreto del cliente.

Multiempresa con secreto de cliente

Para escenarios multiempresas que usan un secreto de cliente, establezca el punto de conexión de la autoridad en el inquilino botframework.com:

CONNECTIONS__SERVICE_CONNECTION__SETTINGS__AUTHTYPE=ClientSecret
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID={app-id-guid}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTSECRET={app-registration-secret}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__AUTHORITY=https://login.microsoftonline.com/botframework.com
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__SCOPE=https://api.botframework.com

UserManagedIdentity

Utilice estos ajustes para configurar la adquisición de tokens con una identidad administrada asignada por el usuario

CONNECTIONS__SERVICE_CONNECTION__SETTINGS__AUTHTYPE=UserManagedIdentity
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID={managed-identity-client-id}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__SCOPE=https://api.botframework.com

Identidad administrada es la configuración recomendada para escenarios de producción. Para más información, consulte Identidades administradas para recursos de Azure.

SystemManagedIdentity

Si usa el tipo de autenticación SystemManagedIdentity, se omite el id. de cliente y se usa la identidad administrada del sistema para el servicio.

CONNECTIONS__SERVICE_CONNECTION__SETTINGS__AUTHTYPE=SystemManagedIdentity
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__SCOPE=https://api.botframework.com

FederatedCredentials

Utilice estos ajustes para configurar una aplicación de un solo inquilino que se autentique mediante credenciales federadas.

CONNECTIONS__SERVICE_CONNECTION__SETTINGS__AUTHTYPE=FederatedCredentials
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID={app-id-guid}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID={tenant-id-guid}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__AUTHORITY=https://login.microsoftonline.com/{tenant-id-guid}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__FICCLIENTID={managed-identity-client-id}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__SCOPE=https://api.botframework.com

Para más información, consulte Autenticación mediante credenciales de identidad federada.

WorkloadIdentity

Use estos ajustes para configurar la adquisición de tokens a través de la identidad de carga de trabajo de Microsoft Entra.

CONNECTIONS__SERVICE_CONNECTION__SETTINGS__AUTHTYPE=WorkloadIdentity
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID={app-id-guid}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID={tenant-id-guid}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__AUTHORITY=https://login.microsoftonline.com/{tenant-id-guid}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__FEDERATEDTOKENFILE=/var/run/secrets/azure/tokens/azure-identity-token
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__SCOPE=https://api.botframework.com

Inquilino único con certificado de cliente

Utilice estos parámetros para establecer una conexión de inquilino único que se autentique con un certificado de cliente.

CONNECTIONS__SERVICE_CONNECTION__SETTINGS__AUTHTYPE=Certificate
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID={app-id-guid}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID={tenant-id-guid}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CERTPEMFILE={path-to-pem-file}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CERTKEYFILE={path-to-key-file}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__SCOPE=https://api.botframework.com

Multiempresa con certificado de cliente

Para escenarios multiempresas que usan un certificado de cliente, establezca el punto de conexión de la autoridad en el inquilino botframework.com:

CONNECTIONS__SERVICE_CONNECTION__SETTINGS__AUTHTYPE=Certificate
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID={app-id-guid}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CERTPEMFILE={path-to-pem-file}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CERTKEYFILE={path-to-key-file}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__AUTHORITY=https://login.microsoftonline.com/botframework.com
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__SCOPE=https://api.botframework.com

Compatibilidad con versiones anteriores con SDK de Azure Bot Framework

Para cargar la configuración utilizando el mismo formato que el SDK de Azure Bot Framework, utilice loadPrevAuthConfigFromEnv(): AuthConfiguration.

Utiliza estos nombres de configuración heredados al migrar configuraciones existentes del SDK de Bot Framework.

MicrosoftAppTenantId={tenant-id-guid}
MicrosoftAppId={app-id-guid}
MicrosoftAppPassword={app-registration-secret}

Proveedor de autenticación personalizado

Los usuarios que requieran un proveedor de autenticación personalizado pueden implementar la interfaz:

export interface AuthProvider {
  getAccessToken: (authConfig: AuthConfiguration, scope: string) => Promise<string>
}

Como ejemplo, implemente el AuthProvider usando @azure/identity:

import { EnvironmentCredential } from "@azure/identity"
import { AuthProvider, AuthConfiguration } from "@microsoft/agents-hosting"
class DevTokenProvider implements AuthProvider {
  async getAccessToken(authConfig: AuthConfiguration): Promise<string> {
    const id = new EnvironmentCredential()
    const tokenResponse = await id.getToken("https://api.botframework.com/.default")
    return tokenResponse.token
  }

Para crear instancias el CloudAdapter utilizando el DevTokenProvider

const adapter = new CloudAdapter(authConfig, new DevTokenProvider())

amework.com/.default") devuelve tokenResponse.token }

To instantiate the `CloudAdapter` by using the `DevTokenProvider`

```ts
const adapter = new CloudAdapter(authConfig, new DevTokenProvider())

El paquete de la Biblioteca de autenticación de Microsoft (MSAL) de agentes de Python le proporciona herramientas que le ayuda a crear tokens de acceso para clientes de agente y servicios externos desde un agente autohospedado del SDK de Microsoft 365 Agents.

El paquete microsoft-agents-authentication-msal proporciona la clase MsalAuth, que es el proveedor de autenticación principal. Puede configurarlo para los siguientes tipos de credenciales:

• Secreto del cliente
• Certificado de cliente
• Identidad administrada asignada a usuario
• Identidad administrada asignada por el sistema

Instalar el paquete de autenticación

Instale el paquete de autenticación MSAL desde PyPI:

pip install microsoft-agents-authentication-msal

Inquilino único frente a multiempresa

La autenticación mediante secreto de cliente y certificado de cliente admite configuraciones de inquilino único y multiempresa.

Identidad administrada asignada por el usuario e Identidad administrada asignada por el sistema solo admiten configuraciones de inquilino único.

Configurar una conexión de

La biblioteca de autenticación MSAL permite crear y usar varios clientes distintos con el motor de hospedaje de Agents Framework. Cada configuración de conexión crea un cliente de autenticación con nombre para facilitar las comunicaciones con servicios externos u otros agentes.

Proporcione la configuración mediante variables de entorno que utilicen la convención de nombres de doble guion bajo (__) para ajustes anidados. La clase MsalConnectionManager lee estas variables para construir instancias de AgentAuthConfiguration para cada conexión nombrada.

Variables de entorno para cada tipo de autenticación

El agente obtiene la configuración de MSAL en tiempo de ejecución a partir de variables de entorno utilizando la función auxiliar load_configuration_from_env().

Las siguientes secciones describen los ajustes de configuración requeridos para cada uno de los tipos de autenticación admitidos, junto con fragmentos de variables de entorno de ejemplo para cada tipo.

Inquilino único con secreto de cliente

Utilice estos parámetros para establecer una conexión de inquilino único que se autentique con un secreto de cliente.

CONNECTIONS__SERVICE_CONNECTION__SETTINGS__AUTHTYPE=ClientSecret
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID={app-id-guid}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTSECRET={app-registration-secret}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID={tenant-id-guid}

La configuración recomendada para el desarrollo local es un único inquilino con secreto del cliente.

Multiempresa con secreto de cliente

Para escenarios multiempresas que usan un secreto de cliente, establezca el punto de conexión de la autoridad en el inquilino botframework.com:

CONNECTIONS__SERVICE_CONNECTION__SETTINGS__AUTHTYPE=ClientSecret
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID={app-id-guid}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTSECRET={app-registration-secret}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__AUTHORITY=https://login.microsoftonline.com/botframework.com

Identidad administrada asignada a usuario

Utilice estos parámetros para configurar la adquisición de tokens con una identidad administrada asignada por el usuario.

CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID={managed-identity-client-id}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__AUTHTYPE=UserManagedIdentity

Identidad administrada es la configuración recomendada para escenarios de producción. Para más información, consulte Identidades administradas para recursos de Azure.

Identidad administrada asignada por el sistema

Si usa el tipo de autenticación SystemManagedIdentity, se omite el id. de cliente y se usa la identidad administrada del sistema para el servicio.

CONNECTIONS__SERVICE_CONNECTION__SETTINGS__AUTHTYPE=SystemManagedIdentity

Inquilino único con certificado de cliente

Utilice estos parámetros para establecer una conexión de inquilino único que se autentique con un certificado de cliente.

CONNECTIONS__SERVICE_CONNECTION__SETTINGS__AUTHTYPE=certificate
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID={app-id-guid}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID={tenant-id-guid}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CERTPEMFILE={path-to-pem-file}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CERTKEYFILE={path-to-key-file}

Multiempresa con certificado de cliente

Para escenarios multiempresas que usan un certificado de cliente, establezca el punto de conexión de la autoridad en el inquilino botframework.com:

CONNECTIONS__SERVICE_CONNECTION__SETTINGS__AUTHTYPE=certificate
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID={app-id-guid}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CERTPEMFILE={path-to-pem-file}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CERTKEYFILE={path-to-key-file}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__AUTHORITY=https://login.microsoftonline.com/botframework.com

Configurar el administrador de conexiones

La clase MsalConnectionManager puede administrar varias conexiones de autenticación para su agente. Lee las configuraciones de conexión y crea instancias de MsalAuth para cada conexión identificada por nombre.

A continuación se muestra un ejemplo de cómo configurar el administrador de conexiones e iniciar su agente:

from os import environ

from microsoft_agents.hosting.aiohttp import start_agent_process, CloudAdapter
from microsoft_agents.hosting.core import Authorization, AgentApplication, TurnState, MemoryStorage

from dotenv import load_dotenv
from aiohttp.web import Request, Response, Application, run_app
from microsoft_agents.authentication.msal import MsalConnectionManager
from microsoft_agents.activity import load_configuration_from_env

def start_server(
    agent_application: AgentApplication, auth_configuration: AgentAuthConfiguration
):
    async def entry_point(req: Request) -> Response:
        agent: AgentApplication = req.app["agent_app"]
        adapter: CloudAdapter = req.app["adapter"]
        return await start_agent_process(req, agent, adapter)

    APP = Application()
    APP.router.add_post("/api/messages", entry_point)
    APP["agent_configuration"] = auth_configuration
    APP["agent_app"] = agent_application
    APP["adapter"] = agent_application.adapter

    try:
        run_app(APP, host="localhost", port=environ.get("PORT", 3978))
    except Exception as error:
        raise error

load_dotenv()
agents_sdk_config = load_configuration_from_env(environ)

STORAGE = MemoryStorage()
CONNECTION_MANAGER = MsalConnectionManager(**agents_sdk_config)
ADAPTER = CloudAdapter(connection_manager=CONNECTION_MANAGER)
AUTHORIZATION = Authorization(STORAGE, CONNECTION_MANAGER, **agents_sdk_config)

AGENT_APP = AgentApplication[TurnState](
    storage=STORAGE, adapter=ADAPTER, authorization=AUTHORIZATION, **agents_sdk_config
)

start_server(
    agent_application=AGENT_APP, auth_configuration=CONNECTION_MANAGER.get_default_connection_configuration()
)

Consulte la muestra de inicio rápido de Python para obtener un ejemplo completo de cómo usar el MsalConnectionManager en un agente de Python.

Proveedor de autenticación personalizado

Los usuarios que necesitan un proveedor de autenticación personalizado pueden implementar la clase base AccessTokenProviderBase:

from microsoft_agents.hosting.core import AccessTokenProviderBase

class CustomAuthProvider(AccessTokenProviderBase):
    async def get_access_token(
        self, resource_url: str, scopes: list[str], force_refresh: bool = False
    ) -> str:
        # Implement custom token acquisition logic
        token = await your_custom_token_logic(resource_url, scopes)
        return token

Compatibilidad con el registro para la autenticación

El sistema de autenticación MSAL utiliza el módulo estándar de Python logging bajo el nombre de registro microsoft_agents.authentication.msal. Para habilitar el registro detallado de los flujos de autenticación para solucionar problemas en la adquisición de tokens, configure el registrador en su aplicación:

import logging

logging.basicConfig(level=logging.WARNING)
logging.getLogger("microsoft_agents.authentication.msal").setLevel(logging.DEBUG)