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

Este artigo descreve maneiras de habilitar, personalizar e aprimorar a experiência de autenticação do Azure Ative Directory B2C (Azure AD B2C) para seu 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
• Habilite a autenticação em seu próprio aplicativo iOS Swift usando o Azure AD B2C

Utilizar um domínio personalizado

Usando um domínio personalizado, você pode marcar totalmente a URL de autenticação. Do ponto de vista do usuário, os usuários permanecem no seu domínio 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" no URL, você também pode substituir o nome do locatário B2C, contoso.onmicrosoft.com, no URL da solicitação de autenticação pelo GUID do ID do locatário. Por exemplo, você pode alterar https://fabrikamb2c.b2clogin.com/contoso.onmicrosoft.com/ para https://account.contosobank.co.uk/<tenant ID GUID>/.

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

1. Siga as orientações em Ativar domínios personalizados.
2. Atualize o membro da classe kAuthorityHostName com o seu domínio personalizado.
3. Atualize o membro da classe com seu kTenantNameID 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" 

Preencher automaticamente o nome de início de sessão

Durante uma jornada do usuário de login, seu aplicativo pode ter como alvo um usuário específico. Quando um aplicativo tem como alvo um usuário, ele pode especificar na solicitação de autorização o login_hint parâmetro de consulta com o nome de entrada do usuário. O Azure AD B2C preenche automaticamente o nome de entrada e o usuário precisa fornecer apenas a senha.

Para preencher previamente o nome de utilizador, faça o seguinte:

1. Se você estiver usando uma política personalizada, adicione a declaração de entrada necessária, conforme descrito em Configurar entrada direta.
2. Procure o objeto de configuração Microsoft Authentication Library (MSAL) e adicione o método withLoginHint() com a dica de início de sessão.

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 a jornada de entrada para seu aplicativo para incluir contas sociais, como Facebook, LinkedIn ou Google, você pode especificar o domain_hint parâmetro. Este 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 especificar domain_hint=facebook.com, o fluxo de entrada vai diretamente para a página de entrada do Facebook.

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

1. Verifique o nome de domínio do seu provedor de identidade externo. Para obter mais informações, consulte Redirecionar o login para um provedor social.
2. Crie ou use um objeto de lista existente para armazenar parâmetros de consulta extras.
3. Adicione o domain_hint parâmetro com o nome de domínio correspondente à lista (por exemplo, facebook.com).
4. Passe a lista de parâmetros de consulta adicionais para o atributo extraQueryParameters do objeto de configuração do 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 o idioma da interface do usuário

A personalização de idioma no Azure AD B2C permite que seu fluxo de usuário acomode uma variedade de idiomas para atender às necessidades de seus clientes. Para obter mais informações, consulte Personalização de idioma.

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

1. Configure a personalização do idioma.
2. Crie ou use um objeto de lista existente para armazenar parâmetros de consulta extras.
3. Adicione o ui_locales parâmetro com o código de idioma correspondente à lista (por exemplo, en-us).
4. Passe a lista de parâmetros de consulta adicionais para o atributo extraQueryParameters do objeto de configuração do 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 políticas personalizadas, você pode 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, faça o seguinte:

1. Configure o elemento ContentDefinitionParameters .
2. Crie ou use um objeto de lista existente para armazenar parâmetros de consulta extras.
3. Adicione o parâmetro de cadeia de caracteres de consulta personalizado, como campaignId. Defina o valor do parâmetro (por exemplo, germany-promotion).
4. Passe a lista de parâmetros de consulta adicionais para o atributo extraQueryParameters do objeto de configuração do 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
...

Fornecer uma sugestão de token de identificação

Um aplicativo de terceira parte confiável pode enviar um JSON Web Token (JWT) 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:

1. Em sua política personalizada, defina um perfil técnico de dica de token de ID.
2. No seu código, gere ou adquira um token de ID e, em seguida, defina o token como uma variável (por exemplo, idToken).
3. Crie ou use um objeto de lista existente para armazenar parâmetros de consulta extras.
4. Adicione o id_token_hint parâmetro com a variável correspondente que armazena o token de ID.
5. Passe a lista de parâmetros de consulta adicionais para o atributo extraQueryParameters do objeto de configuração do 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 registo de logs

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

Recomendamos que se crie uma função de retorno de registo MSAL e disponibilize uma forma para os utilizadores enviarem registos quando enfrentarem problemas de autenticação. O MSAL fornece estes níveis de detalhes de registro:

• Erro: Algo correu mal e foi gerado um erro. Este nível é usado para depurar e identificar problemas.
• Aviso: Não houve necessariamente um erro ou falha, mas as informações destinam-se a diagnósticos e identificação de problemas.
• Info: O MSAL registra eventos destinados a fins informativos e não necessariamente para depuração.
• Verbose: Este é o nível padrão. O MSAL registra todos os detalhes do comportamento da biblioteca.

Por padrão, o registrador MSAL não captura dados pessoais ou organizacionais. A biblioteca oferece a opção de habilitar o registro de dados pessoais e organizacionais se você decidir fazê-lo.

O registrador MSAL deve ser definido o mais cedo possível na sequência de inicialização do aplicativo, antes que quaisquer solicitações MSAL sejam feitas. Configure o registo no método AppDelegate.swift do MSALapplication.

O trecho de código a seguir demonstra como configurar o log 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 visualização da Web incorporada

Os navegadores da Web são necessários para autenticação interativa. Por padrão, a biblioteca MSAL utiliza a visualização da Web do sistema. Durante o início de sessão, a biblioteca MSAL apresenta a vista Web do sistema iOS com a interface de utilizador do Azure AD B2C.

Para obter mais informações, consulte o artigo Personalizar navegadores e WebViews para iOS/macOS .

Dependendo dos seus requisitos, pode utilizar a vista Web incorporada. Existem diferenças visuais e de comportamento de autenticação única entre a vista Web incorporada e a vista Web do sistema na MSAL.

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

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

Próximos passos

• Para saber mais, consulte Opções de configuração do MSAL para iOS Swift.