Eenmalige aanmelding met MSAL.js

Artikel
10/24/2023

Eenmalige aanmelding (SSO) biedt een naadlozere ervaring doordat een gebruiker minder vaak om referenties wordt gevraagd. Gebruikers voeren hun referenties eenmaal in en de tot stand gebrachte sessie kan opnieuw worden gebruikt door andere toepassingen op hetzelfde apparaat zonder verdere prompts.

Microsoft Entra ID schakelt eenmalige aanmelding in door een sessiecooky in te stellen wanneer een gebruiker zich voor het eerst verifieert. MSAL.js slaat ook de id-tokens en toegangstokens van de gebruiker op in de browseropslag per toepassingsdomein. De twee mechanismen, Microsoft Entra session cookie en Microsoft Authentication Library (MSAL) cache, zijn onafhankelijk van elkaar, maar werken samen om SSO-gedrag te bieden.

Eenmalige aanmelding tussen browsertabbladen voor dezelfde app

Wanneer een gebruiker een toepassing heeft geopend op verschillende tabbladen en zich aanmeldt bij een van deze tabbladen, kunnen ze worden aangemeld bij dezelfde app die op andere tabbladen wordt geopend zonder dat hierom wordt gevraagd. Hiervoor moet u cacheLocation instellen in MSAL.js configuratieobjectlocalStorage, zoals wordt weergegeven in het volgende voorbeeld:

const config = {
  auth: {
    clientId: "1111-2222-3333-4444-55555555",
  },
  cache: {
    cacheLocation: "localStorage",
  },
};

const msalInstance = new msal.PublicClientApplication(config);

In dit geval maken toepassingsexemplaren op verschillende browsertabbladen gebruik van dezelfde MSAL-cache, waardoor de verificatiestatus ertussen wordt gedeeld. U kunt ook MSAL-gebeurtenissen gebruiken voor het bijwerken van toepassingsexemplaren wanneer een gebruiker zich aanmeldt vanuit een ander browsertabblad of -venster. Zie voor meer informatie: Gesynchroniseerde aangemelde status op tabbladen en vensters

Eenmalige aanmelding tussen verschillende apps

Wanneer een gebruiker zich verifieert, wordt een sessiecooky ingesteld op het Microsoft Entra-domein in de browser. MSAL.js is afhankelijk van deze sessiecookie om eenmalige aanmelding te bieden voor de gebruiker tussen verschillende toepassingen. Met name biedt MSAL.js de ssoSilent methode om de gebruiker aan te melden en tokens te verkrijgen zonder tussenkomst. Als de gebruiker echter meerdere gebruikersaccounts in een sessie met Microsoft Entra-id heeft, wordt de gebruiker gevraagd een account te kiezen waarmee hij zich aanmeldt. Daarom zijn er twee manieren om eenmalige aanmelding te bereiken met behulp van de ssoSilent-methode.

Met hint van de gebruiker

Om de prestaties te verbeteren en ervoor te zorgen dat de autorisatieserver naar de juiste accountsessie zoekt, kunt u een van de volgende opties doorgeven in het aanvraagobject van de ssoSilent methode om het token op de achtergrond te verkrijgen.

login_hint, die kan worden opgehaald uit de eigenschap gebruikersnaam van het account object of de upn claim in het id-token. Als uw app gebruikers verificeert met B2C, raadpleegt u: B2C-gebruikersstromen configureren om een gebruikersnaam in id-tokens te verzenden
Sessie-id, siddie kan worden opgehaald uit idTokenClaims een account object.
account, die kan worden opgehaald met behulp van een van de accountmethoden

We raden u aan om de login_hintoptionele id-tokenclaim te gebruiken die is ssoSilent opgegeven als loginHint de meest betrouwbare accounthint van stille en interactieve aanvragen.

De login_hint optionele claim biedt een hint voor Microsoft Entra-id over het gebruikersaccount dat zich probeert aan te melden. Als u de accountselectieprompt wilt omzeilen die doorgaans wordt weergegeven tijdens interactieve verificatieaanvragen, geeft u de loginHint volgende informatie op:

const silentRequest = {
    scopes: ["User.Read", "Mail.Read"],
    loginHint: "user@contoso.com"
};

try {
    const loginResponse = await msalInstance.ssoSilent(silentRequest);
} catch (err) {
    if (err instanceof InteractionRequiredAuthError) {
        const loginResponse = await msalInstance.loginPopup(silentRequest).catch(error => {
            // handle error
        });
    } else {
        // handle error
    }
}

In dit voorbeeld loginHint bevat de e-mail of UPN van de gebruiker, die wordt gebruikt als een hint tijdens interactieve tokenaanvragen. De hint kan worden doorgegeven tussen toepassingen om eenmalige aanmelding op de achtergrond mogelijk te maken, waarbij toepassing A zich kan aanmelden bij een gebruiker, de loginHintclaim kan lezen en vervolgens de claim en de huidige tenantcontext naar toepassing B verzenden. Microsoft Entra ID probeert het aanmeldingsformulier vooraf in te vullen of de prompt voor accountselectie te omzeilen en direct door te gaan met het verificatieproces voor de opgegeven gebruiker.

Als de gegevens in de login_hint claim niet overeenkomen met een bestaande gebruiker, worden ze omgeleid om de standaardaanmeldingservaring te doorlopen, inclusief accountselectie.

Een sessie-id gebruiken

Als u een sessie-id wilt gebruiken, voegt u sid toe als een optionele claim voor de id-tokens van uw app. Met sid de claim kan een toepassing de Microsoft Entra-sessie van een gebruiker identificeren, onafhankelijk van de accountnaam of gebruikersnaam. Zie Optionele claims in uw app opnemen voor meer informatie over het toevoegen van optionele claims zoals sid. Gebruik de sessie-id (SID) in stille verificatieaanvragen die u met ssoSilent maakt in MSAL.js.

const request = {
  scopes: ["user.read"],
  sid: sid,
};

 try {
    const loginResponse = await msalInstance.ssoSilent(request);
} catch (err) {
    if (err instanceof InteractionRequiredAuthError) {
        const loginResponse = await msalInstance.loginPopup(request).catch(error => {
            // handle error
        });
    } else {
        // handle error
    }
}

Een accountobject gebruiken

Als u de gebruikersaccountgegevens kent, kunt u het gebruikersaccount ook ophalen met behulp van de methode getAccountByUsername() of getAccountByHomeId():

const username = "test@contoso.com";
const myAccount  = msalInstance.getAccountByUsername(username);

const request = {
    scopes: ["User.Read"],
    account: myAccount
};

try {
    const loginResponse = await msalInstance.ssoSilent(request);
} catch (err) {
    if (err instanceof InteractionRequiredAuthError) {
        const loginResponse = await msalInstance.loginPopup(request).catch(error => {
            // handle error
        });
    } else {
        // handle error
    }
}

Zonder hint van de gebruiker

U kunt proberen de ssoSilent methode te gebruiken zonder dat er een accountwordt doorgegeven, sid of login_hint zoals wordt weergegeven in de volgende code:

const request = {
    scopes: ["User.Read"]
};

try {
    const loginResponse = await msalInstance.ssoSilent(request);
} catch (err) {
    if (err instanceof InteractionRequiredAuthError) {
        const loginResponse = await msalInstance.loginPopup(request).catch(error => {
            // handle error
        });
    } else {
        // handle error
    }
}

Er is echter een kans op fouten bij stille aanmelding als de toepassing meerdere gebruikers in één browsersessie heeft of als de gebruiker meerdere accounts voor die sessie met één browser heeft. De volgende fout kan worden weergegeven als er meerdere accounts beschikbaar zijn:

InteractionRequiredAuthError: interaction_required: AADSTS16000: Either multiple user identities are available for the current request or selected account is not supported for the scenario.

De fout geeft aan dat de server niet kan bepalen welk account moet worden aangemeld en dat een van de parameters in het vorige voorbeeld (account, login_hint, sid) of een interactieve aanmelding nodig is om het account te kiezen.

Overwegingen bij het gebruik van `ssoSilent`

Omleidings-URI (antwoord-URL)

Voor betere prestaties en om problemen te voorkomen, stelt u de redirectUri in op een lege pagina of een andere pagina die geen MSAL gebruikt.

Als de toepassingsgebruikers alleen pop-up- en stille methoden gebruiken, stelt u het redirectUri in op het PublicClientApplication configuratieobject.
Als de toepassing ook omleidingsmethoden gebruikt, stelt u de redirectUri optie per aanvraag in.

Cookies van derden

ssoSilent probeert een verborgen iframe te openen en een bestaande sessie opnieuw te gebruiken met Microsoft Entra-id. Dit werkt niet in browsers die cookies van derden zoals Safari blokkeren en leiden tot een interactiefout:

InteractionRequiredAuthError: login_required: AADSTS50058: A silent sign-in request was sent but no user is signed in. The cookies used to represent the user's session were not sent in the request to Azure AD

Om de fout op te lossen, moet de gebruiker een interactieve verificatieaanvraag maken met behulp van de loginPopup() of loginRedirect(). In sommige gevallen kan de promptwaarde geen worden gebruikt in combinatie met een interactieve MSAL.js methode om eenmalige aanmelding te bereiken. Zie interactieve aanvragen met prompt=geen voor meer. Als u de aanmeldingsgegevens van de gebruiker al hebt, kunt u de optionele parameters loginHint of sid doorgeven om een specifiek account aan te melden.

Eenmalige aanmelding met prompt=login negeren

Als u de voorkeur geeft aan Microsoft Entra ID om de gebruiker te vragen hun referenties in te voeren ondanks een actieve sessie met de autorisatieserver, kunt u de parameter voor de aanmeldingsprompt gebruiken in aanvragen met MSAL.js. Zie MSAL.js promptgedrag voor meer informatie.

MSAL.js biedt functiepariteit met ADAL.js voor Microsoft Entra-verificatiescenario's. Om de migratie van ADAL.js naar MSAL.js eenvoudig te maken en de verificatiestatus tussen apps te delen, leest de bibliotheek het id-token dat de sessie van de gebruiker vertegenwoordigt in ADAL.js cache. Als u hiervan wilt profiteren wanneer u migreert vanuit ADAL.js, moet u ervoor zorgen dat de bibliotheken worden gebruikt localStorage voor het opslaan van tokens in de cache. Stel als volgt de cacheLocation in op localStorage in zowel de MSAL.js- als ADAL.js-configuratie bij de initialisatie:


// In ADAL.js
window.config = {
  clientId: "1111-2222-3333-4444-55555555",
  cacheLocation: "localStorage",
};

var authContext = new AuthenticationContext(config);

// In latest MSAL.js version
const config = {
  auth: {
    clientId: "1111-2222-3333-4444-55555555",
  },
  cache: {
    cacheLocation: "localStorage",
  },
};

const msalInstance = new msal.PublicClientApplication(config);

Volgende stappen

Zie voor meer informatie over SSO: