Webes API-kat hív meg: Kódkonfiguráció

A webes API-regisztráció befejezése után az alkalmazáskód konfigurálható. Ha webes API-t konfigurál egy alsóbb rétegbeli webes API meghívására, az a webes API védelméhez használt kódra épül. További információ: Védett webes API: Alkalmazáskonfiguráció.

Microsoft.Identity.Web

A Microsoft azt javasolja, hogy használja a Microsoft.Identity.Web NuGet-csomagot egy ASP.NET Core által védett API fejlesztésekor, amely alsóbb rétegbeli webes API-kat hív meg. Lásd: Védett webes API: Kódkonfiguráció | A Microsoft.Identity.Web segítségével gyorsan bemutatható a kódtár egy webes API kontextusában.

ASP.NET Core

Titkos ügyfélkódok vagy ügyféltanúsítványok

Mivel a webalkalmazás most egy alsóbb rétegbeli webes API-t hív meg, adjon meg egy titkos ügyfélkulcsot vagy ügyféltanúsítványt a appsettings.json fájlban. Hozzáadhat egy szakaszt is, amely a következőket adja meg:

• Az alsóbb rétegbeli webes API URL-címe
• Az API meghívásához szükséges hatókörök

A következő példában a szakasz ezeket a GraphBeta beállításokat adja meg.

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

Feljegyzés

Javasolhat ügyfél-hitelesítő adatok gyűjteményét, beleértve egy hitelesítő adatok nélküli megoldást, például a számítási feladatok identitásának összevonását az Azure Kuberneteshez. A Microsoft.Identity.Web korábbi verziói egyetlen "ClientSecret" tulajdonságban fejezték ki az ügyfélkulcsot az "Ügyfél hitelesítő adatai" helyett. Ez továbbra is támogatott a visszamenőleges kompatibilitás érdekében, de nem használhatja a "ClientSecret" tulajdonságot és az "Ügyfél hitelesítő adatai" gyűjteményt.

Ügyfélkód helyett ügyféltanúsítványt is megadhat. Az alábbi kódrészlet az Azure Key Vaultban tárolt tanúsítvány használatát mutatja be.

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

Figyelmeztetés

Ha elfelejt tömbre váltani Scopes , a hatókörök használatakor IDownstreamApi null érték jelenik meg, és IDownstreamApi névtelen (nem hitelesített) hívást kísérel meg az alsóbb rétegbeli API-hoz, ami egy 401/unauthenticated.

A Microsoft.Identity.Web számos módszert kínál a tanúsítványok leírására konfiguráció vagy kód alapján egyaránt. További információ: Microsoft.Identity.Web – Tanúsítványok használata a GitHubon.

Program.cs

using Microsoft.Identity.Web;

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

A webes API-nak jogkivonatot kell beszereznie az alsóbb rétegbeli API-hoz. Adja meg a következő sor .AddMicrosoftIdentityWebApi(Configuration)hozzáadásával.EnableTokenAcquisitionToCallDownstreamApi(): . Ez a sor elérhetővé teszi a ITokenAcquisition vezérlő/oldalak műveleteiben használható szolgáltatást.

Egy másik módszer azonban a tokengyorsítótár implementálása. Például a Program.cs hozzáadása .AddInMemoryTokenCaches()lehetővé teszi, hogy a jogkivonat gyorsítótárazva legyen a memóriában.

using Microsoft.Identity.Web;

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

A Microsoft.Identity.Web két mechanizmust biztosít egy lefelé irányuló webes API meghívására egy másik API-ból. A választott lehetőség attól függ, hogy meghívja-e a Microsoft Graphot vagy egy másik API-t.

1. lehetőség: A Microsoft Graph meghívása

A Microsoft Graph meghívásához a Microsoft.Identity.Web lehetővé teszi a GraphServiceClient (Microsoft Graph SDK által közzétett) közvetlen használatát az API-műveletekben.

Feljegyzés

A Microsoft Graph SDK v5+-jával kapcsolatos probléma jelenleg is fennáll. További információ: GitHub-probléma.

A Microsoft Graph felfedéséhez:

1. Adja hozzá a Microsoft.Identity.Web.GraphServiceClient NuGet-csomagot a projekthez.
2. Add .AddMicrosoftGraph() after .EnableTokenAcquisitionToCallDownstreamApi() in Program.cs. .AddMicrosoftGraph() több felülbírálást is kapott. A konfigurációs szakaszt paraméterként használó felülbírálás használatával a kód a következő lesz:

using Microsoft.Identity.Web;

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

2. lehetőség: A Microsoft Graphtól eltérő alsóbb rétegbeli webes API meghívása

1. Adja hozzá a Microsoft.Identity.Web.DownstreamApi NuGet-csomagot a projekthez.
2. Add .AddDownstreamApi() after .EnableTokenAcquisitionToCallDownstreamApi() in Program.cs. A kód a következő lesz:

using Microsoft.Identity.Web;

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

Ahol;

• MyApi a webes API által meghívni kívánt alsóbb rétegbeli webes API nevét jelöli
• MyApiScope a webes API kéréséhez szükséges hatókör az alsóbb rétegbeli webes API-val való interakcióhoz

Ezek az értékek az alábbi kódrészlethez hasonló JSON-fájlban jelennek meg.

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

Ha a webalkalmazásnak másik API-erőforrást kell meghívnia, ismételje meg a .AddDownstreamApi() metódust a megfelelő hatókörrel, ahogyan az alábbi kódrészletben látható:

using Microsoft.Identity.Web;

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

Vegye figyelembe, hogy .EnableTokenAcquisitionToCallDownstreamApi a meghívás paraméter nélkül történik, ami azt jelenti, hogy a hozzáférési jogkivonat éppen időben lesz beolvasva, amikor a vezérlő a hatókör megadásával kéri a jogkivonatot.

A hatókör híváskor .EnableTokenAcquisitionToCallDownstreamApiis átadható, így a webalkalmazás a kezdeti felhasználói bejelentkezés során szerezné be a jogkivonatot. Ezt követően a rendszer lekéri a jogkivonatot a gyorsítótárból, amikor a vezérlő kéri.

A webalkalmazásokhoz hasonlóan különböző tokengyorsítótár-implementációk is választhatók. További információ: Microsoft Identity Web – Token Cache szerializálása a GitHubon.

Az alábbi képen a Microsoft.Identity.Web lehetőségei és a Program.cs gyakorolt hatás látható:

Feljegyzés

Az itt található kód példák teljes megértéséhez ismernie kell ASP.NET alapvető alapismereteket, és különösen a függőséginjektálást és a lehetőségeket.

ASP.NET

Titkos ügyfélkódok vagy ügyféltanúsítványok

Mivel a webalkalmazás most egy alsóbb rétegbeli webes API-t hív meg, adjon meg egy titkos ügyfélkulcsot vagy ügyféltanúsítványt a appsettings.json fájlban. Hozzáadhat egy szakaszt is, amely a következőket adja meg:

• Az alsóbb rétegbeli webes API URL-címe
• Az API meghívásához szükséges hatókörök

A következő példában a szakasz ezeket a GraphBeta beállításokat adja meg.

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

Feljegyzés

Javasolhat ügyfél-hitelesítő adatok gyűjteményét, beleértve egy hitelesítő adatok nélküli megoldást, például a számítási feladatok identitásának összevonását az Azure Kuberneteshez. A Microsoft.Identity.Web korábbi verziói egyetlen "ClientSecret" tulajdonságban fejezték ki az ügyfélkulcsot az "Ügyfél hitelesítő adatai" helyett. Ez továbbra is támogatott a visszamenőleges kompatibilitás érdekében, de nem használhatja a "ClientSecret" tulajdonságot és az "Ügyfél hitelesítő adatai" gyűjteményt.

Ügyfélkód helyett ügyféltanúsítványt is megadhat. Az alábbi kódrészlet az Azure Key Vaultban tárolt tanúsítvány használatát mutatja be.

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

Figyelmeztetés

Ha elfelejt tömbre váltani Scopes , a hatókörök használatakor IDownstreamApi null érték jelenik meg, és IDownstreamApi névtelen (nem hitelesített) hívást kísérel meg az alsóbb rétegbeli API-hoz, ami egy 401/unauthenticated.

A Microsoft.Identity.Web számos módszert kínál a tanúsítványok leírására konfiguráció vagy kód alapján egyaránt. További információ: Microsoft.Identity.Web – Tanúsítványok használata a GitHubon.

Startup.Auth.cs módosítása

A webalkalmazásnak jogkivonatot kell beszereznie az alsóbb rétegbeli API-hoz, a Microsoft.Identity.Web két mechanizmust biztosít egy alsóbb rétegbeli API webes API-ból való meghívásához. A választott lehetőség attól függ, hogy meghívja-e a Microsoft Graphot vagy egy másik API-t.

1. lehetőség: A Microsoft Graph meghívása

Ha meg szeretné hívni a Microsoft Graphot, a Microsoft.Identity.Web lehetővé teszi a GraphServiceClient (Microsoft Graph SDK által közzétett) közvetlen használatát az API-műveletekben. A Microsoft Graph felfedéséhez:

1. Adja hozzá a Microsoft.Identity.Web.GraphServiceClient NuGet-csomagot a projekthez.

2. Adja hozzá .AddMicrosoftGraph() a szolgáltatásgyűjteményhez a Startup.Auth.cs fájlban. .AddMicrosoftGraph() több felülbírálást is kapott. A konfigurációs szakaszt paraméterként használó felülbírálás használatával a kód a következő lesz:

   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();
          }
      }
   }
   

2. lehetőség: A Microsoft Graphtól eltérő alsóbb rétegbeli webes API meghívása

Ha a Microsoft Graphtól eltérő API-t szeretne meghívni, a Microsoft.Identity.Web lehetővé teszi a felület használatát az IDownstreamApi API-műveletekben. A felület használatához:

1. Adja hozzá a Microsoft.Identity.Web.DownstreamApi NuGet-csomagot a projekthez.
2. Adja hozzá .AddDownstreamApi() a .EnableTokenAcquisitionToCallDownstreamApi()Startup.cs fájlban. .AddDownstreamApi() két argumentuma van:
   • Egy szolgáltatás (api) neve: ezt a nevet használja a vezérlőműveletekben a megfelelő konfigurációra való hivatkozáshoz
   • egy konfigurációs szakasz, amely az alsóbb rétegbeli webes API meghívásához használt paramétereket jelöli.

A kód a következő:

  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

Az OBO(on-behalf-of) folyamat egy jogkivonat lekérésére szolgál, amely meghívja az alsóbb rétegbeli webes API-t. Ebben a folyamatban a webes API egy tulajdonosi jogkivonatot kap az ügyfélalkalmazástól a felhasználó által delegált engedélyekkel, majd ezt a jogkivonatot egy másik hozzáférési jogkivonatra cseréli az alsóbb rétegbeli webes API meghívásához.

Az alábbi kód a Spring Security keretrendszerét SecurityContextHolder használja a webes API-ban az érvényesített tulajdonosi jogkivonat lekéréséhez. Ezután az MSAL Java-kódtár használatával szerez be egy jogkivonatot az alsóbb rétegbeli API-hoz a acquireToken következő hívással OnBehalfOfParameters: . Az MSAL gyorsítótárazza a jogkivonatot, hogy az API későbbi hívásai használhassák acquireTokenSilently a gyorsítótárazott jogkivonat lekérését.

@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

Az OBO(on-behalf-of) folyamat egy jogkivonat lekérésére szolgál, amely meghívja az alsóbb rétegbeli webes API-t. Ebben a folyamatban a webes API egy tulajdonosi jogkivonatot kap az ügyfélalkalmazástól a felhasználó által delegált engedélyekkel, majd ezt a jogkivonatot egy másik hozzáférési jogkivonatra cseréli az alsóbb rétegbeli webes API meghívásához.

A Python webes API-nak valamilyen köztes szoftverrel kell ellenőriznie az ügyféltől kapott tulajdonosi jogkivonatot. A webes API ezután az MSAL Python-kódtár használatával lekérte a hozzáférési jogkivonatot az alsóbb rétegbeli API-hoz a acquire_token_on_behalf_of metódus meghívásával. Az API használatára példaként tekintse meg a GitHubon a microsoft-authentication-library-for-python tesztkódot. Az 53.számú probléma megvitatása ugyanabban az adattárban egy olyan megközelítésre vonatkozik, amely meghaladja a középszintű alkalmazás szükségességét.

Az ms-identity-python-on-behalf-of mintában az OBO-folyamat implementálására is láthat példát.

A Node.js és az Azure Functions OBO-folyamat implementálására is láthat példát.

Protokoll

Az OBO protokollról további információt a Microsoft Identitásplatform és az OAuth 2.0 On-Behalf-Of folyamatában talál.

Következő lépések

Lépjen tovább ebben a forgatókönyvben a következő cikkre, és szerezze be az alkalmazás jogkivonatát.