Daemon uygulaması kullanarak web API'sini çağırmak için belirteç alma

Makale
04/09/2024

Gizli bir istemci uygulaması oluşturulduktan sonra, çağrısı AcquireTokenForClientyaparak, kapsamı geçirerek ve isteğe bağlı olarak belirtecin yenilenmesini zorlayarak uygulama için bir belirteç alabilirsiniz.

İstekte bulunacak kapsamlar

İstemci kimlik bilgisi akışı için istekte bulunacak kapsam, kaynağın adı ve ardından /.defaultgelen adıdır. Bu notasyon, Microsoft Entra Id'ye uygulama kaydı sırasında statik olarak bildirilen uygulama düzeyi izinlerini kullanmasını bildirir. Ayrıca, bu API izinleri bir kiracı yöneticisi tarafından verilmelidir.

Bir appsettings.json dosyasında yapılandırmanın bir parçası olarak web API'sinin kapsamlarını tanımlama örneği aşağıda verilmiştir. Bu örnek GitHub'da .NET konsol daemon kodu örneğinden alınmıştır.

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

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

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

MSAL Python'da yapılandırma dosyası şu kod parçacığına benzer:

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

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

Azure AD (v1.0) kaynakları

İstemci kimlik bilgileri için kullanılan kapsam her zaman kaynak kimliği ve ardından /.defaultolmalıdır.

Önemli

MSAL, sürüm 1.0 erişim belirtecini kabul eden bir kaynak için erişim belirteci istediğinde, Microsoft Entra Id son eğik çizgiden önceki her şeyi alıp kaynak tanımlayıcısı olarak kullanarak istenen hedef kitleyi istenen kapsamdan ayrıştırıyor. Bu nedenle, Azure SQL Veritabanı ()https://database.windows.net gibi kaynak eğik çizgiyle biten bir hedef kitle bekliyorsa (Azure SQL Veritabanı https://database.windows.net/için) kapsamı https://database.windows.net//.defaultistemeniz gerekir. (Çift eğik çizgiye dikkat edin.) Ayrıca bkz. MSAL.NET sorun #747: Resource url's trailing slash is omitted, which caused sql auth failure.

AcquireTokenForClient API'si

Uygulama için belirteç almak için platforma bağlı olarak veya eşdeğerini kullanın AcquireTokenForClient .

Microsoft.Identity.Web ile belirteç almanız gerekmez. Bir daemon uygulamasından web API'sini çağırma bölümünde gördüğünüz gibi daha üst düzey API'ler kullanabilirsiniz. Ancak belirteç gerektiren bir SDK kullanıyorsanız, aşağıdaki kod parçacığı bu belirtecin nasıl alındığını gösterir.

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;

Bu kod MSAL Java geliştirme örneklerinden ayıklanır.

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

Aşağıdaki kod parçacığı, bir MSAL Node gizli istemci uygulamasında belirteç alımını gösterir:

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

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

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 uygulama belirteci önbelleğini kullanır

MSAL.NET'da uygulama AcquireTokenForClient belirteci önbelleğini kullanır. (Diğer tüm AcquireTokenXX yöntemleri kullanıcı belirteci önbelleğini kullanır.) kullanıcı belirteci önbelleğini kullandığındanAcquireTokenSilent, çağrısından önce aramayın AcquireTokenSilentAcquireTokenForClient. AcquireTokenForClientuygulama belirtecinin önbelleğini denetler ve güncelleştirir.

Protokol

Seçtiğiniz dil için henüz bir kitaplığınız yoksa protokolü doğrudan kullanmak isteyebilirsiniz:

İlk durum: Paylaşılan gizli dizi kullanarak belirteç isteğine erişme

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

İkinci durum: Sertifika kullanarak belirteç isteğine erişme

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

Daha fazla bilgi için protokol belgelerine bakın: Microsoft kimlik platformu ve OAuth 2.0 istemci kimlik bilgileri akışı.

Sorun giderme

resource/.default kapsamını kullandınız mı?

Geçersiz bir kapsam kullandığınızı belirten bir hata iletisi alırsanız, büyük olasılıkla kapsamı kullanmadınız resource/.default .

API'yi çağırdığınızda işlem hatasını tamamlamak için Yetersiz ayrıcalıklar alırsanız kiracı yöneticisinin uygulamaya izin vermesi gerekir.

Uygulamanıza yönetici onayı vermezseniz aşağıdaki hatayla karşılaşırsınız:

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

Role bağlı olarak aşağıdaki seçeneklerden birini belirleyin.

Genel kiracı yöneticisi

Genel kiracı yöneticisi için Microsoft Entra yönetim merkezinde Kurumsal uygulamalar'a gidin. Uygulama kaydını seçin ve sol bölmenin Güvenlik bölümünden İzinler'i seçin. Ardından {Kiracı Adı} için yönetici onayı ver etiketli büyük düğmeyi seçin (burada {Tenant Name}, dizinin adıdır).

Standart kullanıcı

Kiracınızın standart bir kullanıcısı için Genel Yönetici istrator'dan uygulamaya yönetici onayı vermesini isteyin. Bunu yapmak için yöneticiye aşağıdaki URL'yi sağlayın:

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

URL'de:

değerini Enter_the_Tenant_Id_Here kiracı kimliği veya kiracı adıyla değiştirin (örneğin, contoso.microsoft.com).
Enter_the_Application_Id_Here , kayıtlı uygulamanın uygulama (istemci) kimliğidir.

AADSTS50011: No reply address is registered for the application Hata, yukarıdaki URL'yi kullanarak uygulamaya onay verdikten sonra görüntülenebilir. Uygulamanın ve URL'nin yeniden yönlendirme URI'si olmadığından bu hata oluşur. Bu yoksayılabilir.

Kendi API'nizi mi çağırıyorsunuz?

Daemon uygulamanız kendi web API'nizi çağırıyorsa ve daemon'un uygulama kaydına uygulama izni ekleyemediyseniz web API'sinin uygulama kaydına uygulama rolleri eklemeniz gerekir.

Sonraki adımlar

Bu senaryoda web API'sini çağırma adlı sonraki makaleye geçin.