Archivo de configuración de la biblioteca de autenticación de Microsoft para Android

Artículo
04/10/2024

La biblioteca de autenticación de Microsoft para Android (MSAL) se suministra con un archivo JSON de configuración predeterminada que se personaliza a fin de definir el comportamiento de la aplicación cliente pública para elementos como la autoridad predeterminada, las autoridades que se van a utilizar, etc.

Este artículo le ayudará a comprender los distintos valores del archivo de configuración y a especificar el archivo de configuración que utilizará en la aplicación basada en MSAL.

Parámetros de configuración

Configuración general

Propiedad	Tipo de datos	Obligatorio	Notas
`client_id`	String	Sí	Identificador de cliente de la aplicación de la página Registros de aplicaciones
`redirect_uri`	String	Sí	URI de redireccionamiento de la aplicación de la página Registros de aplicaciones
`broker_redirect_uri_registered`	Boolean	No	Valores posibles: `true`, `false`
`authorities`	List<Authority>	No	Lista de autoridades que la aplicación necesita
`authorization_user_agent`	AuthorizationAgent (enum)	No	Valores posibles: `WEBVIEW`, `BROWSER`
`http`	HttpConfiguration	No	Configure `HttpUrlConnection` `connect_timeout` y `read_timeout`.
`logging`	LoggingConfiguration	No	Especifica el nivel de detalle del registro. Entre las configuraciones opcionales se incluyen: `pii_enabled`, que toma un valor booleano, y `log_level`, que toma `ERROR`, `WARNING`, `INFO` o `VERBOSE`.

client_id

Identificador de cliente o identificador de aplicación creado al registrar la aplicación.

redirect_uri

URI de redireccionamiento registrado al registrar la aplicación. Si el URI de redireccionamiento es a una aplicación de agente, consulte URI de redireccionamiento para aplicaciones cliente públicas a fin de asegurarse de que está usando el formato de URI de redireccionamiento correcto para la aplicación de agente.

broker_redirect_uri_registered

Si quiere utilizar la autenticación con agente, la propiedad broker_redirect_uri_registered debe establecerse en true. En un escenario de autenticación con agente, si la aplicación no tiene el formato correcto para comunicarse con el agente tal y como se describe en URI de redirección para aplicaciones cliente públicas, la aplicación valida el URI de redirección y emite una excepción cuando se inicia.

autoridades

Lista de autoridades que conoce y en las que confía. Además de las autoridades aquí mencionadas, MSAL también consulta a Microsoft para obtener una lista de las nubes y autoridades que conoce Microsoft. En esta lista de autoridades, especifique el tipo de autoridad y cualquier parámetro opcional adicional, como "audience", que se debe adaptar a la audiencia de la aplicación en función del registro de la aplicación. A continuación se muestra una lista de autoridades de ejemplo:

// Example AzureAD and Personal Microsoft Account
{
    "type": "AAD",
    "audience": {
        "type": "AzureADandPersonalMicrosoftAccount"
    },
    "default": true // Indicates that this is the default to use if not provided as part of the acquireToken call
},
// Example AzureAD My Organization
{
    "type": "AAD",
    "audience": {
        "type": "AzureADMyOrg",
        "tenant_id": "contoso.com" // Provide your specific tenant ID here
    }
},
// Example AzureAD Multiple Organizations
{
    "type": "AAD",
    "audience": {
        "type": "AzureADMultipleOrgs"
    }
},
//Example PersonalMicrosoftAccount
{
    "type": "AAD",
    "audience": {
        "type": "PersonalMicrosoftAccount"
    }
}

Asignación de una autoridad de Microsoft Entra y audiencia a puntos de conexión de la Plataforma de identidad de Microsoft

Tipo	Público	Id. de inquilino	Authority_Url	Punto de conexión resultante	Notas
Microsoft Entra ID	AzureADandPersonalMicrosoftAccount			`https://login.microsoftonline.com/common`	`common` es un alias de inquilino de donde se encuentra la cuenta. Por ejemplo, un inquilino de Microsoft Entra específico o el sistema de cuentas de Microsoft.
Microsoft Entra ID	AzureADMyOrg	contoso.com		`https://login.microsoftonline.com/contoso.com`	Solo las cuentas presentes en contoso.com pueden adquirir un token. Cualquier dominio comprobado, o el GUID del inquilino, se puede usar como identificador de inquilino.
Microsoft Entra ID	AzureADMultipleOrgs			`https://login.microsoftonline.com/organizations`	Con este punto de conexión solo se pueden usar cuentas de Microsoft Entra. Las cuentas de Microsoft pueden ser miembros de organizaciones. Para adquirir un token mediante un cuenta de Microsoft para un recurso de una organización, especifique el inquilino de la organización del que desea el token.
Microsoft Entra ID	PersonalMicrosoftAccount			`https://login.microsoftonline.com/consumers`	Solo las cuentas de Microsoft pueden usar este punto de conexión.
B2C			Consulte Punto de conexión resultante	`https://login.microsoftonline.com/tfp/contoso.onmicrosoft.com/B2C_1_SISOPolicy/`	Solo las cuentas presentes en el inquilino contoso.onmicrosoft.com pueden adquirir un token. En este ejemplo, la directiva de B2C forma parte de la ruta de la dirección URL de la autoridad.

Nota:

No se puede habilitar ni deshabilitar la validación de la autoridad en MSAL. Las autoridades son conocidas por usted como el desarrollador tal como se especifica mediante la configuración o son conocidas por Microsoft mediante metadatos. Si MSAL recibe una solicitud de un token para una autoridad desconocida, se produce una MsalClientException de tipo UnknownAuthority. La autenticación con agente no funciona para Azure AD B2C.

Propiedades de la autoridad

Propiedad	Tipo de datos	Obligatorio	Notas
`type`	String	Sí	Refleja la audiencia o el tipo de cuenta a la que se dirige la aplicación. Valores posibles: `AAD`, `B2C`
`audience`	Object	No	Solo se aplica cuando type=`AAD`. Especifica la identidad a la que se dirige la aplicación. Utilice el valor del registro de la aplicación
`authority_url`	String	Sí	Solo es necesario cuando type=`B2C`. Opcional para type=`AAD`. Especifica la dirección URL de la autoridad o la directiva que debe usar la aplicación.
`default`	boolean	Sí	Se requiere un único `"default":true` cuando se especifica una o varias autoridades.

Propiedades de la audiencia

Propiedad	Tipo de datos	Obligatorio	Notas
`type`	String	Sí	Especifica la audiencia a la que la aplicación quiere dirigirse. Valores posibles: `AzureADandPersonalMicrosoftAccount`, `PersonalMicrosoftAccount`, `AzureADMultipleOrgs`, `AzureADMyOrg`
`tenant_id`	String	Sí	Solo es necesario cuando `"type":"AzureADMyOrg"`. Opcional para otros valores `type`. Puede ser un dominio de inquilino como `contoso.com` o un identificador de inquilino como `aaaabbbb-0000-cccc-1111-dddd2222eeee`

authorization_user_agent

Indica si se va a usar un WebView incrustado, o el explorador predeterminado en el dispositivo, al iniciar sesión en una cuenta o al autorizar el acceso a un recurso.

Valores posibles:

WEBVIEW: Utiliza el objeto WebView insertado.
BROWSER: Usa el explorador predeterminado en el dispositivo.

multiple_clouds_supported

Para clientes que admiten varias nubes nacionales, especifique true. La Plataforma de identidad de Microsoft se redirigirá automáticamente a la nube nacional correcta durante la autorización y el canje de tokens. Puede determinar la nube nacional de la cuenta con la que se ha iniciado sesión examinando la autoridad asociada con AuthenticationResult. Tenga en cuenta que AuthenticationResult no proporciona la dirección del punto de conexión nacional específica de la nube del recurso para el que solicita un token.

broker_redirect_uri_registered

Valor booleano que indica si está usando un URI de redireccionamiento de agente compatible con el agente de identidad de Microsoft. Establézcalo en false si no desea usar el agente en la aplicación.

Si utiliza la autoridad de Microsoft Entra con la audiencia establecida en "MicrosoftPersonalAccount", no se usará el agente.

http

Configure los valores globales para los tiempos de espera de HTTP, como:

Propiedad	Tipo de datos	Obligatorio	Notas
`connect_timeout`	int	No	Tiempo en milisegundos
`read_timeout`	int	No	Tiempo en milisegundos

logging

La siguiente configuración global es para el registro:

Propiedad	Tipo de datos	Obligatorio	Notas
`pii_enabled`	boolean	No	Si se van a emitir datos personales
`log_level`	string	No	Qué mensajes de registro se van a generar. Entre los niveles de registro se incluyen `ERROR`,`WARNING`,`INFO` y `VERBOSE`.
`logcat_enabled`	boolean	No	Indica si se va a generar el catálogo de registros, además de la interfaz de registro

account_mode

Especifica el número de cuentas que se pueden usar en la aplicación a la vez. Los valores posibles son:

MULTIPLE (Valor predeterminado)
SINGLE

Si se construye PublicClientApplication mediante un modo de cuenta que no coincide con esta configuración, se producirá una excepción.

Para más información sobre las diferencias entre una o varias cuentas, consulte Single and multiple account apps (Aplicaciones de una o varias cuentas).

browser_safelist

Lista de exploradores permitidos que son compatibles con MSAL. Estos exploradores controlan correctamente los redireccionamientos a intentos personalizados. Puede agregar elementos a esta lista. El valor predeterminado se proporciona en la configuración predeterminada que se muestra a continuación. ``

Archivo de configuración de MSAL predeterminado

A continuación se muestra la configuración predeterminada de MSAL que se incluye con MSAL. Puede ver la versión más reciente en GitHub.

Esta configuración se complementa con los valores que proporcione. Los valores que proporcione invalidan los valores predeterminados.

{
  "authorities": [
    {
      "type": "AAD",
      "audience": {
        "type": "AzureADandPersonalMicrosoftAccount"
      },
      "default": true
    }
  ],
  "authorization_user_agent": "DEFAULT",
  "multiple_clouds_supported": false,
  "broker_redirect_uri_registered": false,
  "http": {
    "connect_timeout": 10000,
    "read_timeout": 30000
  },
  "logging": {
    "pii_enabled": false,
    "log_level": "WARNING",
    "logcat_enabled": false
  },
  "shared_device_mode_supported": false,
  "account_mode": "MULTIPLE",
  "browser_safelist": [
    {
      "browser_package_name": "com.android.chrome",
      "browser_signature_hashes": [
        "aB1cD2eF3gH4iJ5kL6-mN7oP8qR=="
      ],
      "browser_use_customTab" : true,
      "browser_version_lower_bound": "45"
    },
    {
      "browser_package_name": "com.android.chrome",
      "browser_signature_hashes": [
        "cD2eF3gH4iJ5kL6mN7-oP8qR9sT=="
      ],
      "browser_use_customTab" : false
    },
    {
      "browser_package_name": "org.mozilla.firefox",
      "browser_signature_hashes": [
        "eF3gH4iJ5kL6mN7oP8-qR9sT0uV=="
      ],
      "browser_use_customTab" : false
    },
    {
      "browser_package_name": "org.mozilla.firefox",
      "browser_signature_hashes": [
        "gH4iJ5kL6mN7oP8qR9-sT0uV1wX=="
      ],
      "browser_use_customTab" : true,
      "browser_version_lower_bound": "57"
    },
    {
      "browser_package_name": "com.sec.android.app.sbrowser",
      "browser_signature_hashes": [
        "iJ5kL6mN7oP8qR9sT0-uV1wX2yZ=="
      ],
      "browser_use_customTab" : true,
      "browser_version_lower_bound": "4.0"
    },
    {
      "browser_package_name": "com.sec.android.app.sbrowser",
      "browser_signature_hashes": [
        "kL6mN7oP8qR9sT0uV1-wX2yZ3aB=="
      ],
      "browser_use_customTab" : false
    },
    {
      "browser_package_name": "com.cloudmosa.puffinFree",
      "browser_signature_hashes": [
        "mN7oP8qR9sT0uV1wX2-yZ3aB4dE="
      ],
      "browser_use_customTab" : false
    },
    {
      "browser_package_name": "com.duckduckgo.mobile.android",
      "browser_signature_hashes": [
        "S5Av4...jAi4Q=="
      ],
      "browser_use_customTab" : false
    },
    {
      "browser_package_name": "com.explore.web.browser",
      "browser_signature_hashes": [
        "BzDzB...YHCag=="
      ],
      "browser_use_customTab" : false
    },

    {
      "browser_package_name": "com.ksmobile.cb",
      "browser_signature_hashes": [
        "lFDYx...7nouw=="
      ],
      "browser_use_customTab" : false
    },

    {
      "browser_package_name": "com.microsoft.emmx",
      "browser_signature_hashes": [
        "Ivy-R...A6fVQ=="
      ],
      "browser_use_customTab" : false
    },

    {
      "browser_package_name": "com.opera.browser",
      "browser_signature_hashes": [
        "FIJ3I...jWJWw=="
      ],
      "browser_use_customTab" : false
    },

    {
      "browser_package_name": "com.opera.mini.native",
      "browser_signature_hashes": [
        "TOTyH...mmUYQ=="
      ],
      "browser_use_customTab" : false
    },

    {
      "browser_package_name": "mobi.mgeek.TunnyBrowser",
      "browser_signature_hashes": [
        "RMVoXgjjgyjjmbj4578fcbkyyQ=="
      ],
      "browser_use_customTab" : false
    },

    {
      "browser_package_name": "org.mozilla.focus",
      "browser_signature_hashes": [
        "L72dT...q0oYA=="
      ],
      "browser_use_customTab" : false
    }
  ]
}

Ejemplo de configuración básica

En el ejemplo siguiente se muestra una configuración básica que especifica el identificador de cliente, el URI de redireccionamiento, si se ha registrado un redireccionamiento de agente y una lista de autoridades.

{
  "client_id" : "00001111-aaaa-2222-bbbb-3333cccc4444",
  "redirect_uri" : "msauth://com.microsoft.identity.client.sample.local/1wIqXSqBj7w%2Bh11ZifsnqwgyKrY%3D",
  "broker_redirect_uri_registered": true,
  "authorities" : [
    {
      "type": "AAD",
      "audience": {
        "type": "AzureADandPersonalMicrosoftAccount"
      }
      "default": true
    }
  ]
}

Uso de un archivo de configuración

Cree un archivo de configuración. Se recomienda crear un archivo de configuración predeterminado en res/raw/auth_config.json. Pero puede colocarlo en cualquier lugar que desee.

Indique a MSAL dónde debe buscar la configuración al construir PublicClientApplication. Por ejemplo:

//On Worker Thread
IMultipleAccountPublicClientApplication sampleApp = null; 
sampleApp = new PublicClientApplication.createMultipleAccountPublicClientApplication(getApplicationContext(), R.raw.auth_config);

Compartir a través de

Archivo de configuración de la biblioteca de autenticación de Microsoft para Android

Parámetros de configuración

Configuración general

client_id

redirect_uri

broker_redirect_uri_registered

autoridades

Asignación de una autoridad de Microsoft Entra y audiencia a puntos de conexión de la Plataforma de identidad de Microsoft

Propiedades de la autoridad

Propiedades de la audiencia

authorization_user_agent

multiple_clouds_supported

broker_redirect_uri_registered

http

logging

account_mode

browser_safelist

Archivo de configuración de MSAL predeterminado

Ejemplo de configuración básica

Uso de un archivo de configuración

Comentarios

Recursos adicionales