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

Artigo
04/10/2024

A MSAL (Biblioteca de Autenticação da Microsoft) 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 o ajudará a entender as várias configurações no arquivo de configuração e a especificar o arquivo de configuração a ser usado em seu aplicativo baseado na MSAL.

Definições de configuração

Configurações gerais

Propriedade	Tipo de Dados	Obrigatório	Observações
`client_id`	String	Sim	A ID do cliente do seu aplicativo da Página de registro do aplicativo
`redirect_uri`	String	Sim	O URI de Redirecionamento do aplicativo da Página de registro do aplicativo
`broker_redirect_uri_registered`	Boolean	Não	Valores possíveis: `true`, `false`
`authorities`	Lista <Autoridades>	Não	A lista de autoridades que seu aplicativo precisa
`authorization_user_agent`	AuthorizationAgent (enumeração)	Não	Valores possíveis: `WEBVIEW`, `BROWSER`
`http`	HttpConfiguration	Não	Configurar `HttpUrlConnection`, `connect_timeout` e `read_timeout`
`logging`	LoggingConfiguration	Não	Especifique o nível de detalhes de log. As configurações opcionais incluem: `pii_enabled`, que usa um valor booliano e `log_level`, que usa `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 agente, confira URI de redirecionamento para aplicativos cliente públicos para garantir que você esteja usando o formato de URI de redirecionamento correto para seu aplicativo de agente.

broker_redirect_uri_registered

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

autoridades

A lista de autoridades que são conhecidas e nas quais você confia. Além das autoridades listadas aqui, o MSAL também consulta a Microsoft para obter uma lista de nuvens e autoridades conhecidas da Microsoft. Nessa lista de autoridades, especifique o tipo da 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. Esta é uma lista de exemplos 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"
    }
}

Mapear a autoridade e o público-alvo do Microsoft Entra para pontos de extremidade da plataforma de identidade da Microsoft

Tipo	Público	ID do locatário	Authority_Url	Ponto de extremidade resultante	Observações
ID do Microsoft Entra	AzureADandPersonalMicrosoftAccount			`https://login.microsoftonline.com/common`	`common` é um alias de locatário para onde a conta está. Como um locatário do Microsoft Entra específico ou o sistema de contas da Microsoft.
ID do Microsoft Entra	AzureADMyOrg	contoso.com		`https://login.microsoftonline.com/contoso.com`	Somente as contas presentes no contoso.com podem adquirir um token. Qualquer domínio verificado, ou o GUID do locatário, pode ser usado como a ID do locatário.
ID do Microsoft Entra	AzureADMultipleOrgs			`https://login.microsoftonline.com/organizations`	Somente as 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 um conta da Microsoft para um recurso em uma organização, especifique o locatário organizacional do qual você deseja o token.
ID do Microsoft Entra	PersonalMicrosoftAccount			`https://login.microsoftonline.com/consumers`	Somente contas da Microsoft podem usar esse ponto de extremidade.
B2C			Consultar o ponto de extremidade 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.

Observação

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

Propriedades da autoridade

Propriedade	Tipo de dados	Obrigatório	Observações
`type`	String	Sim	Espelha o tipo de conta ou público ao qual seu aplicativo se destina. Valores possíveis: `AAD`, `B2C`
`audience`	Objeto	Não	Aplica-se somente quando type=`AAD`. Especifica a identidade de destino do seu aplicativo. Usar o valor do registro do aplicativo
`authority_url`	String	Sim	Necessário somente quando type=`B2C`. Opcional para type=`AAD`. Especifica a URL ou a política de autoridade que seu aplicativo deve usar
`default`	booleano	Sim	Um único `"default":true` é necessário quando uma ou mais autoridades são especificadas.

Propriedades do Público

Propriedade	Tipo de Dados	Obrigatório	Observações
`type`	String	Sim	Especifica o público-alvo que seu aplicativo deseja direcionar. Valores possíveis: `AzureADandPersonalMicrosoftAccount`, `PersonalMicrosoftAccount`, `AzureADMultipleOrgs`, `AzureADMyOrg`
`tenant_id`	String	Sim	Necessário somente quando `"type":"AzureADMyOrg"`. Opcional para outros valores `type`. 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 usado um modo de exibição da Web inserido ou o navegador padrão no dispositivo, ao entrar em uma conta ou autorizar o acesso a um recurso.

Valores possíveis:

WEBVIEW: usa o modo de exibição da Web inserido.
BROWSER: usa o navegador padrão no dispositivo.

multiple_clouds_supported

Para clientes que dão suporte a várias nuvens nacionais, especifique true. A plataforma de identidade da Microsoft será redirecionada automaticamente para a nuvem nacional correta durante a autorização e o resgate de token. Determine 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 booliano que indica se você está usando um URI de redirecionamento no agente compatível com o agente de Identidade da Microsoft. Defina como false se você não quiser usar o agente em seu aplicativo.

Se você estiver usando a Autoridade do Microsoft Entra com o público definido como "MicrosoftPersonalAccount", o agente não será usado.

http

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

Propriedade	Tipo de dados	Obrigatório	Observações
`connect_timeout`	INT	Não	Tempo em milissegundos
`read_timeout`	int	Não	Tempo em milissegundos

registro em log

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

Propriedade	Tipo de Dados	Obrigatório	Observações
`pii_enabled`	booleano	Não	Se os dados pessoais devem ser emitidos
`log_level`	Cadeia de caracteres	No	Quais mensagens de log gerar. Os níveis de log com suporte incluem `ERROR`, `WARNING`, `INFO` e `VERBOSE`.
`logcat_enabled`	booleano	Não	Se gerar uma saída para categorias de log além da interface de log deve ser gerada

account_mode

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

MULTIPLE (Padrão)
SINGLE

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

Para saber mais sobre as diferenças entre contas únicas e múltiplas, confira Aplicativos de conta única e múltipla.

browser_safelist

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

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

A configuração padrão da MSAL fornecida com a MSAL é mostrada abaixo. Você pode ver a versão mais recente no GitHub.

Essa configuração é complementada por valores que você fornece. Os valores que você fornece 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 do agente 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

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

Informe à 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);

Compartilhar via

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

Definições de configuração

Configurações gerais

client_id

redirect_uri

broker_redirect_uri_registered

autoridades

Mapear a autoridade e o público-alvo do Microsoft Entra para 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

registro em log

account_mode

browser_safelist

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

Exemplo de configuração básica

Como usar um arquivo de configuração

Comentários

Recursos adicionais