디먼 애플리케이션을 사용하여 웹 API를 호출하는 토큰 획득

기밀 클라이언트 애플리케이션을 생성한 후에는 AcquireTokenForClient를 호출하고, 범위를 전달하고, 필요에 따라 토큰을 강제로 새로 고치는 방법으로 앱의 토큰을 획득할 수 있습니다.

요청할 범위

클라이언트 자격 증명 흐름에 대해 요청할 범위는 /.default 앞에 있는 리소스의 이름입니다. 이 표기법은 애플리케이션 등록 시 고정으로 선언된 애플리케이션 수준 권한을 사용하도록 Microsoft Entra ID에 지시합니다. 또한 이러한 API 권한은 테넌트 관리자가 부여해야 합니다.

.NET

다음은 appsettings.json 파일에서 구성의 일부로 웹 API에 대한 범위를 정의하는 예제입니다. 이 예제는 GitHub의 .NET 콘솔 디먼 코드 샘플에서 가져옵니다.

{
    "AzureAd": {
        // Same AzureAd section as before.
    },

    "MyWebApi": {
        "BaseUrl": "https://localhost:44372/",
        "RelativePath": "api/TodoList",
        "RequestAppToken": true,
        "Scopes": [ "[Enter here the scopes for your web API]" ]
    }
}

Java

final static String GRAPH_DEFAULT_SCOPE = "https://graph.microsoft.com/.default";

Node.JS

const tokenRequest = {
    scopes: [process.env.GRAPH_ENDPOINT + '.default'], // e.g. 'https://graph.microsoft.com/.default'
};

Python

MSAL Python에서 구성 파일은 다음 코드 조각과 같습니다.

{
    "scope": ["https://graph.microsoft.com/.default"],
}

.NET(하위 수준)

ResourceId = "someAppIDURI";
var scopes = new [] {  ResourceId+"/.default"};

Azure AD(v1.0) 리소스

클라이언트 자격 증명에 사용되는 범위는 항상 리소스 ID 뒤에 /.default이 따라와야 합니다.

Important

MSAL에서 버전 1.0 액세스 토큰을 허용하는 리소스에 대한 액세스 토큰을 요청하는 경우, Microsoft Entra ID는 마지막 슬래시 앞에 있는 모든 항목을 리소스 식별자로 사용하여 요청된 범위에서 원하는 대상 그룹을 구문 분석합니다. 따라서 Azure SQL Database(https://database.windows.net)와 같이 리소스가 슬래시로 끝나는 대상을 예상하는 경우(Azure SQL Database의 경우 https://database.windows.net/) https://database.windows.net//.default 범위를 요청해야 합니다. (이중 슬래시 참고) MSAL.NET 문제 #747: Resource url's trailing slash is omitted, which caused sql auth failure도 참조하세요.

AcquireTokenForClient API

앱의 토큰을 얻으려면 플랫폼에 따라 AcquireTokenForClient 또는 그와 동등한 것을 사용합니다.

.NET

Microsoft.Identity.Web을 사용하면 토큰을 획득할 필요가 없습니다. 디먼 애플리케이션에서 웹 API 호출에 표시된 것처럼 더 높은 수준의 API를 사용할 수 있습니다. 그러나 토큰이 필요한 SDK를 사용하는 경우 다음 코드 조각은 이 토큰을 가져오는 방법을 보여 줍니다.

using Microsoft.Extensions.DependencyInjection;
using Microsoft.Identity.Abstractions;
using Microsoft.Identity.Web;

// In the Program.cs, acquire a token for your downstream API

var tokenAcquirerFactory = TokenAcquirerFactory.GetDefaultInstance();
ITokenAcquirer acquirer = tokenAcquirerFactory.GetTokenAcquirer();
AcquireTokenResult tokenResult = await acquirer.GetTokenForUserAsync(new[] { "https://graph.microsoft.com/.default" });
string accessToken = tokenResult.AccessToken;

Java

이 코드는 MSAL Java 개발자 샘플에서 가져왔습니다.

private static IAuthenticationResult acquireToken() throws Exception {

     // Load token cache from file and initialize token cache aspect. The token cache will have
     // dummy data, so the acquireTokenSilently call will fail.
     TokenCacheAspect tokenCacheAspect = new TokenCacheAspect("sample_cache.json");

     IClientCredential credential = ClientCredentialFactory.createFromSecret(CLIENT_SECRET);
     ConfidentialClientApplication cca =
             ConfidentialClientApplication
                     .builder(CLIENT_ID, credential)
                     .authority(AUTHORITY)
                     .setTokenCacheAccessAspect(tokenCacheAspect)
                     .build();

     IAuthenticationResult result;
     try {
         SilentParameters silentParameters =
                 SilentParameters
                         .builder(SCOPE)
                         .build();

         // try to acquire token silently. This call will fail since the token cache does not
         // have a token for the application you are requesting an access token for
         result = cca.acquireTokenSilently(silentParameters).join();
     } catch (Exception ex) {
         if (ex.getCause() instanceof MsalException) {

             ClientCredentialParameters parameters =
                     ClientCredentialParameters
                             .builder(SCOPE)
                             .build();

             // Try to acquire a token. If successful, you should see
             // the token information printed out to console
             result = cca.acquireToken(parameters).join();
         } else {
             // Handle other exceptions accordingly
             throw ex;
         }
     }
     return result;
 }

Node.JS

다음 코드 조각에서는 MSAL 노드 기밀 클라이언트 애플리케이션에서 토큰을 획득하는 방법을 설명합니다.

try {
    const authResponse = await cca.acquireTokenByClientCredential(tokenRequest);
    console.log(authResponse.accessToken) // display access token
} catch (error) {
    console.log(error);
}

Python

# The pattern to acquire a token looks like this.
result = None

# First, the code looks up a token from the cache.
# Because we're looking for a token for the current app, not for a user,
# use None for the account parameter.
result = app.acquire_token_silent(config["scope"], account=None)

if not result:
    logging.info("No suitable token exists in cache. Let's get a new one from Azure AD.")
    result = app.acquire_token_for_client(scopes=config["scope"])

if "access_token" in result:
    # Call a protected API with the access token.
    print(result["token_type"])
else:
    print(result.get("error"))
    print(result.get("error_description"))
    print(result.get("correlation_id"))  # You might need this when reporting a bug.

.NET(하위 수준)

using Microsoft.Identity.Client;

// With client credentials flows, the scope is always of the shape "resource/.default" because the
// application permissions need to be set statically (in the portal or by PowerShell), and then granted by
// a tenant administrator.
string[] scopes = new string[] { "https://graph.microsoft.com/.default" };

AuthenticationResult result = null;
try
{
 result = await app.AcquireTokenForClient(scopes)
                  .ExecuteAsync();
}
catch (MsalUiRequiredException ex)
{
    // The application doesn't have sufficient permissions.
    // - Did you declare enough app permissions during app creation?
    // - Did the tenant admin grant permissions to the application?
}
catch (MsalServiceException ex) when (ex.Message.Contains("AADSTS70011"))
{
    // Invalid scope. The scope has to be in the form "https://resourceurl/.default"
    // Mitigation: Change the scope to be as expected.
}

AcquireTokenForClient는 애플리케이션 토큰 캐시를 사용합니다

MSAL.NET에서는 AcquireTokenForClient가 애플리케이션 토큰 캐시를 사용합니다. (다른 모든 AcquireTokenXX 메서드는 사용자 토큰 캐시를 사용합니다.) AcquireTokenSilent는 사용자 토큰 캐시를 사용하므로 AcquireTokenForClient를 호출하기 전에 AcquireTokenSilent를 호출하지 마세요. AcquireTokenForClient는 애플리케이션 토큰 캐시 자체를 확인하고 업데이트합니다.

프로토콜

선택한 언어에 대한 라이브러리가 아직 없는 경우 프로토콜을 직접 사용하는 것이 좋습니다.

첫 번째 사례: 공유 암호를 사용하여 토큰 요청에 액세스

POST /{tenant}/oauth2/v2.0/token HTTP/1.1           //Line breaks for clarity.
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&scope=https%3A%2F%2Fgraph.microsoft.com%2F.default
&client_secret=A1b-C2d_E3f.H4i,J5k?L6m!N7o-P8q_R9s.T0u
&grant_type=client_credentials

두 번째 사례: 인증서를 사용하여 토큰 요청에 액세스

POST /{tenant}/oauth2/v2.0/token HTTP/1.1               // Line breaks for clarity.
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

scope=https%3A%2F%2Fgraph.microsoft.com%2F.default
&client_id=11112222-bbbb-3333-cccc-4444dddd5555
&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
&client_assertion=aaaaaaaa-0b0b-...
&grant_type=client_credentials

자세한 내용은 다음 프로토콜 설명서를 참조하세요. Microsoft ID 플랫폼 및 OAuth 2.0 클라이언트 자격 증명 흐름.

문제 해결

resource/.default 범위를 사용했나요?

유효하지 않은 범위를 사용했음을 나타내는 오류 메시지가 표시되면 resource/.default 범위를 사용하지 않았을 수 있습니다.

관리자 동의를 제공을 잊으셨나요? 디먼 앱에는 관리자 동의가 필요합니다.

API를 호출할 때 작업 오류를 완료하기에 불충분한 권한이 있는 경우 테넌트 관리자는 애플리케이션에 권한을 부여해야 합니다.

애플리케이션에 관리자 동의를 부여하지 않으면 다음 오류가 발생합니다.

Failed to call the web API: Forbidden
Content: {
  "error": {
    "code": "Authorization_RequestDenied",
    "message": "Insufficient privileges to complete the operation.",
    "innerError": {
      "request-id": "<guid>",
      "date": "<date>"
    }
  }
}

역할에 따라 다음 옵션 중 하나를 선택합니다.

글로벌 테넌트 관리자

전역 테넌트 관리자인 경우 Microsoft Entra 관리 센터에서 엔터프라이즈 애플리케이션으로 이동합니다. 앱 등록을 선택하고, 왼쪽 창의 보안 섹션에서 권한을 선택합니다. 그런 다음, {Tenant Name}에 대한 관리자 동의 허용 레이블이 지정된 큰 단추를 선택합니다(여기서 {Tenant Name}은 디렉터리 이름임).

표준 사용자

테넌트의 표준 사용자의 경우 전역 관리주인에게 애플리케이션에 대한 관리자 동의를 부여하도록 요청합니다. 이렇게 하려면 관리자에게 다음 URL을 제공합니다.

https://login.microsoftonline.com/Enter_the_Tenant_Id_Here/adminconsent?client_id=Enter_the_Application_Id_Here

URL에서:

• Enter_the_Tenant_Id_Here를 테넌트 ID 또는 테넌트 이름으로 바꿉니다(예: contoso.microsoft.com).
• Enter_the_Application_Id_Here는 등록한 애플리케이션의 애플리케이션(클라이언트) ID입니다.

이전 URL을 사용하여 앱에 동의를 허용한 후에 AADSTS50011: No reply address is registered for the application 오류가 표시될 수 있습니다. 이 오류는 애플리케이션과 URL에 리디렉션 URI가 없기 때문에 발생합니다. 이 메시지는 무시하고,

사용자 고유의 API를 호출하고 있나요?

디먼 앱이 사용자 고유의 웹 API를 호출하고 디먼의 앱 등록에 앱 권한을 추가할 수 없는 경우 웹 API의 앱 등록에 앱 역할을 추가해야 합니다.

다음 단계

.NET

이 시나리오의 다음 문서인 웹 API 호출로 이동합니다.

Java

이 시나리오의 다음 문서인 웹 API 호출로 이동합니다.

Node.JS

이 시나리오의 다음 문서인 웹 API 호출로 이동합니다.

Python

이 시나리오의 다음 문서인 웹 API 호출로 이동합니다.

.NET 하위 수준

이 시나리오의 다음 문서인 웹 API 호출로 이동합니다.