Gebruikers aanmelden en een API aanroepen in een Android-voorbeeld-app met behulp van systeemeigen verificatie

Van toepassing op: Externe tenants (meer informatie)

In deze quickstart leert u hoe u een voorbeeld van een mobiele Android-toepassing configureert om een ASP.NET Core-web-API aan te roepen.

Voorwaarden

• Gebruikers inloggen in een voorbeeld mobiele Android-app (Kotlin) door gebruik te maken van systeemeigen authenticatie.
• Registreer in het Microsoft Entra-beheercentrum een nieuwe toepassing voor uw web-API met de volgende configuratie. Zie Een toepassing registreren voor gedetailleerde stappen. Noteer de id van de toepassing (client) en de id van de map (tenant) voor later gebruik.
  • Naam: ciam-ToDoList-api.
  • Ondersteunde accounttypen: accounts in deze organisatiemap (alleen één tenant)

API-bereiken configureren

Een API moet minimaal één bereik publiceren, ook wel gedelegeerde machtiginggenoemd, zodat de client-apps een toegangstoken voor een gebruiker kunnen verkrijgen. Voer de volgende stappen uit om een scope te publiceren:

1. Selecteer op de pagina App-registraties de API-toepassing die u hebt gemaakt (ciam-ToDoList-api) om de bijbehorende pagina Overzicht te openen.

2. Selecteer onder Beherende optie Een API beschikbaar maken.

3. Selecteer bovenaan de pagina, naast URI voor de toepassings-id, de koppeling Toevoegen om een unieke URI voor deze app te genereren.

4. Accepteer de voorgestelde URI voor de toepassings-id, zoals api://{clientId}, en selecteer Opslaan. Wanneer uw webtoepassing een toegangstoken voor de web-API aanvraagt, wordt de URI toegevoegd als het voorvoegsel voor elk bereik dat u voor de API definieert.

5. Selecteer onder bereiken die zijn gedefinieerd door deze APIde optie Een bereik toevoegen.

6. Voer de volgende waarden in waarmee een leestoegang tot de API wordt gedefinieerd en selecteer vervolgens Bereik toevoegen om uw wijzigingen op te slaan:

   Eigendom	Waarde
   Scopenaam	ToDoList.Lezen
   Wie kan toestemming geven	Alleen beheerders
   Weergavenaam van beheerderstoestemming	De todo-lijst van gebruikers lezen met de TodoListApi
   Beschrijving van beheerderstoestemming	Sta de app toe om de takenlijst van de gebruiker te lezen met behulp van de TodoListApi.
   Staat	Ingeschakeld

7. Selecteer Voeg opnieuw een bereik toe en voer de volgende waarden in waarmee een bereik voor lees- en schrijftoegang tot de API wordt gedefinieerd. Selecteer Voeg bereik toe om uw wijzigingen op te slaan.

   Eigendom	Waarde
   Scopenaam	ToDoList.ReadWrite
   Wie kan toestemming geven	Alleen beheerders
   Weergavenaam van beheerderstoestemming	Lees en schrijf de ToDo-lijst van gebruikers met behulp van de 'ToDoListApi'
   Beschrijving van beheerderstoestemming	Toestaan dat de app de Takenlijst van de gebruiker kan lezen en schrijven met behulp van de toDoListApi-
   Staat	Ingeschakeld

Meer informatie over het principe van minimale bevoegdheden bij het publiceren van machtigingen voor een web-API.

App-rollen configureren

Een API moet minimaal één app-rol publiceren voor toepassingen, ook wel toepassingsmachtiginggenoemd, zodat de client-apps zelf een toegangstoken kunnen verkrijgen. Toepassingsmachtigingen zijn het type machtigingen dat API's moeten publiceren wanneer ze clienttoepassingen in staat willen stellen zich als zichzelf te verifiëren en geen gebruikers hoeven aan te melden. Voer de volgende stappen uit om een toepassingsmachtiging te publiceren:

1. Selecteer op de pagina App-registraties de toepassing die u hebt gemaakt (zoals ciam-ToDoList-api) om de pagina Overzicht te openen.

2. Onder Beheerselecteer App rollen.

3. Selecteer app-rol makenen voer vervolgens de volgende waarden in en selecteer vervolgens Toepassen om uw wijzigingen op te slaan:

   Eigendom	Waarde
   Weergavenaam	ToDoLijst.Lezen.Alles
   Toegestane ledensoorten	toepassingen
   Waarde	ToDoLijst.Lezen.Alles
   Beschrijving	Toestaan dat de app de takenlijst van elke gebruiker kan lezen met behulp van de TodoListApi
   Wilt u deze app-rol inschakelen?	Houd deze ingeschakeld

4. Selecteer App-rol maken opnieuw en voer vervolgens de volgende waarden in voor de tweede app-rol en selecteer vervolgens Toepassen om uw wijzigingen op te slaan:

   Eigendom	Waarde
   Weergavenaam	ToDoList.ReadWrite.All
   Toegestane ledensoorten	toepassingen
   Waarde	ToDoList.ReadWrite.All
   Beschrijving	toestaan dat de app de Takenlijst van elke gebruiker kan lezen en schrijven met behulp van de toDoListApi-
   Wilt u deze app-rol inschakelen?	Houd deze ingeschakeld

Optionele claims configureren

U kunt de idtyp optionele claim toevoegen om de web-API te helpen bepalen of een token een -app is token of een -app + gebruiker token. Hoewel u een combinatie van scp-- en -rollen kunt gebruiken om-claims voor hetzelfde doel in te zetten, is het gebruik van de idtyp-claim de eenvoudigste manier om een app-token en een app- en gebruikerstoken te onderscheiden. De waarde van deze claim is bijvoorbeeld app wanneer het token een alleen-app-token is.

API-machtigingen verlenen aan de Android-voorbeeld-app

Zodra u zowel uw client-app als web-API hebt geregistreerd en u de API beschikbaar hebt gemaakt door bereiken te maken, kunt u de machtigingen van de client voor de API configureren door de volgende stappen uit te voeren:

1. Selecteer op de pagina App-registraties de toepassing die u hebt gemaakt (zoals ciam-client-app) om de pagina Overzicht te openen.

2. Selecteer onder Beherende API-machtigingen.

3. Selecteer onder Geconfigureerde machtigingenEen machtiging toevoegen.

4. Selecteer de API's die mijn organisatie gebruikt tabblad.

5. Selecteer in de lijst met API's de API, zoals ciam-ToDoList-api.

6. Selecteer de optie Gedelegeerde machtigingen.

7. Selecteer in de lijst met machtigingen ToDoList.Read, ToDoList.ReadWrite (gebruik indien nodig het zoekvak).

8. Selecteer de knop Machtigingen toevoegen.

9. Op dit moment hebt u de machtigingen correct toegewezen. Omdat de tenant echter de tenant van een klant is, kunnen de consumentengebruikers zelf geen toestemming geven voor deze machtigingen. Om dit te verhelpen, moet u als beheerder toestemming geven voor deze machtigingen namens alle gebruikers in de tenant:

   1. Selecteer Beheerderstoestemming verlenen voor <uw tenantnaam>, en selecteer vervolgens Ja.

   2. Selecteer Vernieuwen, controleer vervolgens of Verleend voor <uw tenantnaam> wordt weergegeven onder Status voor allebei de machtigingen.

10. Selecteer in de lijst Geconfigureerde machtigingen de ToDoList.Read- en ToDoList.ReadWrite machtigingen, één voor één en kopieer de volledige URI van de machtiging voor later gebruik. De volledige machtigings-URI ziet er ongeveer uit als api://{clientId}/{ToDoList.Read} of api://{clientId}/{ToDoList.ReadWrite}.

Voorbeeldweb-API klonen of downloaden

Als u de voorbeeldtoepassing wilt verkrijgen, kunt u deze klonen vanuit GitHub of downloaden als een .zip-bestand.

• Als u het voorbeeld wilt klonen, opent u een opdrachtprompt en navigeert u naar de locatie waar u het project wilt maken en voert u de volgende opdracht in:

  git clone https://github.com/Azure-Samples/ms-identity-ciam-dotnet-tutorial.git
  

• download het .zip bestand. Pak het uit naar een bestandspad waarbij de lengte van de naam minder dan 260 tekens is.

Voorbeeldweb-API configureren en uitvoeren

1. Open 2-Authorization/1-call-own-api-aspnet-core-mvc/ToDoListAPI/appsettings.json bestand in de code-editor.

2. Zoek de tijdelijke aanduiding:

   • Enter_the_Application_Id_Here en vervang deze door de Application (client) ID van de web API die u eerder hebt gekopieerd.
   • Enter_the_Tenant_Id_Here en vervang dat door de Directory-id (tenant) die u eerder hebt gekopieerd.
   • Enter_the_Tenant_Subdomain_Here en vervang dit door het subdomein Directory (tenant). Als uw primaire tenantdomein bijvoorbeeld is contoso.onmicrosoft.com, gebruikt u contoso. Als u uw tenantnaam niet hebt, leert u hoe u uw tenantgegevens kunt lezen.

U moet uw web-API hosten voor de Android-voorbeeld-app om deze aan te roepen. Volg quickstart: Een ASP.NET-web-app implementeren om uw web-API te implementeren.

Voorbeeld van mobiele Android-app configureren om web-API aan te roepen

Met het voorbeeld kunt u meerdere eindpunten voor web-API-URL's en reeksen van scopes configureren. In dit geval configureert u slechts één web-API-URL-eindpunt en de bijbehorende scopes.

1. Open /app/src/main/java/com/azuresamples/msalnativeauthandroidkotlinsampleapp/AccessApiFragment.kt bestand in uw Android Studio.

2. Zoek de eigenschap met de naam WEB_API_URL_1 en stel de URL in op uw web-API.

   private const val WEB_API_URL_1 = "" // Developers should set the respective URL of their web API here
   

3. Zoek de eigenschap met de naam scopesForAPI1 en stel de bereiken in die zijn vastgelegd in om API-machtigingen te verlenen aan de Android-voorbeeld-app.

   private val scopesForAPI1 = listOf<String>() // Developers should set the respective scopes of their web API here. For example, private val scopes = listOf<String>("api://{clientId}/{ToDoList.Read}", "api://{clientId}/{ToDoList.ReadWrite}")
   

Voorbeeld-app voor Android uitvoeren en web-API aanroepen

Voer de volgende stappen uit om uw app te bouwen en uit te voeren:

1. Selecteer uw app in het menu Configuraties uitvoeren in de werkbalk.

2. Selecteer in het menu van het doelapparaat het apparaat waarop u de app wilt uitvoeren.

   Als u geen apparaten hebt geconfigureerd, moet u een virtueel Android-apparaat maken om de Android Emulator te gebruiken of een fysiek apparaat te verbinden.

3. Selecteer de knop Uitvoeren. De app wordt geopend op het e-mail- en eenmalige toegangscodescherm.

4. Selecteer het tabblad API om de API-aanroep te testen. Een geslaagde aanroep van de web-API retourneert HTTP-200, terwijl HTTP-403 onbevoegde toegang aantekent.

Volgende stappen