Göra ditt program till flera klientorganisationer

Om du erbjuder ett SaaS-program (Programvara som en tjänst) till många organisationer kan du konfigurera programmet så att det accepterar inloggningar från valfri Azure Active Directory-klientorganisation (Azure AD) genom att konvertera det till flera klientorganisationer. Användare i valfri Azure AD klientorganisation 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 Connect 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 Azure AD app för flera innehavare:

  1. Uppdatera programregistreringen så att den gäller för flera innehavare
  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

Du kan också referera till exemplet; Skapa ett SaaS-webbprogram för flera innehavare som anropar Microsoft Graph med hjälp av Azure AD och OpenID Connect. Den här metoden förutsätter att du är bekant med att skapa ett program med en enda klientorganisation för Azure AD. Annars börjar du med någon av snabbstarterna på utvecklarguidens startsida.

Uppdatera registreringen för att vara flera klientorganisationer

Som standard är webbapps-/API-registreringar i Azure AD en enda klient när de skapas. Om du vill göra registreringen till flera klientorganisationer letar du upp avsnittet Kontotyper som stöds i fönstret Autentisering i programregistreringen i Azure-Portal. Ändra inställningen till Konton i valfri organisationskatalog.

När ett program med en klientorganisation skapas via Azure-Portal är ett av objekten som visas på översiktssidanprogram-ID-URI:n. Detta är ett av sätten som ett program identifieras i protokollmeddelanden och kan läggas till när som helst. App-ID-URI:n för appar med en enda klientorganisation kan vara globalt unik i den klientorganisationen. För appar med flera klientorganisationer måste det däremot vara globalt unikt för alla klienter, vilket säkerställer att Azure AD kan hitta appen för alla klienter.

Om namnet på din klientorganisation till exempel var contoso.onmicrosoft.com en giltig app-ID-URI skulle vara https://contoso.onmicrosoft.com/myapp. Om App-ID-URI inte följer detta mönster misslyckas konfigurationen av ett program som ett program för flera klientorganisationer.

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

Med ett program för flera klientorganisationer, eftersom programmet inte omedelbart kan avgöra vilken klientorganisation användaren kommer från, kan begäranden inte skickas till en klients slutpunkt. I stället skickas begäranden till en slutpunkt som multiplexerar över alla Azure AD klienter: https://login.microsoftonline.com/common.

Redigera koden och ändra värdet för klientorganisationen till /common. Det är viktigt att observera att den här slutpunkten inte är en klientorganisation eller en utfärdare. 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 Azure AD (OpenID Connect, OAuth 2.0, SAML 2.0, WS-Federation).

Inloggningssvaret på 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.

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 klientorganisationer kan inte verifiera token genom att matcha utfärdarvärdet i metadata med issuer värdet i token. Ett program med flera klientorganisationer behöver logik för att avgöra vilka utfärdarvärden som är giltiga och som inte baseras på klientorganisations-ID-delen av utfärdarvärdet.

Om ett program för flera innehavare till exempel bara tillåter inloggning från specifika klienter som har registrerat sig för sin tjänst måste det kontrollera antingen issuer värdet eller anspråksvärdet tid i token för att se till att klientorganisationen finns i listan över prenumeranter. Om ett program för flera innehavare bara hanterar enskilda användare och inte fattar några åtkomstbeslut baserat på klienter kan det ignorera utfärdarvärdet helt och hållet.

I exemplen med flera klientorganisationer inaktiveras utfärdarvalidering för att aktivera alla Azure AD klientorganisation att logga in. /common Eftersom slutpunkten inte motsvarar en klientorganisation och inte är en utfärdare har den en mallad URL i stället för ett faktiskt värde när du undersöker utfärdarvärdet i metadata för/common:

https://sts.windows.net/{tenantid}/

För att säkerställa att appen har stöd för flera klienter ändrar du det relevanta avsnittet i koden för att säkerställa att utfärdarvärdet är inställt på {tenantid}.

Däremot använder program med en enda klient vanligtvis slutpunktsvärden för att konstruera metadata-URL:er som:

https://login.microsoftonline.com/contoso.onmicrosoft.com/.well-known/openid-configuration

för att ladda ned två viktiga informationsdelar som används för att verifiera token: klientens signeringsnycklar och utfärdarvärde.

Varje Azure AD klientorganisation har ett unikt utfärdarvärde för formuläret:

https://sts.windows.net/31537af4-6d77-4bb9-a681-d2394888ea26/

... där GUID-värdet är den namnsäkra versionen av klientorganisations-ID:t för klientorganisationen.

När ett program med en enda klientorganisation validerar en token kontrollerar den tokens signatur mot signeringsnycklarna från metadatadokumentet. Det här testet gör det möjligt att se till att utfärdarvärdet i token matchar det som hittades i metadatadokumentet.

För att en användare ska kunna logga in på ett program i Azure AD 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 Azure-Portal.

För ett program med flera klientorganisationer finns den första registreringen för programmet i den Azure AD klientorganisation 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 Azure AD dem att godkänna de behörigheter som begärs av programmet. 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, endast appar och delegerade.

  • En delegerad behörighet ger ett program möjlighet att fungera som en inloggad användare för en delmängd av det som användaren kan göra. Du kan till exempel ge ett program delegerad behörighet att läsa den inloggade användarens kalender.
  • En appbehörighet beviljas direkt till programmets identitet. Du kan till exempel ge ett program behörighet att endast använda appen 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 godkänna det.

Vissa delegerade behörigheter kräver också en klientadministratörs medgivande. Möjligheten att skriva tillbaka till Azure AD som den inloggade användaren kräver till exempel 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. Begäran som ditt program skickar för den här åtgärden är den vanliga OAuth2/OpenID Connect-auktoriseringsbegäran som även innehåller frågesträngsparametern prompt=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 godtagbara uppmanas inga andra användare i klientorganisationen att godkänna från och med den punkten.

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. Om du vill testa ditt program med slutanvändarmedgivande inaktiverat hittar du konfigurationsväxeln i Azure-Portal i avsnittet Användarinställningar under Företagsprogram.

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 godkänna 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 den endast för deras användarkonto när administratören godkänner programmet. Vanliga användare kommer fortfarande inte att kunna logga in eller godkänna 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, som var och en representeras av sin egen registrering i Azure AD. 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 Azure AD 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 hämtar du resursen till kundklientorganisationen först? Azure AD tar upp det här fallet genom att göra det möjligt att godkänna klient och resurs i ett enda steg. Användaren ser summan av de behörigheter som begärs av både klienten och resursen på sidan medgivande. Om du vill aktivera det här beteendet måste resursens programregistrering innehålla klientens app-ID som ett knownClientApplications i dess programmanifest. Exempel:

"knownClientApplications": ["94da0930-763f-45c7-8d26-04d5938baab2"]

Detta visas i ett webb-API-exempel med inbyggda klientanrop på flera nivåer i avsnittet Relaterat innehåll i slutet av den här artikeln. Följande diagram innehåller en översikt över medgivande för en flernivåapp som är registrerad i en enda klientorganisation.

Diagram som illustrerar medgivande till kända klientappar på flera nivåer.

Flera nivåer i flera klientorganisationer

Ett liknande fall inträffar om de olika nivåerna för ett program registreras i olika klientorganisationer. Tänk dig till exempel att skapa ett internt klientprogram som anropar Exchange Online-API:et. För att utveckla det inbyggda programmet och senare för att det inbyggda programmet ska köras i en kunds klientorganisation måste Exchange Online tjänstens huvudnamn 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 tredjepartsutvecklare skapar API:et så att det även kan fungera som en webbklient för att implementera registrering. Gör så här:

  1. Följ de tidigare avsnitten för att se till att API:et implementerar programregistrerings-/kodkraven för flera klientorganisationer.
  2. Förutom att exponera API:ets omfång/roller kontrollerar du att registreringen innehåller behörigheten "Logga in och läsa användarprofil" (tillhandahålls som standard).
  3. Implementera en inloggnings-/registreringssida i webbklienten och följ riktlinjerna 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 är registrerad 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:

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 åtkomst och endast för hela programmet.

Program för flera klientorganisationer och cachelagring av åtkomsttoken

Program med flera klientorganisationer kan också hämta åtkomsttoken för att anropa API:er som skyddas av Azure AD. Ett vanligt fel när du använder Microsoft Authentication Library (MSAL) med ett program för 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 Azure AD 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.

Nästa steg

I den här artikeln har du lärt dig hur du konverterar ett program för en enda klientorganisation till ett program för flera klientorganisationer. När du har aktiverat enkel inloggning (SSO) mellan din app och Azure AD uppdaterar du appen för att komma åt API:er som exponeras av Microsoft resurser som Microsoft 365. På så sätt kan du erbjuda en anpassad upplevelse i ditt program, till exempel att visa sammanhangsberoende information för användarna, till exempel profilbilder och avtalade tider i kalendern.

Mer information om hur du gör API-anrop till Azure AD och Microsoft 365-tjänster som Exchange, SharePoint, OneDrive, OneNote med mera finns i Microsoft Graph API.