Handleiding: een Azure Active Directory gastgebruiker uitnodigen met Microsoft Graph

Een van de meest tijdrovende taken waarmee we bij mijn huidige opdracht worden geconfronteerd, is het uitnodigen van gebruikers in onze Azure Active Directory-tenant. Vooral omdat we dit momenteel handmatig doen in de Azure Portal. We gebruiken Azure Active Directory B2B waarin externe gebruikers als gasten worden uitgenodigd. Om dit proces te automatiseren maken we gebruik van Microsoft Graph. Je moet bij het implementeren hiervan rekening houden met verschillende zaken. Hieronder vind je een snelle handleiding.

Overigens snijd ik in dit artikel hier en daar een bochtje af. Bijvoorbeeld bij het maken van Views en Controller-acties voor de web app. Dit is een bewuste keuze omdat ik wil dat deze handleiding zich concentreert op het aanroepen van de Microsoft Graph. En omdat ik ervan uitga dat je weet hoe je een View of Controller-actie kunt maken. 😉

Wat gaan we maken?

We creëren een web app die Application Permissions gebruikt om gebruikers uit te nodigen voor een Azure Active Directory-tenant met behulp van Microsoft Graph. We gebruiken Application Permissions omdat we de functionaliteit voor verschillende typen gebruikers beschikbaar willen maken. Mogelijk hebben niet alle gebruikers van de app beheerdersrechten op de AAD-tenant. Op deze manier heeft de applicatie zelf het recht om gebruikers uit te nodigen, zodat de gebruiker deze rechten niet hoeft te hebben. Om deze handleiding relatief simpel en gericht te houden op de betreffende taak, slaan we het aanmelden bij de web app over.

Azure Active Directory-eindpunten

Er zijn momenteel twee Azure Active Directory-eindpunten: V1 en V2. Het V1-eindpunt kennen we inmiddels al een tijdje. V2 heeft extra functionaliteit, met als grootste verschil:

The v2.0 endpoint allows developers to write apps that accept sign-in from both Microsoft Accounts and Azure AD accounts, using a single auth endpoint. This gives you the ability to write your app completely account-agnostic; it can be ignorant of the type of account that the user signs in with. Of course, you can make your app aware of the type of account being used in a particular session, but you don’t have to.

Bron: What’s different about the v2.0 endpoint?

Daarnaast worden app-registraties voor het V2-eindpunt niet gedaan in de Azure Portal, maar in de afzonderlijke Application Registration Portal. Voor deze handleiding gebruiken we het Azure Active Directory V1-eindpunt en een app-registratie in de Azure Portal.

De handleiding

Dit zijn de stappen die nodig zijn om deze eenvoudige voorbeeldtoepassing te maken.

1. Maak een app-registratie in de Azure Portal

Open Azure Active Directory in de portal
Ga naar App Registrations en klik op New Application Registration
Geef de nieuwe app-registratie een Name, kies Web app/API als applicatietype en geef het een (nep) Sign-on-URL
Klik op Create
Nadat de toepassingsregistratie is gemaakt, klikt u op Settings
Ga naar Required Permissions, klik op Add en vervolgens op Select an API

Handleiding Een Azure Active Directory Gastgebruiker Uitnodigen App Registratie Betabit

Selecteer Microsoft Graph en klik op Select
Onder Application Permissions* vink je Invite guest users to the organization aan
Als extraatje kun je Read all users’ full profiles selecteren, zodat je de gebruikers in de web app kan laten zien
Klik op Select om de rechten te selecteren en vervolgens op Done om het toevoegen van API-toegang te beëindigen.

Handleiding Een Azure Active Directory Gastgebruiker Uitnodigen Grant Permission Betabit

Belangrijk!
Een beheerder moet deze machtigingen verlenen. Klik op de knop Grant Permissions om de rechten voor de toepassing daadwerkelijk te verlenen. Alle wijzigingen die je doorvoert in de ingeschakelde machtigingen, vereisen dat je opnieuw expliciet de machtigingen verleent door op de knop te klikken.

Ga naar Keys
Onder Passwords geef je een Key description in, selecteer een Duration en klik op Save

Let op: kopieer de waarde van de Key nadat je hebt opgeslagen, omdat je deze niet meer kunt ophalen nadat je de Blade hebt gesloten.

*Toepassingsmachtigingen en gedelegeerde machtigingen

Zojuist heb ik expliciet aangegeven de machtigingen voor de applicatie aan te zetten onder Application Permissions. En hier is een goede reden voor. Gebruik Delegated Permissions als je wilt dat de toepassing de API aanroept als de aangemelde gebruiker. Wanneer de toepassing Microsoft Graph als zichzelf aanroept, gebruik je Application Permissions. Aangezien we willen dat iedereen die de app gebruikt de mogelijkheid heeft om gebruikers uit te nodigen, gebruiken we Application Permissions.

2. Maak en implementeer de web app

Maak een ASP.NET-webapplicatie. Ik heb een .NET Core 2.0 web app gemaakt, maar je bent vrij om te bepalen wat jouw voorkeur heeft.

Voeg de Microsoft.Graph NuGet-package toe
Voeg de NuGet-package Active Directory Authentication Library toe (Microsoft.IdentityModel.Clients.ActiveDirectory)
Creëer iets als een InviteUserModel, views en acties voor de controller
Maak een ClientCredential met:
- De id van de toepassing die je in stap 1 hebt gemaakt
- Het wachtwoord voor deze toepassing
Maak een AuthenticationContext voor jouw AAD-tenant (zoiets als https://login.microsoftonline.com/<JOUW_AAD_TENANT>.onmicrosoft.com)
Haal een token op voor Microsoft Graph door AcquireToken aan te roepen op de AuthenticationContext
Maak een DelegateAuthProvider die het resulterende token aan de kop van elk verzoek toevoegt

Alles samen zou het er ongeveer zo uit moeten zien:

var clientCredential = new ClientCredential(_appId, _appSecret);
var authenticationContext = new AuthenticationContext($"https://login.microsoftonline.com/{_tenant}");
var authenticationResult = authenticationContext.AcquireTokenAsync("https://graph.microsoft.com", clientCredential).Result;

var delegateAuthProvider = new DelegateAuthenticationProvider((requestMessage) =>
{
    requestMessage.Headers.Authorization = new AuthenticationHeaderValue("bearer", authenticationResult.AccessToken);
    return Task.FromResult(0);
});

return new GraphServiceClient(delegateAuthProvider);

3. Microsoft Graph gebruiken

Het gemaakte voorbeeld bevat een GraphServiceClientHelper, waardoor het er als volgt uitziet:

var graphServiceClient = GraphServiceClientHelper.CreateGraphServiceClient();
var invitation = await graphServiceClient.Invitations.Request().AddAsync(new Invitation
{
    InviteRedirectUrl = "http://localhost:xxx",
    InvitedUserDisplayName = inviteUserModel.DisplayName,
    InvitedUserEmailAddress = inviteUserModel.EmailAddress,
    InvitedUserMessageInfo = new InvitedUserMessageInfo
    {
        CustomizedMessageBody = inviteUserModel.InviteMessage
    },
    SendInvitationMessage = inviteUserModel.SendInviteMessage
});

Belangrijk!
De InviteRedirectUrl is een vereiste parameter. Het moet de URL bevatten waarnaar de uitgenodigde gebruiker wordt doorgestuurd na het accepteren van de uitnodiging.

Gotcha!

Houd er rekening mee dat er enkele verschillen zijn tussen de API V1.0 Graph en de bètaversie. Een voorbeeld: de bètaversie biedt geen ondersteuning bij het ophalen van meer dan 100 items tegelijkertijd. Aan de andere kant biedt V1.0 geen ondersteuning voor het ‘expanden’ van MemberOf, terwijl de bèta dit wel ondersteunt.

Om de bètaversie aan te roepen, gebruik je de constructor voor GraphServiceClient. Hiervoor zijn twee parameters nodig: baseUrl en authenticationProvider. Je hoeft de URL van de resource waarvoor je een token ophaalt niet te wijzigen, omdat tokens voor Microsoft Graph (https://graph.microsoft.com) zowel voor V1.0 als de bètaversie werken.

Het initialiseren van de GraphServiceClient voor de bètaversie ziet er als volgt uit:

var client = new GraphServiceClient("https://graph.microsoft.com/beta", delegateAuthProvider);

Source code

Dit (extreem eenvoudige) voorbeeld heb ik op GitHub gehost. Je kunt het hier vinden: rickvdbosch/MicrosoftGraphExample. Mocht je problemen ondervinden bij het uitvoeren van deze handleiding: neem gerust contact met me op.

AAD gastgebruiker uitnodigen met Microsoft Graph

Meer weten over Microsoft Graph? Rick helpt je graag verder