Een web-API die web-API's aanroept: codeconfiguratie

In dit artikel wordt beschreven hoe u code configureert voor een web-API-app met behulp van de OAuth 2.0-autorisatiecodestroom.

Microsoft raadt u aan het NuGet-pakket Microsoft.Identity.Web te gebruiken bij het ontwikkelen van een met ASP.NET Core beveiligde API die downstream-web-API's aanroept. Zie Beveiligde web-API: codeconfiguratie | Microsoft.Identity.Web voor een snelle presentatie van die bibliotheek in de context van een web-API.

Vereisten

• Een web-API registreren die web-API's aanroept

De app configureren

Kies een taal voor uw web-API.

ASP.NET Core

Clientgeheimen of clientcertificaten

Aangezien uw web-app nu een downstream-web-API aanroept, geeft u een clientgeheim of clientcertificaat op in het bestand appsettings.json. U kunt ook een sectie toevoegen die het volgende aangeeft:

• De URL van de downstream web-API
• De bereiken die nodig zijn voor het aanroepen van de API

In het volgende voorbeeld geeft de GraphBeta sectie deze instellingen op.

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "ClientId": "[Enter_the_Application_Id_Here]",
    "TenantId": "common",

   // To call an API
   "ClientCredentials": [
    {
      "SourceType": "ClientSecret",
      "ClientSecret":"[Enter_the_Client_Secret_Here]"
    }
  ]
 },
 "GraphBeta": {
    "BaseUrl": "https://graph.microsoft.com/beta",
    "Scopes": ["user.read"]
    }
}

Notitie

U kunt een verzameling clientreferenties voorstellen, waaronder een oplossing zonder referenties, zoals federatie van workloadidentiteit voor Azure Kubernetes. Vorige versies van Microsoft.Identity.Web hebben het clientgeheim uitgedrukt in één eigenschap ClientSecret in plaats van ClientCredentials. Dit wordt nog steeds ondersteund voor compatibiliteit met eerdere versies, maar u kunt niet zowel de eigenschap ClientSecret als de verzameling ClientCredentials gebruiken.

In plaats van een clientgeheim kunt u een clientcertificaat opgeven. Het volgende codefragment toont het gebruik van een certificaat dat is opgeslagen in Azure Key Vault.

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "ClientId": "[Enter_the_Application_Id_Here]",
    "TenantId": "common",

   // To call an API
   "ClientCredentials": [
      {
        "SourceType": "KeyVault",
        "KeyVaultUrl": "https://msidentitywebsamples.vault.azure.net",
        "KeyVaultCertificateName": "MicrosoftIdentitySamplesCert"
      }
   ]
  },
  "GraphBeta": {
    "BaseUrl": "https://graph.microsoft.com/beta",
    "Scopes": ["user.read"]
  }
}

Waarschuwing

Als u vergeet de Scopes in een matrix te wijzigen, wordt wanneer u de IDownstreamApi bereiken probeert te gebruiken null weergegeven en IDownstreamApi wordt geprobeerd een anonieme (niet-geverifieerde) aanroep naar de downstream-API uit te voeren, wat resulteert in een 401/unauthenticated.

Microsoft.Identity.Web biedt verschillende manieren om certificaten te beschrijven, zowel op configuratie als op code. Zie Microsoft.Identity.Web - Certificaten gebruiken op GitHub voor meer informatie.

Program.cs

using Microsoft.Identity.Web;

// ...
builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddMicrosoftIdentityWebApi(Configuration, Configuration.GetSection("AzureAd"))
    .EnableTokenAcquisitionToCallDownstreamApi()
    .AddInMemoryTokenCaches();
// ...

Een web-API moet een token verkrijgen voor de downstream-API. Geef deze op door de .EnableTokenAcquisitionToCallDownstreamApi() regel erna .AddMicrosoftIdentityWebApi(Configuration)toe te voegen. Deze regel bevat de ITokenAcquisition service die kan worden gebruikt in de acties controller/pagina's.

Een alternatieve methode is echter het implementeren van een tokencache. Als u bijvoorbeeld aan Program.cs kunt toevoegen.AddInMemoryTokenCaches(), kan het token in de cache worden opgeslagen in het geheugen.

using Microsoft.Identity.Web;

// ...
builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddMicrosoftIdentityWebApi(Configuration, Configuration.GetSection("AzureAd"))
    .EnableTokenAcquisitionToCallDownstreamApi()
    .AddInMemoryTokenCaches();
// ...

Microsoft.Identity.Web biedt twee mechanismen voor het aanroepen van een downstream-web-API vanuit een andere API. De optie die u kiest, is afhankelijk van of u Microsoft Graph of een andere API wilt aanroepen.

Optie 1: Microsoft Graph aanroepen

Als u Microsoft Graph wilt aanroepen, kunt u met Microsoft.Identity.Web de GraphServiceClient API-acties rechtstreeks gebruiken (beschikbaar gesteld door de Microsoft Graph SDK).

Notitie

Er is een doorlopend probleem met Microsoft Graph SDK v5+. Raadpleeg het GitHub-probleem voor meer informatie.

Microsoft Graph beschikbaar maken:

1. Voeg het NuGet-pakket Microsoft.Identity.Web.GraphServiceClient toe aan het project.
2. Voeg .AddMicrosoftGraph() na .EnableTokenAcquisitionToCallDownstreamApi() in Program.cs toe. .AddMicrosoftGraph() heeft verschillende onderdrukkingen. Als u de onderdrukking gebruikt die een configuratiesectie als parameter gebruikt, wordt de code:

using Microsoft.Identity.Web;

// ...
builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddMicrosoftIdentityWebApi(Configuration, Configuration.GetSection("AzureAd"))
    .EnableTokenAcquisitionToCallDownstreamApi()
    .AddMicrosoftGraph(Configuration.GetSection("GraphBeta"))
    .AddInMemoryTokenCaches();
// ...

Optie 2: een andere downstream web-API aanroepen dan Microsoft Graph

1. Voeg het NuGet-pakket Microsoft.Identity.Web.DownstreamApi toe aan het project.
2. Voeg .AddDownstreamApi() na .EnableTokenAcquisitionToCallDownstreamApi() in Program.cs toe. De code wordt:

using Microsoft.Identity.Web;

// ...
builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddMicrosoftIdentityWebApi(Configuration, "AzureAd")
    .EnableTokenAcquisitionToCallDownstreamApi()
    .AddDownstreamApi("MyApi", Configuration.GetSection("MyApiScope"))
    .AddInMemoryTokenCaches();
// ...

waar;

• MyApi geeft de naam aan van de downstream-web-API die uw web-API wil aanroepen
• MyApiScope is het bereik dat nodig is om uw web-API aan te vragen om te communiceren met de downstream-web-API

Deze waarden worden weergegeven in uw JSON die vergelijkbaar is met het volgende codefragment.

"DownstreamAPI": {
      "BaseUrl": "https://downstreamapi.contoso.com/",
      "Scopes": "user.read"
    },

Als de web-app een andere API-resource moet aanroepen, herhaalt u de .AddDownstreamApi() methode met het relevante bereik, zoals wordt weergegeven in het volgende fragment:

using Microsoft.Identity.Web;

// ...
builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddMicrosoftIdentityWebApi(Configuration, "AzureAd")
    .EnableTokenAcquisitionToCallDownstreamApi()
    .AddDownstreamApi("MyApi", Configuration.GetSection("MyApiScope"))
    .AddDownstreamApi("MyApi2", Configuration.GetSection("MyApi2Scope"))
    .AddInMemoryTokenCaches();
// ...

Houd er rekening mee dat zonder .EnableTokenAcquisitionToCallDownstreamApi parameter wordt aangeroepen, wat betekent dat het toegangstoken net op tijd wordt verkregen wanneer de controller het token aanvraagt door het bereik op te geven.

Het bereik kan ook worden doorgegeven tijdens het aanroepen .EnableTokenAcquisitionToCallDownstreamApi, waardoor de web-app het token verkrijgt tijdens de initiële aanmelding van de gebruiker zelf. Het token wordt vervolgens opgehaald uit de cache wanneer de controller dit aanvraagt.

Net als bij web-apps kunnen verschillende tokencache-implementaties worden gekozen. Zie Microsoft.Identity.Web - Serialisatie van tokencache op GitHub voor meer informatie.

In de volgende afbeelding ziet u de mogelijkheden van Microsoft.Identity.Web en de impact op Program.cs:

Notitie

Om de codevoorbeelden hier volledig te begrijpen, moet u vertrouwd zijn met ASP.NET Core basisprincipes en met name met afhankelijkheidsinjectie en opties.

ASP.NET

Clientgeheimen of clientcertificaten

Aangezien uw web-app nu een downstream-web-API aanroept, geeft u een clientgeheim of clientcertificaat op in het bestand appsettings.json. U kunt ook een sectie toevoegen die het volgende aangeeft:

• De URL van de downstream web-API
• De bereiken die nodig zijn voor het aanroepen van de API

In het volgende voorbeeld geeft de GraphBeta sectie deze instellingen op.

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "ClientId": "[Enter_the_Application_Id_Here]",
    "TenantId": "common",

   // To call an API
   "ClientCredentials": [
    {
      "SourceType": "ClientSecret",
      "ClientSecret":"[Enter_the_Client_Secret_Here]"
    }
  ]
 },
 "GraphBeta": {
    "BaseUrl": "https://graph.microsoft.com/beta",
    "Scopes": ["user.read"]
    }
}

Notitie

U kunt een verzameling clientreferenties voorstellen, waaronder een oplossing zonder referenties, zoals federatie van workloadidentiteit voor Azure Kubernetes. Vorige versies van Microsoft.Identity.Web hebben het clientgeheim uitgedrukt in één eigenschap ClientSecret in plaats van ClientCredentials. Dit wordt nog steeds ondersteund voor compatibiliteit met eerdere versies, maar u kunt niet zowel de eigenschap ClientSecret als de verzameling ClientCredentials gebruiken.

In plaats van een clientgeheim kunt u een clientcertificaat opgeven. Het volgende codefragment toont het gebruik van een certificaat dat is opgeslagen in Azure Key Vault.

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "ClientId": "[Enter_the_Application_Id_Here]",
    "TenantId": "common",

   // To call an API
   "ClientCredentials": [
      {
        "SourceType": "KeyVault",
        "KeyVaultUrl": "https://msidentitywebsamples.vault.azure.net",
        "KeyVaultCertificateName": "MicrosoftIdentitySamplesCert"
      }
   ]
  },
  "GraphBeta": {
    "BaseUrl": "https://graph.microsoft.com/beta",
    "Scopes": ["user.read"]
  }
}

Waarschuwing

Als u vergeet de Scopes in een matrix te wijzigen, wordt wanneer u de IDownstreamApi bereiken probeert te gebruiken null weergegeven en IDownstreamApi wordt geprobeerd een anonieme (niet-geverifieerde) aanroep naar de downstream-API uit te voeren, wat resulteert in een 401/unauthenticated.

Microsoft.Identity.Web biedt verschillende manieren om certificaten te beschrijven, zowel op configuratie als op code. Zie Microsoft.Identity.Web - Certificaten gebruiken op GitHub voor meer informatie.

Startup.Auth.cs wijzigen

Uw web-app moet een token verkrijgen voor de downstream-API. Microsoft.Identity.Web biedt twee mechanismen voor het aanroepen van een downstream-API vanuit een web-API. De optie die u kiest, is afhankelijk van of u Microsoft Graph of een andere API wilt aanroepen.

Optie 1: Microsoft Graph aanroepen

Als u Microsoft Graph wilt aanroepen, kunt u met Microsoft.Identity.Web de GraphServiceClient gebruiken (beschikbaar gesteld door de Microsoft Graph SDK) in uw API-acties. Microsoft Graph beschikbaar maken:

1. Voeg het NuGet-pakket Microsoft.Identity.Web.GraphServiceClient toe aan uw project.

2. Voeg toe .AddMicrosoftGraph() aan de serviceverzameling in het Startup.Auth.cs-bestand . .AddMicrosoftGraph() heeft verschillende onderdrukkingen. Als u de onderdrukking gebruikt die een configuratiesectie als parameter gebruikt, wordt de code:

   using Microsoft.Extensions.DependencyInjection;
   using Microsoft.Identity.Client;
   using Microsoft.Identity.Web;
   using Microsoft.Identity.Web.OWIN;
   using Microsoft.Identity.Web.TokenCacheProviders.InMemory;
   using Microsoft.IdentityModel.Validators;
   using Microsoft.Owin.Security;
   using Microsoft.Owin.Security.Cookies;
   using Owin;
   
   namespace WebApp
   {
      public partial class Startup
      {
          public void ConfigureAuth(IAppBuilder app)
          {
              app.SetDefaultSignInAsAuthenticationType(CookieAuthenticationDefaults.AuthenticationType);
   
              app.UseCookieAuthentication(new CookieAuthenticationOptions());
   
              // Get an TokenAcquirerFactory specialized for OWIN
              OwinTokenAcquirerFactory owinTokenAcquirerFactory = TokenAcquirerFactory.GetDefaultInstance<OwinTokenAcquirerFactory>();
   
              // Configure the web app.
              app.AddMicrosoftIdentityWebApi(owinTokenAcquirerFactory);
   
              // Add the services you need.
              owinTokenAcquirerFactory.Services
                  .AddMicrosoftGraph()
                  .AddInMemoryTokenCaches();
              owinTokenAcquirerFactory.Build();
          }
      }
   }
   

Optie 2: een andere downstream web-API aanroepen dan Microsoft Graph

Als u een andere API wilt aanroepen dan Microsoft Graph, kunt u met Microsoft.Identity.Web de IDownstreamApi interface in uw API-acties gebruiken. Ga als volgt te werk om deze interface te gebruiken:

1. Voeg het NuGet-pakket Microsoft.Identity.Web.DownstreamApi toe aan uw project.
2. Voeg .AddDownstreamApi() na .EnableTokenAcquisitionToCallDownstreamApi() toe aan het bestand Startup.cs. .AddDownstreamApi() heeft twee argumenten:
   • De naam van een service (API): u gebruikt deze naam in de controlleracties om te verwijzen naar de bijbehorende configuratie
   • een configuratiesectie die de parameters vertegenwoordigt die worden gebruikt om de downstream-web-API aan te roepen.

Hier volgt de code:

  using Microsoft.Extensions.DependencyInjection;
  using Microsoft.Identity.Client;
  using Microsoft.Identity.Web;
  using Microsoft.Identity.Web.OWIN;
  using Microsoft.Identity.Web.TokenCacheProviders.InMemory;
  using Microsoft.IdentityModel.Validators;
  using Microsoft.Owin.Security;
  using Microsoft.Owin.Security.Cookies;
  using Owin;

  namespace WebApp
  {
      public partial class Startup
      {
          public void ConfigureAuth(IAppBuilder app)
          {
              app.SetDefaultSignInAsAuthenticationType(CookieAuthenticationDefaults.AuthenticationType);

              app.UseCookieAuthentication(new CookieAuthenticationOptions());

              // Get a TokenAcquirerFactory specialized for OWIN.
              OwinTokenAcquirerFactory owinTokenAcquirerFactory = TokenAcquirerFactory.GetDefaultInstance<OwinTokenAcquirerFactory>();

              // Configure the web app.
              app.AddMicrosoftIdentityWebApi(owinTokenAcquirerFactory);

              // Add the services you need.
              owinTokenAcquirerFactory.Services
                  .AddDownstreamApi("Graph", owinTokenAcquirerFactory.Configuration.GetSection("GraphBeta"))
                  .AddInMemoryTokenCaches();
              owinTokenAcquirerFactory.Build();
          }
      }
  }

Java

On-behalf-of -stroom (OBO) gebruiken

De stroom namens (OBO) wordt gebruikt om een token te verkrijgen om de downstream-web-API aan te roepen. In deze stroom ontvangt uw web-API een bearer-token met door de gebruiker gedelegeerde machtigingen van de clienttoepassing en wordt dit token vervolgens uitgewisseld voor een ander toegangstoken om de downstream web-API aan te roepen.

De onderstaande code maakt gebruik van SecurityContextHolder van het Spring Security Framework in de web-API om het gevalideerde bearer-token op te halen. Vervolgens wordt de MSAL Java-bibliotheek gebruikt om een token voor downstream API te verkrijgen met behulp van de acquireToken-aanroep met OnBehalfOfParameters. MSAL slaat het token in de cache op, zodat volgende aanroepen naar de API acquireTokenSilently kunnen gebruiken om het token in de cache op te halen.

@Component
class MsalAuthHelper {

    @Value("${security.oauth2.client.authority}")
    private String authority;

    @Value("${security.oauth2.client.client-id}")
    private String clientId;

    @Value("${security.oauth2.client.client-secret}")
    private String secret;

    @Autowired
    CacheManager cacheManager;

    private String getAuthToken(){
        String res = null;
        Authentication authentication = SecurityContextHolder.getContext().getAuthentication();

        if(authentication != null){
            res = ((OAuth2AuthenticationDetails) authentication.getDetails()).getTokenValue();
        }
        return res;
    }

    String getOboToken(String scope) throws MalformedURLException {
        String authToken = getAuthToken();

        ConfidentialClientApplication application =
                ConfidentialClientApplication.builder(clientId, ClientCredentialFactory.create(secret))
                        .authority(authority).build();

        String cacheKey = Hashing.sha256()
                .hashString(authToken, StandardCharsets.UTF_8).toString();

        String cachedTokens = cacheManager.getCache("tokens").get(cacheKey, String.class);
        if(cachedTokens != null){
            application.tokenCache().deserialize(cachedTokens);
        }

        IAuthenticationResult auth;
        SilentParameters silentParameters =
                SilentParameters.builder(Collections.singleton(scope))
                        .build();
        auth = application.acquireTokenSilently(silentParameters).join();

        if (auth == null){
            OnBehalfOfParameters parameters =
                    OnBehalfOfParameters.builder(Collections.singleton(scope),
                            new UserAssertion(authToken))
                            .build();

            auth = application.acquireToken(parameters).join();
        }

        cacheManager.getCache("tokens").put(cacheKey, application.tokenCache().serialize());

        return auth.accessToken();
    }
}

Python

On-behalf-of -stroom (OBO) gebruiken

De stroom namens (OBO) wordt gebruikt om een token te verkrijgen om de downstream-web-API aan te roepen. In deze stroom ontvangt uw web-API een bearer-token met door de gebruiker gedelegeerde machtigingen van de clienttoepassing en wordt dit token vervolgens uitgewisseld voor een ander toegangstoken om de downstream web-API aan te roepen.

Een Python-web-API moet een aantal middleware gebruiken om het bearer-token te valideren dat van de client is ontvangen. De web-API kan vervolgens het toegangstoken voor downstream-API verkrijgen met behulp van de MSAL Python-bibliotheek door de acquire_token_on_behalf_of-methode aan te roepen. Zie de testcode voor de microsoft-authentication-library-for-python op GitHub voor een voorbeeld van het gebruik van deze API. Zie ook de bespreking van probleem 53 in dezelfde opslagplaats voor een benadering die de noodzaak voor een toepassing in de middelste laag omzeilt.

U kunt ook een voorbeeld zien van de implementatie van de OBO-stroom in het voorbeeld ms-identity-python-on-behalf-of.

U kunt ook een voorbeeld zien van de implementatie van een OBO-stroom in Node.js en Azure Functions.

Protocol

Zie het Microsoft-identiteitsplatform en de Namens-stroom voor OAuth 2.0 voor meer informatie over het OBO-protocol.

Volgende stap

Een token voor de app verkrijgen.