Verificatieopties inschakelen in een iOS Swift-app met behulp van Azure AD B2C

Artikel
01/11/2024

In dit artikel worden manieren beschreven waarop u de verificatie van Azure Active Directory B2C (Azure AD B2C) voor uw iOS Swift-toepassing kunt inschakelen, aanpassen en verbeteren.

Raadpleeg voordat u begint eerst de volgende artikelen:

Verificatie configureren in een iOS Swift-voorbeeld-app met behulp van Azure AD B2C
Verificatie inschakelen in uw eigen iOS Swift-app met behulp van Azure AD B2C

Een aangepast domein gebruiken

Met behulp van een aangepast domein kunt u de verificatie-URL volledig aanpassen aan uw merknaam. Voor gebruikers lijkt het alsof ze tijdens het verificatieproces op uw domein blijven, in plaats van dat ze worden omgeleid naar de Azure AD B2C-domeinnaam b2clogin.com.

Als u alle verwijzingen naar 'b2c' in de URL wilt verwijderen, kunt u ook de naam van uw B2C-tenant (contoso.onmicrosoft.com) in de URL van de verificatieaanvraag vervangen door de GUID van uw tenant-id. U kunt https://fabrikamb2c.b2clogin.com/contoso.onmicrosoft.com/ bijvoorbeeld wijzigen in https://account.contosobank.co.uk/<tenant ID GUID>/.

Ga als volgt te werk om een aangepast domein en uw tenant-id in de verificatie-URL te gebruiken:

Volg de richtlijnen in Aangepaste domeinen inschakelen.
Werk het klasselid kAuthorityHostName bij met uw aangepaste domein.
Werk het klasselid kTenantName bij met uw tenant-id.

De volgende Swift-code toont de app-instellingen vóór de wijziging:

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

De volgende Swift-code toont de app-instellingen na de wijziging:

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

Tijdens een gebruikersbeleving voor aanmelden kan uw app zich op een specifieke gebruiker richten. Wanneer een app zich op een gebruiker richt, geeft de app in de autorisatieaanvraag mogelijk de queryparameter login_hint op met de aanmeldingsnaam van de gebruiker. Azure AD B2C vult automatisch de aanmeldingsnaam in en de gebruiker hoeft alleen het wachtwoord op te geven.

Ga als volgt te werk om de aanmeldingsnaam vooraf in te vullen:

Als u een aangepast beleid gebruikt, voegt u de vereiste invoerclaim toe, zoals beschreven in Directe aanmelding instellen.
Zoek naar uw MSAL-configuratieobject (Microsoft Authentication Library) en voeg vervolgens de methode withLoginHint() toe met de aanmeldingshint.

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
...

Een id-provider vooraf selecteren

Als u socialemedia-accounts, zoals Facebook, LinkedIn en Google, in de aanmeldbeleving voor uw toepassing hebt geconfigureerd, kunt u de parameter domain_hint opgeven. Deze queryparameter biedt een hint naar Azure AD B2C over de id-provider voor sociale media die moet worden gebruikt voor aanmelden. Als de toepassing bijvoorbeeld domain_hint=facebook.com opgeeft, leidt de aanmeldingsstroom rechtstreeks naar de aanmeldingspagina van Facebook.

Ga als volgt te werk om gebruikers om te leiden naar een externe id-provider:

Controleer de domeinnaam van de externe id-provider. Zie Aanmelden omleiden naar een sociale provider voor meer informatie.
Maak of gebruik een bestaand lijstobject om extra queryparameters op te slaan.
Voeg de parameter domain_hint met de bijbehorende domeinnaam toe aan de lijst (bijvoorbeeld facebook.com).
Geef de lijst met extra queryparameters door aan het kenmerk extraQueryParameters van het MSAL-configuratieobject.

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
...

De taal van de gebruikersinterface opgeven

Met taalaanpassing in Azure AD B2C kunt u verschillende talen in uw gebruikersstroom opnemen om aan de behoeften van uw klanten te voldoen. Zie Taalaanpassing voor meer informatie.

Ga als volgt te werk om de voorkeurstaal in te stellen:

Taalaanpassing configureren.
Maak of gebruik een bestaand lijstobject om extra queryparameters op te slaan.
Voeg de parameter ui_locales met de bijbehorende taalcode toe aan de lijst (bijvoorbeeld en-us).
Geef de lijst met extra queryparameters door aan het kenmerk extraQueryParameters van het MSAL-configuratieobject.

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
...

Een aangepaste queryreeksparameter doorgeven

Met aangepast beleid kunt u een aangepaste querytekenreeksparameter doorgeven. Dit is bijvoorbeeld handig wanneer u de pagina-inhoud dynamisch wilt wijzigen.

Ga als volgt te werk om een aangepaste querytekenreeksparameter door te geven:

Configureer het element ContentDefinitionParameters.
Maak of gebruik een bestaand lijstobject om extra queryparameters op te slaan.
Voeg de aangepaste queryreeksparameter, zoals campaignId, toe. Stel de parameterwaarde in (bijvoorbeeld germany-promotion).
Geef de lijst met extra queryparameters door aan het kenmerk extraQueryParameters van het MSAL-configuratieobject.

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
...

Een hint voor een id-token doorgeven

Een Relying Party-toepassing kan een binnenkomend JSON Web Token (JWT) verzenden als onderdeel van de OAuth2-autorisatieaanvraag. Het binnenkomende token is een hint over de gebruiker of de autorisatieaanvraag. Azure AD B2C valideert het token en extraheert vervolgens de claim.

Ga als volgt te werk om een hint voor het id-token in de verificatieaanvraag op te nemen:

Definieer in uw aangepaste beleid een technisch profiel voor de hint voor het id-token.
Genereer een id-token in uw code of haal deze op en stel het token vervolgens in op een variabele (bijvoorbeeld idToken).
Maak of gebruik een bestaand lijstobject om extra queryparameters op te slaan.
Voeg de parameter id_token_hint toe met de bijbehorende variabele waarin het id-token wordt opgeslagen.
Geef de lijst met extra queryparameters door aan het kenmerk extraQueryParameters van het MSAL-configuratieobject.

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
...

Logboekregistratie configureren

De MSAL-bibliotheek genereert logboekberichten die u kunnen helpen bij het vaststellen van problemen. De app kan logboekregistratie configureren. De app kan u ook aangepaste controle geven over het detailniveau en over de registratie van persoonlijke en organisatorische gegevens.

We raden u aan een callback voor MSAL-logboekregistratie te maken en gebruikers een manier te bieden om logboeken in te dienen wanneer ze verificatieproblemen ondervinden. MSAL biedt de volgende detailniveaus voor logboekregistratie:

Fout: er is iets misgegaan en er is een fout gegenereerd. Dit niveau wordt gebruikt voor het opsporen van fouten en het identificeren van problemen.
Waarschuwing: er is niet noodzakelijkerwijs een fout of fout opgetreden, maar de informatie is bedoeld voor diagnoses en het opsporen van problemen.
Info: MSAL registreert gebeurtenissen die zijn bedoeld voor informatieve doeleinden en niet noodzakelijkerwijs voor foutopsporing.
Uitgebreid: dit is het standaardniveau. MSAL registreert de volledige details van het bibliotheekgedrag.

De MSAL-logboekregistratie legt standaard geen persoonlijke of organisatorische gegevens vast. De bibliotheek biedt u de optie om logboekregistratie van persoonlijke en organisatorische gegevens in te schakelen.

De MSAL-logboekregistratie moet zo vroeg mogelijk in de startvolgorde van de app worden ingesteld voordat er MSAL-aanvragen worden gedaan. Configureer MSAL-logboekregistratie in de methode AppDelegate.swiftapplication.

Het volgende codefragment laat zien hoe u MSAL-logboekregistratie configureert:

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
    }

Ingesloten webweergave

Webbrowsers zijn vereist voor interactieve verificatie. De MSAL-bibliotheek maakt standaard gebruik van de systeemwebweergave. Tijdens het aanmelden wordt in de MSAL-bibliotheek de webweergave van het iOS-systeem weergegeven met de Azure AD B2C-gebruikersinterface.

Zie het artikel Browsers en WebViews aanpassen voor iOS/macOS voor meer informatie.

Afhankelijk van uw vereisten kunt u de ingesloten webweergave gebruiken. Er zijn verschillen in visueel gedrag en het gedrag van de eenmalige aanmelding tussen de ingesloten webweergave en de systeemwebweergave in MSAL.

Schermopname die het verschil weergeeft tussen de systeemwebweergave en de ingesloten webweergave.

Belangrijk

We raden u aan de standaardinstelling van het platform te gebruiken, gewoonlijk de systeembrowser. De systeembrowser is beter in het onthouden van de gebruikers die zich eerder hebben aangemeld. Sommige id-providers, zoals Google, bieden geen ondersteuning voor een ingesloten weergave.

Als u dit gedrag wilt wijzigen, wijzigt u het kenmerk webviewType van MSALWebviewParameters in wkWebView. In het volgende voorbeeld ziet u hoe u het webweergavetype in de ingesloten weergave kunt wijzigen:

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

Volgende stappen

Zie Configuratieopties van MSAL voor iOS Swift voor meer informatie.

Delen via

Verificatieopties inschakelen in een iOS Swift-app met behulp van Azure AD B2C

Een aangepast domein gebruiken

Een id-provider vooraf selecteren

De taal van de gebruikersinterface opgeven

Een aangepaste queryreeksparameter doorgeven

Een hint voor een id-token doorgeven

Logboekregistratie configureren

Ingesloten webweergave

Volgende stappen

Feedback

Aanvullende resources

Delen via

Verificatieopties inschakelen in een iOS Swift-app met behulp van Azure AD B2C

Een aangepast domein gebruiken

De aanmeldingsnaam vooraf invullen

Een id-provider vooraf selecteren

De taal van de gebruikersinterface opgeven

Een aangepaste queryreeksparameter doorgeven

Een hint voor een id-token doorgeven

Logboekregistratie configureren

Ingesloten webweergave

Volgende stappen

Feedback

Aanvullende resources