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

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 vereiste scopes 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"]
    }
}

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"]
  }
}

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 na .AddMicrosoftIdentityWebApi(Configuration) toe te voegen. Deze regel maakt de ITokenAcquisition service beschikbaar die kan worden gebruikt in de acties van controllers/pagina's.

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

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).

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 overschrijvingen. Als u de overschrijving gebruikt die een configuratiesectie als parameter neemt, 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 uw web-API moet aanvragen 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 .EnableTokenAcquisitionToCallDownstreamApi zonder enige parameter wordt aangeroepen, wat betekent dat het toegangstoken precies op tijd wordt verkregen wanneer de controller het token aanvraagt door de reikwijdte te specificeren.

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:

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 vereiste scopes 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"]
    }
}

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"]
  }
}

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 benaderen, kunt u met Microsoft.Identity.Web direct de GraphServiceClient gebruiken, beschikbaar via 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 .AddMicrosoftGraph() toe aan de servicecollectie in het bestand Startup.Auth.cs. .AddMicrosoftGraph() heeft verschillende overschrijvingen. Als u de overschrijving gebruikt die een configuratiesectie als parameter neemt, 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();
          }
      }
  }

Stroom voor on-behalf-of (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();
    }
}

Stroom voor on-behalf-of (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-voorbeeldflow in ms-identity-python-on-behalf-of.