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

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

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

• Configurar a autenticação em um aplicativo swift de exemplo do iOS 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

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 em seu domínio durante o processo de autenticação, em vez de serem redirecionados para o Azure AD B2C b2clogin.com nome de domínio.

Para remover todas as referências de “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 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 diretrizes em Habilitar domínios personalizados.
2. Atualize o membro da classe kAuthorityHostName com seu domínio personalizado.
3. Atualize o membro da classe kTenantName com sua 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" 

Preencher previamente o nome de usuário

Durante a experiência de login do usuário, seu aplicativo pode focar em um usuário específico. Quando um aplicativo tem como destino 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 o nome de logon, 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 conexão direta.
2. Procure o objeto de configuração da MSAL (Biblioteca de Autenticação da Microsoft) 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 do aplicativo para incluir contas sociais, como Facebook, LinkedIn ou Google, poderá 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 especificar 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:

1. Verifique o nome de domínio do 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 extra para o atributo do objeto de configuração MSAL extraQueryParameters .

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 idiomas no Azure AD B2C permite que seu fluxo de usuário acomode uma variedade de idiomas para atender às necessidades dos clientes. Para obter mais informações, consulte Personalização de idioma.

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

1. Configurar 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 extra para o atributo do objeto de configuração MSAL extraQueryParameters .

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 personalizada, 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 personalizada, como campaignId. Defina o valor do parâmetro (por exemplo, germany-promotion).
4. Passe a lista de parâmetros de consulta extra para o atributo do objeto de configuração MSAL extraQueryParameters .

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:

1. Em sua política personalizada, defina um perfil técnico de dica de token de ID.
2. Em seu código, gere ou adquira um token de ID e 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 extra para o atributo do objeto de configuração MSAL extraQueryParameters .

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 fornecer 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: algo deu errado e um erro foi gerado. Esse nível é usado para depurar e identificar problemas.
• Aviso: não houve necessariamente um erro ou falha, mas as informações se destinam a diagnósticos e problemas de identificação.
• Informações: A MSAL registra eventos destinados a fins informativos e não necessariamente para depuração.
• Detalhado: esse é o nível padrão. A MSAL registra todos os detalhes do comportamento da biblioteca.

Por padrão, o registrador da MSAL não captura dados pessoais ou organizacionais. A biblioteca oferece a opção de habilitar o registro em log de dados pessoais e organizacionais se você decidir fazer isso.

O logger MSAL deve ser configurado o mais cedo possível na sequência de inicialização do aplicativo, antes que quaisquer solicitações MSAL sejam feitas. Configure registrar em log na MSAL no método AppDelegate.swiftapplication.

O trecho de código a seguir demonstra como configurar o registro em log do 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 integrada

Navegadores da Web são necessários para autenticação interativa. Por padrão, a biblioteca MSAL usa o modo de 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 obter mais informações, consulte o artigo Personalizar navegadores e WebViews para iOS/macOS .

Dependendo de seus requisitos, você pode usar a visualização web incorporada. 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.

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 o modo de exibição inserido:

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

Próximas etapas

• Para saber mais, confira as opções de configuração do MSAL para iOS Swift.