다음을 통해 공유


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

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

요청할 범위

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

다음은 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]" ]
    }
}

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 또는 그와 동등한 것을 사용합니다.

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;

프로토콜

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

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

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의 앱 등록에 앱 역할을 추가해야 합니다.

다음 단계

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