Habilitar as opções de autenticação em um aplicativo iOS Swift usando o Azure AD B2C

Artigo
01/11/2024

Este artigo descreve maneiras de habilitar, personalizar e aprimorar a experiência de autenticação do Azure Active Directory B2C (Azure AD B2C) para o aplicativo iOS Swift.

Antes de começar, familiarize-se com os seguintes artigos:

Configurar a autenticação em um aplicativo iOS Swift de exemplo usando o Azure AD B2C
Habilitar a autenticação em seu próprio aplicativo iOS Swift usando o Azure AD B2C

Usar um domínio personalizado

Ao usar um domínio personalizado, você pode recriar por completo a URL de autenticação. Da perspectiva do usuário, os usuários permanecem nos domínios durante o processo de autenticação, em vez de serem redirecionados para o nome de domínio b2clogin.com do Azure AD B2C.

Para remover todas as referências a “b2c” na URL, você também pode substituir o nome do locatário b2c, contoso.onmicrosoft.com, na URL de solicitação de autenticação pelo GUID da ID do locatário. Por exemplo, você pode mudar de https://fabrikamb2c.b2clogin.com/contoso.onmicrosoft.com/ para https://account.contosobank.co.uk/<tenant ID GUID>/.

Para usar um domínio personalizado e a ID de locatário na URL de autenticação, faça o seguinte:

Siga as instruções em Habilitar domínios personalizados.
Atualize o membro da classe kAuthorityHostName com o domínio personalizado.
Atualize o membro da classe kTenantName com a ID de locatário.

O código Swift a seguir mostra as configurações do aplicativo antes da alteração:

let kTenantName = "contoso.onmicrosoft.com" 
let kAuthorityHostName = "contoso.b2clogin.com"

O código Swift a seguir mostra as configurações do aplicativo após a alteração:

let kTenantName = "00000000-0000-0000-0000-000000000000" 
let kAuthorityHostName = "login.contoso.com"

Durante um percurso de entrada do usuário, um aplicativo pode ser direcionado a um usuário específico. Ao direcionar a um usuário, um aplicativo pode especificar, na solicitação de autorização, o parâmetro de consulta login_hint com o nome de entrada do usuário. O Azure AD B2C preenche automaticamente o nome de entrada, e o usuário só precisa fornecer a senha.

Para preencher o nome de logon, faça o seguinte:

Se você estiver usando uma política personalizada, adicione a declaração de entrada necessária, conforme descrito em Configurar conexão direta.
Procure o objeto de configuração da Biblioteca de Autenticação da Microsoft (MSAL) e, em seguida, adicione o método withLoginHint() com a dica de logon.

let parameters = MSALInteractiveTokenParameters(scopes: kScopes, webviewParameters: self.webViewParameters!)
parameters.promptType = .selectAccount
parameters.authority = authority
parameters.loginHint = "bob@contoso.com"
// More settings here

applicationContext.acquireToken(with: parameters) { (result, error) in
...

Pré-selecionar um provedor de identidade

Se você configurou o percurso de entrada para seu aplicativo para incluir contas sociais, como Facebook, LinkedIn ou do Google, você pode especificar o domain_hint parâmetro. Esse parâmetro de consulta fornece uma dica para o Azure AD B2C sobre o provedor de identidade social que deve ser usado para entrar. Por exemplo, se o aplicativo especifica domain_hint=facebook.com, o fluxo de entrada vai diretamente para a página de entrada do Facebook.

Para redirecionar usuários para um provedor de identidade externo, faça o seguinte:

Verifique o nome de domínio do seu provedor de identidade externo. Para obter mais informações, consulte redirecionar entrada para um provedor social.
Crie ou use um objeto de lista existente para armazenar parâmetros de consulta adicionais.
Adicione o parâmetro domain_hint com o nome de domínio correspondente à lista (por exemplo, facebook.com).
Passe a lista de parâmetros de consulta adicional ao atributo extraQueryParameters do objeto de configuração da MSAL.

let extraQueryParameters: [String: String] = ["domain_hint": "facebook.com"]

let parameters = MSALInteractiveTokenParameters(scopes: kScopes, webviewParameters: self.webViewParameters!)
parameters.promptType = .selectAccount
parameters.authority = authority
parameters.extraQueryParameters = extraQueryParameters
// More settings here

applicationContext.acquireToken(with: parameters) { (result, error) in
...

Especificar a linguagem de programação da interface do usuário

A personalização da linguagem de programação no Azure Active Directory B2C permite que o fluxo do usuário acomode uma variedade de linguagens de programação para atender às necessidades dos clientes. Para obter mais informações, consulte Personalização de linguagem de programação.

Para definir o idioma preferencial, faça o seguinte:

Configurar a personalização de linguagem.
Crie ou use um objeto de lista existente para armazenar parâmetros de consulta adicionais.
Adicione o parâmetro ui_locales com o código de linguagem correspondente à lista (por exemplo, en-us).
Passe a lista de parâmetros de consulta adicional ao atributo extraQueryParameters do objeto de configuração da MSAL.

let extraQueryParameters: [String: String] = ["ui_locales": "en-us"]

let parameters = MSALInteractiveTokenParameters(scopes: kScopes, webviewParameters: self.webViewParameters!)
parameters.promptType = .selectAccount
parameters.authority = authority
parameters.extraQueryParameters = extraQueryParameters
// More settings here

applicationContext.acquireToken(with: parameters) { (result, error) in
...

Passar um parâmetro de cadeia de caracteres de consulta personalizado

Com as políticas personalizadas, é possível passar um parâmetro de cadeia de caracteres de consulta personalizado. Um bom exemplo de caso de uso é quando você deseja alterar dinamicamente o conteúdo da página.

Para passar um parâmetro de cadeia de caracteres de consulta personalizado, siga estas etapas:

Configure o elemento ContentDefinitionParameters.
Crie ou use um objeto de lista existente para armazenar parâmetros de consulta adicionais.
Adicione o parâmetro de cadeia de caracteres de consulta personalizada, como campaignId. Defina o valor do parâmetro (por exemplo, germany-promotion).
Passe a lista de parâmetros de consulta adicional ao atributo extraQueryParameters do objeto de configuração da MSAL.

let extraQueryParameters: [String: String] = ["campaignId": "germany-promotion"]

let parameters = MSALInteractiveTokenParameters(scopes: kScopes, webviewParameters: self.webViewParameters!)
parameters.promptType = .selectAccount
parameters.authority = authority
parameters.extraQueryParameters = extraQueryParameters
// More settings here

applicationContext.acquireToken(with: parameters) { (result, error) in
...

Passar uma dica de token de ID

Um aplicativo de terceira parte confiável pode enviar um JWT (Token Web JSON) de entrada como parte da solicitação de autorização OAuth2. O token de entrada é uma dica sobre o usuário ou a solicitação de autorização. O Azure AD B2C valida o token e, em seguida, extrai a declaração.

Para incluir uma dica de token de ID na solicitação de autenticação, faça o seguinte:

Em sua política personalizada, defina um perfil técnico de dica de token de ID.
No código, gere ou adquira uma ID do token e, em seguida, defina o token como uma variável (por exemplo, idToken).
Crie ou use um objeto de lista existente para armazenar parâmetros de consulta adicionais.
Adicione o parâmetro id_token_hint com a variável correspondente que armazena a ID do token.
Passe a lista de parâmetros de consulta adicional ao atributo extraQueryParameters do objeto de configuração da MSAL.

let extraQueryParameters: [String: String] = ["id_token_hint": idToken]

let parameters = MSALInteractiveTokenParameters(scopes: kScopes, webviewParameters: self.webViewParameters!)
parameters.promptType = .selectAccount
parameters.authority = authority
parameters.extraQueryParameters = extraQueryParameters
// More settings here

applicationContext.acquireToken(with: parameters) { (result, error) in
...

Configurar o registro em log

A biblioteca MSAL gera mensagens de log que podem ajudar a diagnosticar problemas. O aplicativo pode configurar o registro em log. O aplicativo também pode dar a você controle personalizado sobre o nível de detalhes e se os dados pessoais e organizacionais são registrados.

Recomendamos que você crie um retorno de chamada de registro em log da MSAL e forneça uma maneira para os usuários enviarem logs quando estiverem com problemas de autenticação. A MSAL fornece os níveis de detalhes de log a seguir:

Erro: indica que algo deu errado e um erro foi gerado. Esse nível é usado para depuração e identificação de problemas.
Aviso: as informações são destinadas a diagnosticar e identificar problemas, mesmo que não tenha havido necessariamente um erro ou falha.
Informações: a MSAL registra os eventos que são destinados para fins informativos e não necessariamente para depuração.
Verbose: esse é o nível padrão. A MSAL registra em log os detalhes completos do comportamento da biblioteca.

Por padrão, o agente da MSAL não captura dados pessoais ou organizacionais. A biblioteca oferecerá a opção para habilitar o registro em log de dados pessoais e organizacionais se você optar por fazer isso.

O agente MSAL deve ser definido o mais cedo possível na sequência de inicialização do aplicativo, antes de qualquer solicitação de MSAL ser feita. Configure o registro MSAL no método AppDelegate.swiftapplication.

O trecho de código a seguir demonstra como configurar o registro em log no MSAL:

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        
        MSALGlobalConfig.loggerConfig.logLevel = .verbose
        MSALGlobalConfig.loggerConfig.setLogCallback { (logLevel, message, containsPII) in
            
            // If PiiLoggingEnabled is set YES, this block will potentially contain sensitive information (Personally Identifiable Information), but not all messages will contain it.
            // containsPII == YES indicates if a particular message contains PII.
            // You might want to capture PII only in debug builds, or only if you take necessary actions to handle PII properly according to legal requirements of the region
            if let displayableMessage = message {
                if (!containsPII) {
                    #if DEBUG
                    // NB! This sample uses print just for testing purposes
                    // You should only ever log to NSLog in debug mode to prevent leaking potentially sensitive information
                    print(displayableMessage)
                    #endif
                }
            }
        }
        return true
    }

Experiência de exibição da Web inserida

É obrigatório o uso de navegadores da Web na autenticação interativa. Por padrão, a biblioteca MSAL usa a exibição da Web do sistema. Durante a inserção das credenciais, a biblioteca MSAL abre o modo de exibição da Web do sistema iOS com a interface do usuário do Azure AD B2C.

Para mais informações, confira o artigo Personalizar navegadores e modos de exibição da Web para iOS/macOS.

Dependendo dos seus requisitos, você pode usar a exibição da Web inserida. Há diferenças de comportamento de logon único e visual entre a exibição da Web inserida e a exibição da Web do sistema no MSAL.

Captura de tela demonstrando a diferença entre a experiência de exibição da Web do sistema e a experiência de exibição da Web incorporada.

Importante

Recomendamos que você use o padrão de plataforma, que é normalmente o navegador do sistema. O navegador do sistema é melhor para lembrar os usuários que fizeram logon antes. Alguns provedores de identidade, como o Google, não dão suporte a uma experiência de exibição inserida.

Para alterar esse comportamento, altere o atributo webviewType de MSALWebviewParameters para wkWebView. O exemplo a seguir demonstra como alterar o tipo de exibição da Web para a exibição inserida:

func initWebViewParams() {
    self.webViewParameters = MSALWebviewParameters(authPresentationViewController: self)
    
    // Use embedded view experience
    self.webViewParameters?.webviewType = .wkWebView
}

Próximas etapas

Para saber mais, confira Opções de configuração da MSAL para iOS Swift.

Compartilhar via

Habilitar as opções de autenticação em um aplicativo iOS Swift usando o Azure AD B2C

Usar um domínio personalizado

Pré-selecionar um provedor de identidade

Especificar a linguagem de programação da interface do usuário

Passar um parâmetro de cadeia de caracteres de consulta personalizado

Passar uma dica de token de ID

Configurar o registro em log

Experiência de exibição da Web inserida

Próximas etapas

Recursos adicionais

Compartilhar via

Habilitar as opções de autenticação em um aplicativo iOS Swift usando o Azure AD B2C

Usar um domínio personalizado

Preencher previamente o nome de usuário

Pré-selecionar um provedor de identidade

Especificar a linguagem de programação da interface do usuário

Passar um parâmetro de cadeia de caracteres de consulta personalizado

Passar uma dica de token de ID

Configurar o registro em log

Experiência de exibição da Web inserida

Próximas etapas

Recursos adicionais