App met één tenant converteren naar multitenant in Microsoft Entra-id

  • Artikel

Als u een SaaS-toepassing (Software as a Service) aan veel organisaties aanbiedt, kunt u uw toepassing zo configureren dat aanmeldingen van elke Microsoft Entra-tenant worden geaccepteerd door deze te converteren naar multitenant. Gebruikers in elke Microsoft Entra-tenant kunnen zich aanmelden bij uw toepassing nadat ze toestemming hebben gegeven om hun account met uw toepassing te gebruiken.

Voor bestaande apps met een eigen accountsysteem (of andere aanmeldingen van andere cloudproviders) moet u aanmeldingscode toevoegen via OAuth2, OpenID Verbinding maken of SAML en een knop Aanmelden met Microsoft in uw toepassing plaatsen.

In deze handleiding voert u de vier stappen uit die nodig zijn om één tenant-app te converteren naar een Microsoft Entra-app met meerdere tenants:

  1. Uw toepassingsregistratie bijwerken zodat deze multitenant is
  2. Uw code bijwerken om aanvragen naar het /common eindpunt te verzenden
  3. Werk uw code bij om meerdere verlenerwaarden te verwerken
  4. Inzicht in toestemming van gebruikers en beheerders en het aanbrengen van de juiste codewijzigingen

Als u een van onze voorbeelden wilt gebruiken, raadpleegt u Een multitenant SaaS-webtoepassing bouwen die Microsoft Graph aanroept met behulp van Microsoft Entra ID en OpenID Verbinding maken

Vereisten

Registratie bijwerken om multitenant te zijn

Standaard zijn web-app-/API-registraties in Microsoft Entra ID één tenant bij het maken. Als u de registratie multitenant wilt maken, meldt u zich aan bij het Microsoft Entra-beheercentrum en selecteert u de app-registratie die u wilt bijwerken. Wanneer de app-registratie is geopend, selecteert u het deelvenster Verificatie en gaat u naar de sectie Ondersteunde accounttypen . Wijzig de instelling in Accounts in een organisatiemap.

Wanneer een toepassing met één tenant wordt gemaakt in het Microsoft Entra-beheercentrum, is een van de items op de overzichtspagina de URI voor de toepassings-id. Dit is een van de manieren waarop een toepassing wordt geïdentificeerd in protocolberichten en kan op elk gewenst moment worden toegevoegd. De app-id-URI voor apps met één tenant kan wereldwijd uniek zijn binnen die tenant. Voor multitenant-apps moet het daarentegen wereldwijd uniek zijn voor alle tenants, wat ervoor zorgt dat Microsoft Entra ID de app in alle tenants kan vinden.

Als de naam van uw tenant bijvoorbeeld was contoso.onmicrosoft.com , zou een geldige URI voor de app-id zijn https://contoso.onmicrosoft.com/myapp. Als de app-id-URI dit patroon niet volgt, mislukt het instellen van een toepassing als multitenant.

Uw code bijwerken om aanvragen te verzenden naar /common

Met een multitenant-toepassing kan de toepassing niet direct zien van welke tenant de gebruiker afkomstig is, zodat aanvragen niet naar het eindpunt van een tenant kunnen worden verzonden. In plaats daarvan worden aanvragen verzonden naar een gemeenschappelijk eindpunt (https://login.microsoftonline.com/common) dat fungeert voor alle Microsoft Entra-tenants, die fungeren als een centrale hub die aanvragen verwerkt.

Open uw app in uw IDE en bewerk uw code en wijzig de waarde voor uw tenant-id in /common. Dit eindpunt is geen tenant of een verlener zelf. Wanneer het Microsoft Identity Platform een aanvraag op het /common eindpunt ontvangt, wordt de gebruiker aangemeld, waardoor de tenant wordt ontdekt waaruit de gebruiker afkomstig is. Dit eindpunt werkt met alle verificatieprotocollen die worden ondersteund door de Microsoft Entra-id (OpenID Verbinding maken, OAuth 2.0, SAML 2.0, WS-Federation).

Het aanmeldingsantwoord voor de toepassing bevat vervolgens een token dat de gebruiker vertegenwoordigt. De waarde van de uitgever in het token vertelt een toepassing van waaruit de gebruiker afkomstig is. Wanneer een antwoord wordt geretourneerd vanaf het /common eindpunt, komt de waarde van de verlener in het token overeen met de tenant van de gebruiker.

Notitie

Er zijn in werkelijkheid twee instanties voor multitenant-toepassingen:

  • https://login.microsoftonline.com/common voor toepassingen die accounts verwerken in elke organisatiedirectory (elke Microsoft Entra-directory) en persoonlijke Microsoft-accounts (bijvoorbeeld Skype, XBox).
  • https://login.microsoftonline.com/organizations voor toepassingen die accounts verwerken in elke organisatiemap (elke Microsoft Entra-directory):

De uitleg in dit document gebruikt common. Maar u kunt deze vervangen door organizations als uw toepassing geen persoonlijke Microsoft-accounts ondersteunt.

Werk uw code bij om meerdere verlenerwaarden te verwerken

Webtoepassingen en web-API's ontvangen en valideren tokens van het Microsoft Identity Platform. Systeemeigen clienttoepassingen valideren geen toegangstokens en moeten ze behandelen als ondoorzichtig. Ze vragen in plaats daarvan tokens aan en ontvangen tokens van het Microsoft Identity Platform en doen dit om ze naar API's te verzenden, waar ze vervolgens worden gevalideerd.

Multitenant-toepassingen moeten meer controles uitvoeren bij het valideren van een token. Een toepassing met meerdere tenants is geconfigureerd voor het verbruik van metagegevens van sleutels of /organizations/common sleutel-URL's. De toepassing moet valideren dat de issuer eigenschap in de gepubliceerde metagegevens overeenkomt met de iss claim in het token, naast de gebruikelijke controle of de iss claim in het token de tenant-id (tid) claim bevat. Zie Tokens valideren voor meer informatie.

Als een gebruiker zich kan aanmelden bij een toepassing in Microsoft Entra ID, moet de toepassing worden weergegeven in de tenant van de gebruiker. Hierdoor kan de organisatie bijvoorbeeld unieke beleidsregels toepassen wanneer gebruikers van hun tenant zich aanmelden bij de toepassing. Voor een toepassing met één tenant kunt u de registratie gebruiken via het Microsoft Entra-beheercentrum.

Voor een multitenant-toepassing bevindt de eerste registratie voor de toepassing zich in de Microsoft Entra-tenant die door de ontwikkelaar wordt gebruikt. Wanneer een gebruiker van een andere tenant zich voor het eerst aanmeldt bij de toepassing, vraagt Microsoft Entra-id hen om toestemming te geven voor de machtigingen die door de toepassing zijn aangevraagd. Als ze toestemming geven, wordt een weergave van de toepassing met de naam een service-principal gemaakt in de tenant van de gebruiker en kan de aanmelding worden voortgezet. Er wordt ook een delegatie gemaakt in de map waarin de toestemming van de gebruiker voor de toepassing wordt vastgelegd. Zie Toepassingsobjecten en service-principalobjecten voor meer informatie over de toepassings- en ServicePrincipal-objecten en hoe deze zich verhouden tot elkaar.

Diagram waarin de toestemming van een gebruiker voor een app met één laag wordt weergegeven.

Deze toestemmingservaring wordt beïnvloed door de machtigingen die door de toepassing zijn aangevraagd. Het Microsoft Identity Platform ondersteunt twee soorten machtigingen;

  • Gedelegeerd: Met deze machtiging verleent een toepassing de mogelijkheid om als aangemelde gebruiker te fungeren voor een subset van de dingen die de gebruiker kan doen. U kunt bijvoorbeeld een toepassing de gedelegeerde machtiging verlenen om de agenda van de aangemelde gebruiker te lezen.
  • Alleen-app: deze machtiging wordt rechtstreeks verleend aan de identiteit van de toepassing. U kunt bijvoorbeeld een toepassing de app alleen toestemming geven om de lijst met gebruikers in een tenant te lezen, ongeacht wie is aangemeld bij de toepassing.

Sommige machtigingen kunnen worden toegestaan door een gewone gebruiker, terwijl anderen toestemming van een tenantbeheerder vereisen.

Zie De werkstroom voor beheerderstoestemming configureren voor meer informatie over toestemming van gebruikers en beheerders.

Bij app-specifieke machtigingen is er altijd toestemming van een tenantbeheerder nodig. Als uw toepassing een machtiging voor alleen-apps aanvraagt en een gebruiker zich probeert aan te melden bij de toepassing, wordt er een foutbericht weergegeven met de mededeling dat de gebruiker geen toestemming kan geven.

Voor bepaalde gedelegeerde machtigingen is ook toestemming van een tenantbeheerder vereist. De mogelijkheid om terug te schrijven naar Microsoft Entra-id als de aangemelde gebruiker vereist bijvoorbeeld toestemming van een tenantbeheerder. Als een gewone gebruiker zich probeert aan te melden bij een toepassing die een gedelegeerde machtiging aanvraagt waarvoor beheerderstoestemming is vereist, krijgt de app een foutmelding. Of een machtiging beheerderstoestemming vereist, wordt bepaald door de ontwikkelaar die de resource heeft gepubliceerd en kan worden gevonden in de documentatie voor de resource. De documentatie over machtigingen voor de Microsoft Graph API geeft aan welke machtigingen beheerderstoestemming vereisen.

Als uw toepassing machtigingen gebruikt waarvoor beheerderstoestemming is vereist, kunt u een knop of koppeling toevoegen waar de beheerder de actie kan initiëren. De aanvraag die uw toepassing verzendt voor deze actie is de gebruikelijke OAuth2/OpenID Verbinding maken autorisatieaanvraag die ook de prompt=consent querytekenreeksparameter bevat. Nadat de beheerder toestemming heeft gegeven en de service-principal is gemaakt in de tenant van de klant, hebben volgende aanmeldingsaanvragen de prompt=consent parameter niet nodig. Aangezien de beheerder heeft besloten dat de aangevraagde machtigingen acceptabel zijn, worden vanaf dat moment geen andere gebruikers in de tenant om toestemming gevraagd.

Tenantbeheerders kunnen uitschakelen dat normale gebruikers toestemming kunnen geven voor toepassingen. Als dit wordt uitgeschakeld, is er altijd beheerderstoestemming nodig om een toepassing in een tenant te kunnen gebruiken. U kunt uw toepassing testen met toestemming van eindgebruikers uitgeschakeld in het Microsoft Entra-beheercentrum. Schakel in Bedrijfstoepassingen>Toestemming en machtigingen de optie Gebruikerstoestemming niet toestaan in.

De prompt=consent parameter kan ook worden gebruikt door toepassingen die machtigingen aanvragen waarvoor geen beheerderstoestemming is vereist. Een voorbeeld van wanneer dit wordt gebruikt, is als voor de toepassing een ervaring is vereist waarbij de tenantbeheerder zich eenmalig registreert en vanaf dat moment geen andere gebruikers om toestemming wordt gevraagd.

Als voor een toepassing beheerderstoestemming is vereist en een beheerder zich aanmeldt zonder dat de prompt=consent parameter wordt verzonden, wordt de beheerder toestemming gegeven voor de toepassing die alleen van toepassing is op het gebruikersaccount. Gewone gebruikers kunnen zich nog steeds niet aanmelden of toestemming geven voor de toepassing. Deze functie is handig als u de tenantbeheerder de mogelijkheid wilt geven om uw toepassing te verkennen voordat andere gebruikers toegang hebben.

Uw toepassing kan meerdere lagen hebben, waarbij elk wordt vertegenwoordigd door een eigen registratie in Microsoft Entra ID. Bijvoorbeeld een systeemeigen toepassing die een web-API aanroept of een webtoepassing die een web-API aanroept. In beide gevallen vraagt de client (systeemeigen app of web-app) machtigingen aan om de resource (web-API) aan te roepen. Om de client toestemming te geven voor de tenant van een klant, moeten alle resources waarvoor machtigingen worden aangevraagd, al aanwezig zijn in de tenant van de klant. Als niet aan deze voorwaarde wordt voldaan, retourneert Microsoft Entra-id een fout dat de resource eerst moet worden toegevoegd.

Meerdere lagen in één tenant

Dit kan een probleem zijn als uw logische toepassing bestaat uit twee of meer toepassingsregistraties, bijvoorbeeld een afzonderlijke client en resource. Hoe haalt u de resource eerst op in de externe tenant? Microsoft Entra ID heeft betrekking op dit geval door client en resource in één stap toestemming te geven. De gebruiker ziet het totaal van de machtigingen die zijn aangevraagd door zowel de client als de resource op de toestemmingspagina. Als u dit gedrag wilt inschakelen, moet de toepassingsregistratie van de resource de app-id van de client als een knownClientApplications in het toepassingsmanifest bevatten. Voorbeeld:

"knownClientApplications": ["12ab34cd-56ef-78gh-90ij11kl12mn"]

Dit wordt gedemonstreerd in een voorbeeld van een multitenant-toepassing. In het volgende diagram ziet u een overzicht van toestemming voor een app met meerdere lagen die is geregistreerd in één tenant.

Diagram waarin toestemming wordt gegeven voor een bekende client-app met meerdere lagen.

Meerdere lagen in meerdere tenants

Een vergelijkbaar geval treedt op als de verschillende lagen van een toepassing zijn geregistreerd in verschillende tenants. Denk bijvoorbeeld aan het bouwen van een systeemeigen clienttoepassing die de Exchange Online-API aanroept. Als u de systeemeigen toepassing wilt ontwikkelen en later de systeemeigen toepassing wilt uitvoeren in de tenant van een klant, moet de Exchange Online-service-principal aanwezig zijn. In dit geval moeten de ontwikkelaar en de klant Exchange Online aanschaffen om de service-principal in hun tenants te kunnen maken.

Als het een API is die is gebouwd door een andere organisatie dan Microsoft, moet de ontwikkelaar van de API een manier bieden voor hun klanten om toestemming te geven voor de toepassing in de tenants van hun klanten. Het aanbevolen ontwerp is voor de externe ontwikkelaar om de API te bouwen, zodat deze ook kan functioneren als een webclient om registratie te implementeren. Dit doet u als volgt:

  1. Volg de eerdere secties om ervoor te zorgen dat de API de vereisten voor registratie/code voor meerdere tenants implementeert.
  2. Zorg er niet alleen voor dat de api-bereiken/-rollen beschikbaar worden gemaakt, maar ook of de registratie de machtiging 'Aanmelden en gebruikersprofiel lezen' bevat (standaard opgegeven).
  3. Implementeer een aanmeldings-/registratiepagina in de webclient en volg de richtlijnen voor beheerderstoestemming .
  4. Zodra de gebruiker toestemming heeft gegeven voor de toepassing, worden de koppelingen voor service-principals en toestemmingsdelegering gemaakt in hun tenant en kan de systeemeigen toepassing tokens voor de API ophalen.

In het volgende diagram ziet u een overzicht van toestemming voor een app met meerdere lagen die is geregistreerd in verschillende tenants.

Diagram waarin toestemming voor app met meerdere lagen voor meerdere partijen wordt weergegeven.

Gebruikers en beheerders kunnen op elk gewenst moment toestemming voor uw toepassing intrekken:

  • Gebruikers trekken de toegang tot afzonderlijke toepassingen in door ze te verwijderen uit hun lijst met Toegangsvenster toepassingen.
  • Beheer istrators intrekken de toegang tot toepassingen door ze te verwijderen met behulp van de Sectie Bedrijfstoepassingen van het Microsoft Entra-beheercentrum. Selecteer de toepassing en navigeer naar het tabblad Machtigingen om de toegang in te trekken.

Als een beheerder toestemming geeft voor een toepassing voor alle gebruikers in een tenant, kunnen gebruikers de toegang niet afzonderlijk intrekken. Alleen de beheerder kan de toegang intrekken en alleen voor de hele toepassing.

Multitenant-toepassingen en cachetoegangstokens

Toepassingen met meerdere tenants kunnen ook toegangstokens krijgen om API's aan te roepen die worden beveiligd door Microsoft Entra-id. Een veelvoorkomende fout bij het gebruik van de Microsoft Authentication Library (MSAL) met een toepassing met meerdere tenants is om in eerste instantie een token aan te vragen voor een gebruiker die een gebruiker gebruikt /common, een antwoord te ontvangen en vervolgens een volgend token aan te vragen voor dezelfde gebruiker die ook gebruikt /common. Omdat het antwoord van Microsoft Entra-id afkomstig is van een tenant, niet, slaat /commonMSAL het token in de cache op als afkomstig van de tenant. De volgende aanroep om /common een toegangstoken voor de gebruiker op te halen, mist de cachevermelding en de gebruiker wordt gevraagd zich opnieuw aan te melden. Om te voorkomen dat de cache ontbreekt, moet u ervoor zorgen dat volgende aanroepen voor een al aangemelde gebruiker worden gedaan naar het eindpunt van de tenant.

Zie ook