Konvertera en klientorganisationsapp till multitenant på Microsoft Entra-ID

  • Artikel

Om du erbjuder ett SaaS-program (Programvara som en tjänst) till många organisationer kan du konfigurera ditt program för att acceptera inloggningar från alla Microsoft Entra-klienter genom att konvertera det till flera klienter. Användare i alla Microsoft Entra-klienter kommer att kunna logga in på ditt program när de har samtyckt till att använda sitt konto med ditt program.

För befintliga appar med ett eget kontosystem (eller andra inloggningar från andra molnleverantörer) bör du lägga till inloggningskod via OAuth2, OpenID Anslut eller SAML och lägga till knappen Logga in med Microsoft i ditt program.

I den här guiden utför du de fyra steg som krävs för att konvertera en enskild klientapp till en Microsoft Entra-app för flera klienter:

  1. Uppdatera programregistreringen så att den är multitenant
  2. Uppdatera koden för att skicka begäranden till /common slutpunkten
  3. Uppdatera koden för att hantera flera utfärdarvärden
  4. Förstå användar- och administratörsmedgivande och göra lämpliga kodändringar

Om du vill prova att använda något av våra exempel kan du läsa Skapa ett SaaS-webbprogram med flera klientorganisationer som anropar Microsoft Graph med hjälp av Microsoft Entra-ID och OpenID-Anslut

Förutsättningar

Uppdatera registreringen så att den är multitenant

Som standard är webbapps-/API-registreringar i Microsoft Entra-ID:t en enda klientorganisation när de skapas. Om du vill göra registreringen multitenant loggar du in på administrationscentret för Microsoft Entra och väljer den appregistrering som du vill uppdatera. När appregistreringen är öppen väljer du fönstret Autentisering och går till avsnittet Kontotyper som stöds. Ändra inställningen till Konton i en organisationskatalog.

När ett program med en enda klientorganisation skapas i administrationscentret för Microsoft Entra är ett av objekten som visas på sidan Översikt program-ID.URI. Det här är ett av sätten som ett program identifieras på i protokollmeddelanden och kan läggas till när som helst. App-ID-URI:n för appar med en enskild klientorganisation kan vara globalt unik i den klientorganisationen. För appar med flera klienter måste det däremot vara globalt unikt för alla klienter, vilket säkerställer att Microsoft Entra-ID:t kan hitta appen för alla klienter.

Om namnet på din klientorganisation till exempel var contoso.onmicrosoft.com skulle en giltig app-ID-URI vara https://contoso.onmicrosoft.com/myapp. Om app-ID-URI:n inte följer det här mönstret misslyckas inställningen av ett program som multitenant.

Uppdatera koden för att skicka begäranden till /common

Med ett program med flera klienter kan programmet inte omedelbart avgöra vilken klientorganisation användaren kommer från, så begäranden kan inte skickas till en klients slutpunkt. I stället skickas begäranden till en gemensam slutpunkt (https://login.microsoftonline.com/common) som hanterar alla Microsoft Entra-klienter, som fungerar som en central hubb som hanterar begäranden.

Öppna din app i din IDE och redigera koden och ändra värdet för ditt klient-ID till /common. Den här slutpunkten är inte en klient eller en utfärdare själv. När Microsofts identitetsplattform tar emot en begäran på /common slutpunkten loggar den in användaren och identifierar därmed vilken klient som användaren kommer från. Den här slutpunkten fungerar med alla autentiseringsprotokoll som stöds av Microsoft Entra ID (OpenID Anslut, OAuth 2.0, SAML 2.0, WS-Federation).

Inloggningssvaret till programmet innehåller sedan en token som representerar användaren. Utfärdarvärdet i token talar om för ett program vilken klientorganisation användaren kommer från. När ett svar returneras från /common slutpunkten motsvarar utfärdarvärdet i token användarens klientorganisation.

Kommentar

Det finns i själva verket två myndigheter för program med flera klienter:

  • https://login.microsoftonline.com/common för program som bearbetar konton i en organisationskatalog (alla Microsoft Entra-kataloger) och personliga Microsoft-konton (t.ex. Skype, XBox).
  • https://login.microsoftonline.com/organizations för program som bearbetar konton i en organisationskatalog (alla Microsoft Entra-kataloger):

Förklaringarna i det här dokumentet använder common. Men du kan ersätta det med organizations om ditt program inte stöder Microsofts personliga konton.

Uppdatera koden för att hantera flera utfärdarvärden

Webbprogram och webb-API:er tar emot och validerar token från Microsofts identitetsplattform. Interna klientprogram validerar inte åtkomsttoken och måste behandla dem som ogenomskinliga. De begär och tar i stället emot token från Microsofts identitetsplattform och gör det för att skicka dem till API:er, där de sedan verifieras.

Program med flera klienter måste utföra fler kontroller vid validering av en token. Ett program med flera klientorganisationer har konfigurerats för att använda nycklars metadata från /organizations eller /common nycklars URL:er. Programmet måste verifiera att issuer egenskapen i de publicerade metadata matchar anspråket iss i token, förutom den vanliga kontrollen att anspråket iss i token innehåller klient-ID-anspråket (tid). Mer information finns i Verifiera token.

För att en användare ska kunna logga in på ett program i Microsoft Entra-ID måste programmet representeras i användarens klientorganisation. Detta gör att organisationen kan göra saker som att tillämpa unika principer när användare från deras klientorganisation loggar in på programmet. För ett program med en enda klientorganisation kan man använda registreringen via administrationscentret för Microsoft Entra.

För ett program med flera klienter finns den första registreringen för programmet i Microsoft Entra-klientorganisationen som används av utvecklaren. När en användare från en annan klientorganisation loggar in på programmet för första gången ber Microsoft Entra-ID dem att samtycka till de behörigheter som programmet begär. Om de samtycker skapas en representation av programmet som kallas tjänstens huvudnamn i användarens klientorganisation och inloggningen kan fortsätta. En delegering skapas också i katalogen som registrerar användarens medgivande till programmet. Mer information om programmets program- och ServicePrincipal-objekt och hur de relaterar till varandra finns i Programobjekt och objekt för tjänstens huvudnamn.

Diagram som illustrerar en användares medgivande till en app med en enda nivå.

Den här medgivandeupplevelsen påverkas av de behörigheter som begärs av programmet. Microsofts identitetsplattform stöder två typer av behörigheter.

  • Delegerad: Den här behörigheten ger ett program möjlighet att fungera som en inloggad användare för en delmängd av de saker som användaren kan göra. Du kan till exempel ge ett program delegerad behörighet att läsa den inloggade användarens kalender.
  • Endast app: Den här behörigheten beviljas direkt till programmets identitet. Du kan till exempel ge ett program endast appbehörighet för att läsa listan över användare i en klientorganisation, oavsett vem som är inloggad i programmet.

Vissa behörigheter kan godkännas av en vanlig användare, medan andra kräver en klientadministratörs medgivande.

Mer information om användar- och administratörsmedgivande finns i Konfigurera arbetsflödet för administratörsmedgivande.

Appspecifika behörigheter kräver alltid medgivande av en klientadministratör. Om ditt program begär en appbehörighet och en användare försöker logga in på programmet visas ett felmeddelande om att användaren inte kan samtycka.

Vissa delegerade behörigheter kräver också en klientadministratörs medgivande. Möjligheten att till exempel skriva tillbaka till Microsoft Entra-ID som den inloggade användaren kräver en klientadministratörs medgivande. Om en vanlig användare försöker logga in på ett program som begär en delegerad behörighet som kräver administratörsmedgivande får appen ett fel, precis som med appbehörighet. Om en behörighet kräver administratörsmedgivande bestäms av utvecklaren som publicerade resursen och finns i dokumentationen för resursen. Behörighetsdokumentationen för Microsoft Graph API anger vilka behörigheter som kräver administratörsmedgivande.

Om ditt program använder behörigheter som kräver administratörsmedgivande kan du överväga att lägga till en knapp eller länk där administratören kan initiera åtgärden. Den begäran som ditt program skickar för den här åtgärden är den vanliga OAuth2/OpenID-Anslut auktoriseringsbegäran som även innehåller frågesträngsparameternprompt=consent. När administratören har samtyckt och tjänstens huvudnamn har skapats i kundens klientorganisation behöver efterföljande inloggningsbegäranden inte parametern prompt=consent . Eftersom administratören har beslutat att de begärda behörigheterna är acceptabla uppmanas inga andra användare i klientorganisationen att godkänna dem från och med då.

En klientadministratör kan inaktivera möjligheten för vanliga användare att samtycka till program. Om den här funktionen har inaktiverats krävs alltid administratörens godkännande för program som ska användas i klienten. Du kan testa ditt program med slutanvändarens medgivande inaktiverat i administrationscentret för Microsoft Entra. I Företagsprogram>Medgivande och behörigheter kontrollerar du alternativet Tillåt inte användarmedgivande.

Parametern prompt=consent kan också användas av program som begär behörigheter som inte kräver administratörsmedgivande. Ett exempel på när detta skulle användas är om programmet kräver en upplevelse där klientadministratören "registrerar sig" en gång och inga andra användare uppmanas att ge sitt medgivande från den tidpunkten.

Om ett program kräver administratörsmedgivande och en administratör loggar in utan att parametern prompt=consent skickas, gäller det endast för deras användarkonto när administratören godkänner programmet. Vanliga användare kommer fortfarande inte att kunna logga in eller samtycka till programmet. Den här funktionen är användbar om du vill ge klientadministratören möjlighet att utforska ditt program innan andra användare får åtkomst.

Ditt program kan ha flera nivåer, där var och en representeras av sin egen registrering i Microsoft Entra-ID. Till exempel ett internt program som anropar ett webb-API eller ett webbprogram som anropar ett webb-API. I båda dessa fall begär klienten (intern app eller webbapp) behörighet att anropa resursen (webb-API). För att klienten ska kunna godkännas i en kunds klientorganisation måste alla resurser som den begär behörigheter till redan finnas i kundens klientorganisation. Om det här villkoret inte uppfylls returnerar Microsoft Entra-ID ett fel om att resursen måste läggas till först.

Flera nivåer i en enda klientorganisation

Detta kan vara ett problem om ditt logiska program består av två eller flera programregistreringar, till exempel en separat klient och resurs. Hur får du resursen till den externa klientorganisationen först? Microsoft Entra-ID omfattar det här fallet genom att aktivera klient- och resursmedgivande i ett enda steg. Användaren ser summan av de behörigheter som begärs av både klienten och resursen på sidan medgivande. För att aktivera det här beteendet måste resursens programregistrering inkludera klientens app-ID som ett knownClientApplications i dess programmanifest. Till exempel:

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

Detta visas i ett programexempel för flera klientorganisationer. Följande diagram innehåller en översikt över medgivande för en app med flera nivåer som registrerats i en enda klientorganisation.

Diagram som illustrerar medgivande till en känd klientapp på flera nivåer.

Flera nivåer i flera klientorganisationer

Ett liknande fall inträffar om de olika nivåerna i ett program registreras i olika klientorganisationer. Du kan till exempel överväga att skapa ett internt klientprogram som anropar Exchange Online-API:et. För att utveckla det inbyggda programmet och senare för att det interna programmet ska kunna köras i en kunds klientorganisation måste Tjänstens huvudnamn för Exchange Online finnas. I det här fallet måste utvecklaren och kunden köpa Exchange Online för att tjänstens huvudnamn ska skapas i deras klientorganisationer.

Om det är ett API som skapats av en annan organisation än Microsoft måste utvecklaren av API:et tillhandahålla ett sätt för sina kunder att godkänna programmet i sina kunders klientorganisationer. Den rekommenderade designen är att tredjepartsutvecklaren skapar API:et så att det även kan fungera som en webbklient för att implementera registrering. Så här gör du:

  1. Följ de tidigare avsnitten för att se till att API:et implementerar kraven för registrering/kod för flera klientprogram.
  2. Förutom att exponera API:ets omfång/roller kontrollerar du att registreringen innehåller behörigheten "Logga in och läs användarprofil" (tillhandahålls som standard).
  3. Implementera en inloggnings-/registreringssida i webbklienten och följ vägledningen för administratörsmedgivande.
  4. När användaren har godkänt programmet skapas länkarna för tjänstens huvudnamn och medgivandedelegering i klientorganisationen och det interna programmet kan hämta token för API:et.

Följande diagram innehåller en översikt över medgivande för en app med flera nivåer som registrerats i olika klientorganisationer.

Diagram som illustrerar medgivande till flernivåapp för flera parter.

Användare och administratörer kan återkalla medgivande till ditt program när som helst:

  • Användare återkallar åtkomsten till enskilda program genom att ta bort dem från listan med Åtkomstpanelen-program.
  • Administratörer återkallar åtkomsten till program genom att ta bort dem med hjälp av avsnittet Företagsprogram i administrationscentret för Microsoft Entra. Välj programmet och gå till fliken Behörigheter för att återkalla åtkomsten.

Om en administratör godkänner ett program för alla användare i en klientorganisation kan användarna inte återkalla åtkomst individuellt. Endast administratören kan återkalla åtkomsten och endast för hela programmet.

Program för flera klienter och cachelagring av åtkomsttoken

Program med flera klienter kan också hämta åtkomsttoken för att anropa API:er som skyddas av Microsoft Entra-ID. Ett vanligt fel när du använder Microsoft Authentication Library (MSAL) med ett program med flera klientorganisationer är att först begära en token för en användare med hjälp av /common, ta emot ett svar och sedan begära en efterföljande token för samma användare som också använder /common. Eftersom svaret från Microsoft Entra ID kommer från en klientorganisation, inte /common, cachelagrar MSAL token som från klientorganisationen. Det efterföljande anropet till /common för att hämta en åtkomsttoken för användaren missar cacheposten och användaren uppmanas att logga in igen. För att undvika att cacheminnet saknas kontrollerar du att efterföljande anrop för en redan inloggad användare görs till klientorganisationens slutpunkt.

Se även