웹 API를 호출하는 웹 API: 코드 구성

이 문서에서는 OAuth 2.0 권한 부여 코드 흐름을 사용하여 Web API 앱에 대한 코드를 구성하는 방법을 설명합니다.

Microsoft에서는 다운스트림 웹 API를 호출하는 ASP.NET Core 보호 API를 개발할 때 Microsoft.Identity.Web NuGet 패키지를 사용하는 것을 권장합니다. 웹 API의 컨텍스트 내 해당 라이브러리를 빠르게 표시하려면 보호된 웹 API: 코드 구성 | Microsoft.Identity.Web을 참조하세요.

필수 조건

• 웹 API를 호출하는 웹 API 등록

앱 구성

웹 API에 대한 언어를 선택합니다.

ASP.NET Core

클라이언트 암호 또는 클라이언트 인증서

이제 웹앱이 다운스트림 웹 API를 호출하므로 appsettings.json 파일에 클라이언트 암호나 클라이언트 인증서를 제공합니다. 다음을 지정하는 섹션을 추가할 수도 있습니다.

• 다운스트림 웹 API의 URL
• API를 호출하는 데 필요한 범위

다음 예에서는 GraphBeta 섹션에서 이러한 설정을 지정합니다.

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

참고 항목

Azure Kubernetes용 워크로드 ID 페더레이션과 같은 자격 증명이 없는 솔루션을 포함하여 클라이언트 자격 증명 컬렉션을 제안할 수 있습니다. 이전 버전의 Microsoft.Identity.Web은 "ClientCredentials" 대신 단일 속성 "ClientSecret"으로 클라이언트 암호를 표현했습니다. 이는 이전 버전과의 호환성을 위해 계속 지원되지만 "ClientSecret" 속성과 "ClientCredentials" 컬렉션을 모두 사용할 수는 없습니다.

클라이언트 암호 대신 클라이언트 인증서를 제공할 수 있습니다. 다음 코드 조각에서는 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"]
  }
}

Warning

Scopes를 배열로 변경하는 것을 잊은 경우 IDownstreamApi를 사용하려고 하면 범위가 null로 나타나고 IDownstreamApi는 다운스트림 API에 대해 익명(인증되지 않은) 호출을 시도합니다. 401/unauthenticated.

Microsoft.Identity.Web은 구성이나 코드를 통해 인증서를 설명 하는 여러 가지 방법을 제공합니다. 자세한 내용은 GitHub에서 Microsoft.Identity.Web - 인증서 사용을 참조하세요.

Program.cs

using Microsoft.Identity.Web;

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

웹 API는 다운스트림 API에 대한 토큰을 획득해야 합니다. .EnableTokenAcquisitionToCallDownstreamApi() 줄을 .AddMicrosoftIdentityWebApi(Configuration) 뒤에 추가하여 지정합니다. 이 줄은 컨트롤러/페이지 작업에서 사용할 수 있는 ITokenAcquisition 서비스를 노출합니다.

그러나 대체 방법은 토큰 캐시를 구현하는 것입니다. 예를 들어, Program.cs에 .AddInMemoryTokenCaches()를 추가하면 토큰이 메모리에 캐시될 수 있습니다.

using Microsoft.Identity.Web;

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

Microsoft.Identity.Web은 다른 API에서 다운스트림 웹 API를 호출하는 두 가지 메커니즘을 제공합니다. 선택할 옵션은 Microsoft Graph 또는 다른 API를 호출하는지 여부에 따라 달라집니다.

옵션 1: Microsoft Graph 호출

Microsoft Graph를 호출하려면 Microsoft.Identity.Web을 통해 직접 GraphServiceClient(Microsoft Graph SDK에 의해 노출됨)를 API 작업에서 사용할 수 있습니다.

참고 항목

Microsoft Graph SDK v5+에는 지속적인 문제가 있습니다. 자세한 내용은 GitHub 문제를 참조하세요.

Microsoft Graph를 공개하려면:

1. 프로젝트에 Microsoft.Identity.Web.GraphServiceClient NuGet 패키지를 추가합니다.
2. Program.cs의 .EnableTokenAcquisitionToCallDownstreamApi() 뒤에 .AddMicrosoftGraph()를 추가합니다. .AddMicrosoftGraph() 에는 여러 재정의가 있습니다. 구성 섹션을 매개 변수로 사용하는 재정의를 사용하면 코드가 다음과 같이 됩니다.

using Microsoft.Identity.Web;

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

옵션 2: Microsoft Graph 이외의 다운스트림 웹 API 호출

1. 프로젝트에 Microsoft.Identity.Web.DownstreamApi NuGet 패키지를 추가합니다.
2. Program.cs의 .EnableTokenAcquisitionToCallDownstreamApi() 뒤에 .AddDownstreamApi()를 추가합니다. 코드는 다음과 같습니다.

using Microsoft.Identity.Web;

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

이 경우

• MyApi은(는) 웹 API에서 호출하려는 다운스트림 웹 API의 이름을 표시합니다.
• MyApiScope은(는) 다운스트림 웹 API와 상호 작용하기 위해 웹 API가 요청하는 데 필요한 범위입니다.

이러한 값은 다음 코드 조각과 유사한 JSON에 표시됩니다.

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

웹앱이 다른 API 리소스를 호출해야 하는 경우 다음 코드 조각에 표시된 대로 관련 범위를 사용하여 .AddDownstreamApi() 메서드를 반복합니다.

using Microsoft.Identity.Web;

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

.EnableTokenAcquisitionToCallDownstreamApi는 매개 변수 없이 호출됩니다. 즉, 컨트롤러가 범위를 지정하여 토큰을 요청하는 시점에 액세스 토큰이 획득됩니다.

.EnableTokenAcquisitionToCallDownstreamApi를 호출할 때 범위를 전달할 수도 있습니다. 이렇게 하면 웹앱이 초기 사용자 로그인 중에 토큰을 획득하게 됩니다. 그런 다음 컨트롤러가 요청할 때 토큰을 캐시에서 가져옵니다.

웹앱과 마찬가지로 다양한 토큰 캐시 구현을 선택할 수 있습니다. 자세한 내용은 Microsoft ID 웹 - GitHub의 토큰 캐시 serialization을 참조하세요.

다음 이미지에서는 Microsoft.Identity.Web의 가능성과 Program.cs에 미치는 영향을 보여 줍니다.

참고 항목

여기의 코드 예제를 완전히 이해하려면 ASP.NET Core 기본, 특히 종속성 주입 및 옵션에 대해 잘 알고 있어야 합니다.

ASP.NET

클라이언트 암호 또는 클라이언트 인증서

이제 웹앱이 다운스트림 웹 API를 호출하므로 appsettings.json 파일에 클라이언트 암호나 클라이언트 인증서를 제공합니다. 다음을 지정하는 섹션을 추가할 수도 있습니다.

• 다운스트림 웹 API의 URL
• API를 호출하는 데 필요한 범위

다음 예에서는 GraphBeta 섹션에서 이러한 설정을 지정합니다.

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

참고 항목

Azure Kubernetes용 워크로드 ID 페더레이션과 같은 자격 증명이 없는 솔루션을 포함하여 클라이언트 자격 증명 컬렉션을 제안할 수 있습니다. 이전 버전의 Microsoft.Identity.Web은 "ClientCredentials" 대신 단일 속성 "ClientSecret"으로 클라이언트 암호를 표현했습니다. 이는 이전 버전과의 호환성을 위해 계속 지원되지만 "ClientSecret" 속성과 "ClientCredentials" 컬렉션을 모두 사용할 수는 없습니다.

클라이언트 암호 대신 클라이언트 인증서를 제공할 수 있습니다. 다음 코드 조각에서는 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"]
  }
}

Warning

Scopes를 배열로 변경하는 것을 잊은 경우 IDownstreamApi를 사용하려고 하면 범위가 null로 나타나고 IDownstreamApi는 다운스트림 API에 대해 익명(인증되지 않은) 호출을 시도합니다. 401/unauthenticated.

Microsoft.Identity.Web은 구성이나 코드를 통해 인증서를 설명 하는 여러 가지 방법을 제공합니다. 자세한 내용은 GitHub에서 Microsoft.Identity.Web - 인증서 사용을 참조하세요.

Startup.Auth.cs 수정

웹앱은 다운스트림 API에 대한 토큰을 획득해야 합니다. Microsoft.Identity.Web은 웹 API에서 다운스트림 API를 호출하기 위한 두 가지 메커니즘을 제공합니다. 선택할 옵션은 Microsoft Graph 또는 다른 API를 호출하는지 여부에 따라 달라집니다.

옵션 1: Microsoft Graph 호출

Microsoft Graph를 호출하려면 Microsoft.Identity.Web을 통해 직접 GraphServiceClient(Microsoft Graph SDK에 의해 노출됨)를 API 작업에 사용할 수 있습니다. Microsoft Graph를 공개하려면:

1. 프로젝트에 Microsoft.Identity.Web.GraphServiceClient NuGet 패키지를 추가합니다.

2. Startup.Auth.cs 파일의 서비스 컬렉션에 .AddMicrosoftGraph()를 추가합니다. .AddMicrosoftGraph() 에는 여러 재정의가 있습니다. 구성 섹션을 매개 변수로 사용하는 재정의를 사용하면 코드가 다음과 같이 됩니다.

   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: Microsoft Graph 이외의 다운스트림 웹 API 호출

Microsoft Graph 이외의 API를 호출하려는 경우 Microsoft.Identity.Web을 사용하면 API 작업에서 IDownstreamApi 인터페이스를 사용할 수 있습니다. 이 인터페이스를 사용하려면:

1. 프로젝트에 Microsoft.Identity.Web.DownstreamApi NuGet 패키지를 추가합니다.
2. .AddDownstreamApi()을 .EnableTokenAcquisitionToCallDownstreamApi() 뒤에, Startup.cs 파일에서 추가합니다. .AddDownstreamApi()에는 다음의 두 가지 인수가 있습니다.
   • 서비스 이름(API): 컨트롤러 작업에서 이 이름을 사용하여 해당 구성을 참조합니다.
   • 다운스트림 웹 API를 호출하는 데 사용되는 매개 변수를 나타내는 구성 섹션.

코드는 다음과 같습니다.

  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

OBO(On-Behalf-of) 흐름 사용

OBO(On-Behalf-of) 흐름은 다운스트림 웹 API를 호출하는 토큰을 가져오는 데 사용됩니다. 해당 흐름에서 웹 API는 클라이언트 애플리케이션으로부터 사용자 위임 권한이 있는 전달자 토큰을 받아 다운스트림 웹 API 호출에 필요한 다른 액세스 토큰으로 교환합니다.

아래 코드는 유효성이 확인된 전달자 토큰을 가져오기 위하여 웹 API에서 Spring Security 프레임워크의 SecurityContextHolder를 이용합니다. 이어서, MSAL Java 라이브러리를 사용하여 OnBehalfOfParameters가 있는 acquireToken을 사용하는 다운스트림 API용 토큰을 획득합니다. MSAL은 해당 토큰을 캐시하여 API에 대한 후속 호출이 acquireTokenSilently를 사용하여 캐시된 토큰을 얻을 수 있도록 합니다.

@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

OBO(On-Behalf-of) 흐름 사용

OBO(On-Behalf-of) 흐름은 다운스트림 웹 API를 호출하는 토큰을 가져오는 데 사용됩니다. 해당 흐름에서 웹 API는 클라이언트 애플리케이션으로부터 사용자 위임 권한이 있는 전달자 토큰을 받아 다운스트림 웹 API 호출에 필요한 다른 액세스 토큰으로 교환합니다.

Python 웹 API는 일부 미들웨어를 사용하여 클라이언트로부터 받은 전달자 토큰의 유효성을 검사해야 합니다. 이후, 웹 API는 acquire_token_on_behalf_of 메서드를 호출하여 MSAL Python 라이브러리를 사용하는 다운스트림 API를 위한 액세스 토큰을 획득할 수 있습니다. 해당 API 사용에 대한 예제는 GitHub의 Python용 Microsoft 인증 라이브러리 테스트 코드를 참조하세요. 동일한 리포지토리의 문제 53 토론에서 중간 계층 애플리케이션 요구를 우회하는 방법에 대하여서도 확인하세요.

ms-identity-python-on-behalf-of 샘플에서 OBO 흐름 구현의 예시도 확인할 수 있습니다.

Node.js 및 Azure Functions에서도 OBO 흐름 구현의 예시를 확인할 수 있습니다.

프로토콜

OBO 프로토콜에 대한 자세한 내용은 Microsoft ID 플랫폼 및 OAuth 2.0 On-Behalf-Of 흐름을 참조하세요.

다음 단계

앱에 대한 토큰을 획득합니다.