Arquivo de configuração da Biblioteca de Autenticação Microsoft do Android

Artigo
04/10/2024

A Biblioteca de Autenticação Microsoft (MSAL) do Android é fornecida com um arquivo JSON de configuração padrão que você personaliza para definir o comportamento do seu aplicativo cliente público para coisas como a autoridade padrão, quais autoridades você usará e assim por diante.

Este artigo irá ajudá-lo a entender as várias configurações no arquivo de configuração e como especificar o arquivo de configuração a ser usado em seu aplicativo baseado em MSAL.

Definições de configuração

Definições gerais

Property	Tipo de Dados	Necessário	Notas
`client_id`	Cadeia (de carateres)	Sim	ID do cliente do seu aplicativo na página de registro do aplicativo
`redirect_uri`	Cadeia (de carateres)	Sim	URI de redirecionamento do seu aplicativo na página de registro do aplicativo
`broker_redirect_uri_registered`	Boolean	Não	Valores possíveis: `true`, `false`
`authorities`	Autoridade de lista<>	Não	A lista de autoridades de que seu aplicativo precisa
`authorization_user_agent`	AuthorizationAgent (enum)	Não	Valores possíveis: `WEBVIEW`, `BROWSER`
`http`	HttpConfiguration	Não	Configurar `HttpUrlConnection` `connect_timeout` e `read_timeout`
`logging`	LoggingConfiguration	Não	Especifica o nível de detalhe do registro. As configurações opcionais incluem: `pii_enabled`, que tem um valor booleano e `log_level`, que leva `ERROR`, `WARNING`, `INFO`, ou `VERBOSE`.

client_id

A ID do cliente ou a ID do aplicativo que foi criada quando você registrou seu aplicativo.

redirect_uri

O URI de redirecionamento que você registrou quando registrou seu aplicativo. Se o URI de redirecionamento for para um aplicativo de broker, consulte Redirecionar URI para aplicativos cliente públicos para garantir que você esteja usando o formato de URI de redirecionamento correto para seu aplicativo broker.

broker_redirect_uri_registered

Se você quiser usar a autenticação intermediada, a broker_redirect_uri_registered propriedade deve ser definida como true. Em um cenário de autenticação intermediada, se o aplicativo não estiver no formato correto para falar com o broker, conforme descrito em Redirecionar URI para aplicativos cliente públicos, o aplicativo validará seu URI de redirecionamento e lançará uma exceção quando for iniciado.

autoridades

A lista de autoridades que são conhecidas e confiáveis por você. Além das autoridades listadas aqui, a MSAL também consulta a Microsoft para obter uma lista de nuvens e autoridades conhecidas pela Microsoft. Nessa lista de autoridades, especifique o tipo de autoridade e quaisquer parâmetros opcionais adicionais, como "audience", que devem ser alinhados com o público do seu aplicativo com base no registro do aplicativo. Segue-se um exemplo de lista de autoridades:

// 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"
    }
}

Mapeie a autoridade do Microsoft Entra & audiência para os pontos de extremidade da plataforma de identidade da Microsoft

Type	Audiência	ID de Inquilino do	Authority_Url	Ponto final resultante	Notas
Microsoft Entra ID	AzureADandPersonalMicrosoftAccount			`https://login.microsoftonline.com/common`	`common` é um alias de locatário para onde a conta está. Como um locatário específico do Microsoft Entra ou o sistema de conta da Microsoft.
Microsoft Entra ID	AzureADMyOrg	contoso.com		`https://login.microsoftonline.com/contoso.com`	Apenas as contas presentes no contoso.com podem adquirir um token. Qualquer domínio verificado, ou o GUID do locatário, pode ser usado como o ID do locatário.
Microsoft Entra ID	AzureADMultipleOrgs			`https://login.microsoftonline.com/organizations`	Somente contas do Microsoft Entra podem ser usadas com esse ponto de extremidade. As contas da Microsoft podem ser membros de organizações. Para adquirir um token usando uma conta da Microsoft para um recurso em uma organização, especifique o locatário organizacional do qual você deseja o token.
Microsoft Entra ID	PersonalMicrosoftAccount			`https://login.microsoftonline.com/consumers`	Somente contas da Microsoft podem usar esse ponto de extremidade.
B2C			Consulte o ponto final resultante	`https://login.microsoftonline.com/tfp/contoso.onmicrosoft.com/B2C_1_SISOPolicy/`	Somente as contas presentes no locatário contoso.onmicrosoft.com podem adquirir um token. Neste exemplo, a política B2C faz parte do caminho da URL da Autoridade.

Nota

A validação de autoridade não pode ser ativada e desativada no MSAL. As autoridades são conhecidas por você como o desenvolvedor, conforme especificado por meio da configuração, ou conhecidas pela Microsoft por meio de metadados. Se a MSAL receber uma solicitação de um token para uma autoridade desconhecida, um MsalClientException do tipo UnknownAuthority resultará. A autenticação intermediada não funciona para o Azure AD B2C.

Propriedades da autoridade

Property	Tipo de dados	Necessário	Notas
`type`	Cadeia (de carateres)	Sim	Espelha o público ou o tipo de conta que seus alvos de aplicativo. Valores possíveis: `AAD`, `B2C`
`audience`	Object	Não	Só se aplica quando type=`AAD`. Especifica a identidade a que seu aplicativo se destina. Usar o valor do registro do seu aplicativo
`authority_url`	Cadeia (de carateres)	Sim	Obrigatório apenas quando type=`B2C`. Opcional para type=`AAD`. Especifica a autoridade, URL ou política que seu aplicativo deve usar
`default`	boolean	Sim	É necessária uma única `"default":true` quando é especificada uma ou mais autoridades.

Propriedades do público

Property	Tipo de Dados	Necessário	Notas
`type`	Cadeia (de carateres)	Sim	Especifica o público que seu aplicativo deseja atingir. Valores possíveis: `AzureADandPersonalMicrosoftAccount`, `PersonalMicrosoftAccount`, `AzureADMultipleOrgs`, `AzureADMyOrg`
`tenant_id`	Cadeia (de carateres)	Sim	Necessário apenas quando `"type":"AzureADMyOrg"`. Opcional para outros `type` valores. Pode ser um domínio de locatário, como `contoso.com`, ou uma ID de locatário, como `aaaabbbb-0000-cccc-1111-dddd2222eeee`

authorization_user_agent

Indica se deve ser usada uma exibição da Web incorporada ou o navegador padrão no dispositivo ao entrar em uma conta ou autorizar o acesso a um recurso.

Valores possíveis:

WEBVIEW: Use a visualização da Web incorporada.
BROWSER: Usa o navegador padrão no dispositivo.

multiple_clouds_supported

Para clientes que suportam várias nuvens nacionais, especifique true. A plataforma de identidade da Microsoft redirecionará automaticamente para a nuvem nacional correta durante a autorização e o resgate do token. Você pode determinar a nuvem nacional da conta conectada examinando a autoridade associada ao AuthenticationResult. Observe que o AuthenticationResult não fornece o endereço de ponto de extremidade específico da nuvem nacional do recurso para o qual você solicita um token.

broker_redirect_uri_registered

Um booleano que indica se você está usando um URI de redirecionamento in-broker compatível com o Microsoft Identity broker. Defina como false se você não quiser usar o broker em seu aplicativo.

Se você estiver usando o Microsoft Entra Authority com o Audience definido como "MicrosoftPersonalAccount", o broker não será usado.

http

Defina configurações globais para tempos limite HTTP, como:

Property	Tipo de dados	Necessário	Notas
`connect_timeout`	número inteiro	Não	Tempo em milissegundos
`read_timeout`	número inteiro	Não	Tempo em milissegundos

registos

As seguintes configurações globais são para registro:

Property	Tipo de Dados	Necessário	Notas
`pii_enabled`	boolean	Não	Emissão ou não de dados pessoais
`log_level`	string	Não	Quais mensagens de log para saída. Os níveis de log suportados incluem `ERROR`,`WARNING`,`INFO`, e `VERBOSE`.
`logcat_enabled`	boolean	Não	Se a saída deve ser feita para registrar cat, além da interface de registro

account_mode

Especifica quantas contas podem ser usadas em seu aplicativo ao mesmo tempo. Os valores possíveis são:

MULTIPLE (Padrão)
SINGLE

A construção de um PublicClientApplication modo de conta que não corresponda a essa configuração resultará em uma exceção.

Para obter mais informações sobre as diferenças entre contas únicas e múltiplas, consulte Aplicativos de conta única e múltipla.

browser_safelist

Uma lista de permissões de navegadores compatíveis com o MSAL. Esses navegadores lidam corretamente com redirecionamentos para intenções personalizadas. Você pode adicionar a esta lista. O padrão é fornecido na configuração padrão mostrada abaixo. ``

O arquivo de configuração padrão do MSAL

A configuração padrão do MSAL que acompanha o MSAL é mostrada abaixo. Você pode ver a versão mais recente no GitHub.

Essa configuração é complementada por valores fornecidos. Os valores fornecidos substituem os padrões.

{
  "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
    }
  ]
}

Exemplo de configuração básica

O exemplo a seguir ilustra uma configuração básica que especifica a ID do cliente, o URI de redirecionamento, se um redirecionamento de broker está registrado e uma 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
    }
  ]
}

Como usar um arquivo de configuração

Crie um arquivo de configuração. Recomendamos que você crie seu arquivo de configuração personalizado no res/raw/auth_config.json. Mas você pode colocá-lo em qualquer lugar que desejar.

Diga à MSAL onde procurar sua configuração ao construir o PublicClientApplication. Por exemplo:

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

Partilhar via

Arquivo de configuração da Biblioteca de Autenticação Microsoft do Android

Definições de configuração

Definições gerais

client_id

redirect_uri

broker_redirect_uri_registered

autoridades

Mapeie a autoridade do Microsoft Entra & audiência para os pontos de extremidade da plataforma de identidade da Microsoft

Propriedades da autoridade

Propriedades do público

authorization_user_agent

multiple_clouds_supported

broker_redirect_uri_registered

http

registos

account_mode

browser_safelist

O arquivo de configuração padrão do MSAL

Exemplo de configuração básica

Como usar um arquivo de configuração

Comentários

Recursos adicionais