Partilhar via

Ativar opções de autenticação numa aplicação Swift para iOS com o Azure AD B2C

  • Artigo

Este artigo descreve formas de ativar, personalizar e melhorar a experiência de autenticação do Azure Active Directory B2C (Azure AD B2C) para a sua aplicação Swift para iOS.

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

Utilizar um domínio personalizado

Ao utilizar um domínio personalizado, pode marcar totalmente o URL de autenticação. Do ponto de vista do utilizador, os utilizadores permanecem no 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 a "b2c" no URL, também pode substituir o nome do inquilino B2C, contoso.onmicrosoft.com, no URL do pedido de autenticação pelo GUID do ID do inquilino. Por exemplo, pode mudar https://fabrikamb2c.b2clogin.com/contoso.onmicrosoft.com/ para https://account.contosobank.co.uk/<tenant ID GUID>/.

Para utilizar um domínio personalizado e o seu ID de inquilino no URL de autenticação, faça o seguinte:

  1. Siga a documentação de orientação em Ativar domínios personalizados.
  2. Atualize o membro da kAuthorityHostName classe com o seu domínio personalizado.
  3. Atualize o membro da kTenantName classe com o seu ID de inquilino.

O seguinte código Swift mostra as definições da aplicação antes da alteração:

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

O seguinte código Swift mostra as definições da aplicação após a alteração:

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

Pré-preencher o nome de início de sessão

Durante um percurso de início de sessão do utilizador, a sua aplicação poderá visar um utilizador específico. Quando uma aplicação destina um utilizador, pode especificar no pedido de autorização o login_hint parâmetro de consulta com o nome de início de sessão do utilizador. Azure AD B2C preenche automaticamente o nome de início de sessão e o utilizador tem de fornecer apenas a palavra-passe.

Para pré-preencher o nome de início de sessão, faça o seguinte:

  1. Se estiver a utilizar uma política personalizada, adicione a afirmação de entrada necessária, conforme descrito em Configurar o início de sessão direto.
  2. Procure o objeto de configuração da Biblioteca de Autenticação da Microsoft (MSAL) e, em seguida, adicione o withLoginHint() método com a sugestão 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 fornecedor de identidade

Se tiver configurado o percurso de início de sessão para que a sua aplicação inclua contas de redes sociais, como o Facebook, o LinkedIn ou o Google, pode especificar o domain_hint parâmetro . Este parâmetro de consulta fornece uma sugestão para Azure AD B2C sobre o fornecedor de identidade social que deve ser utilizado para iniciar sessão. Por exemplo, se a aplicação especificar domain_hint=facebook.com, o fluxo de início de sessão vai diretamente para a página de início de sessão do Facebook.

Para redirecionar os utilizadores para um fornecedor de identidade externo, faça o seguinte:

  1. Verifique o nome de domínio do seu fornecedor de identidade externa. Para obter mais informações, veja Redirecionar o início de sessão para um fornecedor de redes sociais.
  2. Crie ou utilize um objeto de lista existente para armazenar parâmetros de consulta adicionais.
  3. Adicione o domain_hint parâmetro com o nome de domínio correspondente à lista (por exemplo, facebook.com).
  4. Transmita a lista de parâmetros de consulta extra para o atributo do objeto de extraQueryParameters configuração 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 IU

A personalização de idiomas no Azure AD B2C permite ao seu fluxo de utilizador acomodar uma variedade de idiomas de acordo com as necessidades dos seus clientes. Para obter mais informações, veja Personalização de idiomas.

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

  1. Configurar a personalização de idiomas.
  2. Crie ou utilize um objeto de lista existente para armazenar parâmetros de consulta adicionais.
  3. Adicione o ui_locales parâmetro com o código de idioma correspondente à lista (por exemplo, en-us).
  4. Transmita a lista de parâmetros de consulta extra para o atributo do objeto de extraQueryParameters configuração 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
...

Transmitir um parâmetro de cadeia de consulta personalizado

Com as políticas personalizadas, pode transmitir um parâmetro de cadeia de consulta personalizado. Um bom exemplo de caso de utilização é quando pretende alterar dinamicamente o conteúdo da página.

Para transmitir um parâmetro de cadeia de consulta personalizado, faça o seguinte:

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

Transmitir uma sugestão de token de ID

Uma aplicação de entidade confiadora pode enviar um JSON Web Token (JWT) de entrada como parte do pedido de autorização OAuth2. O token de entrada é uma sugestão sobre o utilizador ou o pedido de autorização. Azure AD B2C valida o token e, em seguida, extrai a afirmação.

Para incluir uma sugestão de token de ID no pedido de autenticação, faça o seguinte:

  1. Na sua política personalizada, defina um perfil técnico de sugestão de token de ID.
  2. No 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 utilize um objeto de lista existente para armazenar parâmetros de consulta adicionais.
  4. Adicione o id_token_hint parâmetro com a variável correspondente que armazena o token de ID.
  5. Transmita a lista de parâmetros de consulta extra para o atributo do objeto de extraQueryParameters configuração 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 registo

A biblioteca MSAL gera mensagens de registo que podem ajudar a diagnosticar problemas. A aplicação pode configurar o registo. A aplicação também pode dar-lhe controlo personalizado sobre o nível de detalhe e se os dados pessoais e organizacionais são registados.

Recomendamos que crie uma chamada de retorno de registo do MSAL e forneça uma forma de os utilizadores submeterem registos quando tiverem problemas de autenticação. A MSAL fornece estes níveis de detalhes de registo:

  • Erro: ocorreu um erro e foi gerado um erro. Este nível é utilizado para depurar e identificar problemas.
  • Aviso: Não houve necessariamente um erro ou falha, mas as informações destinam-se a diagnósticos e a identificar problemas.
  • Informações: a MSAL regista eventos que se destinam a fins informativos e não necessariamente para depuração.
  • Verboso: este é o nível predefinido. A MSAL regista todos os detalhes do comportamento da biblioteca.

Por predefinição, o logger MSAL não captura quaisquer dados pessoais ou organizacionais. A biblioteca dá-lhe a opção de ativar o registo de dados pessoais e organizacionais, caso decida fazê-lo.

O logger MSAL deve ser definido o mais cedo possível na sequência de iniciação de aplicações, antes de serem feitos quaisquer pedidos MSAL. Configure o registo MSAL no método AppDelegate.swiftapplication .

O fragmento de código seguinte demonstra como configurar o registo 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 vista Web incorporada

Os browsers são necessários para a autenticação interativa. Por predefinição, a biblioteca MSAL utiliza a vista 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 Azure AD B2C.

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

Consoante os seus requisitos, pode utilizar a vista Web incorporada. Existem diferenças visuais e de comportamento de início de sessão único entre a vista Web incorporada e a vista Web do sistema no MSAL.

Captura de ecrã a demonstrar a diferença entre a experiência de vista Web do sistema e a experiência de vista Web incorporada.

Importante

Recomendamos que utilize a predefinição da plataforma, que normalmente é o browser do sistema. O browser do sistema é melhor se lembrar dos utilizadores que iniciaram sessão anteriormente. Alguns fornecedores de identidade, como o Google, não suportam uma experiência de vista incorporada.

Para alterar este comportamento, altere o webviewType atributo de MSALWebviewParameters para wkWebView. O exemplo seguinte demonstra como alterar o tipo de vista Web para a vista incorporada:

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

Passos seguintes