Daemon uygulaması kullanarak bir web API'sini çağırmak için belirteçleri elde etme

Şunlar için geçerlidir: İş gücü kiracıları (daha fazla bilgi edinin)

Gizli istemci uygulaması için belirteç edinme

Kullanıcı etkileşimi olmadan çalışan Daemon uygulamaları ve diğer gizli istemci uygulamaları, yalnızca uygulama erişim belirteçleri almak için OAuth 2.0 istemci kimlik bilgileri akışını kullanır. Bu makalede gerekli kapsamları yapılandırma, belirteç almak için API'yi (veya platform eşdeğerini) çağırma AcquireTokenForClient ve sık karşılaşılan hataları giderme işlemleri açıklanır. Devam etmeden önce gizli bir istemci uygulaması oluşturduğunuzdan emin olun.

İstekte bulunacak kapsamlar

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

.NET

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

Java

Java'da varsayılan Microsoft Graph kapsamını sabit olarak tanımlayın:

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

Node.js

Node.jsiçinde, belirteç isteği nesnesinde kapsamı belirtin:

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

Piton

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

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

.NET (düşük düzey)

Alt düzey .NET kodunda, kapsamı kaynak kimliğinin sonuna /.default ekleyerek oluşturun:

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 istenen kapsamdan hedef kitleyi ayrıştırarak, son eğik çizgiden önceki kısmı alır ve kaynak tanımlayıcısı olarak kullanır. 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

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

.NET

Microsoft.Identity.Web ile doğrudan belirteç edinmeniz 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 örnekte gösterildiği gibi soyutlama aracılığıyla ITokenAcquirer bir uygulama belirteci alabilirsiniz:

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

Aşağıdaki Java belirteç alma örneği 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;
 }

Node.js

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

Piton

Aşağıdaki örnekte, istemci kimlik bilgileriyle yalnızca uygulama erişim belirteci almak için MSAL Python deseni gösterilmektedir:

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 (düşük düzey)

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.) AcquireTokenSilent, kullanıcı belirteci önbelleğini kullandığından, AcquireTokenForClient çağrısından önce AcquireTokenSilent çağrısını yapmayın. uygulama 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 anahtar kullanarak jeton 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 resource/.default kapsamını hatalı kullandınız.

Yönetici onayı sağlamayı unuttun mu? Daemon uygulamalarının buna ihtiyacı var!

API'yi çağırdığınızda "İşlemi tamamlamak için yetersiz ayrıcalık" hatası alırsanız, kiracı yöneticisinin uygulamaya izin vermesi gerekir.

Uygulamanıza yönetici onayı vermezseniz, API aşağıdaki örneğe benzer bir hata yanıtı döndürür:

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.

Bulut Uygulaması Yöneticisi

Bulut Uygulaması 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 {Kiracı Adı}, dizinin adıdır).

Standart kullanıcı

Kiracınızın standart bir kullanıcısı için Bulut Uygulaması Yöneticisinden uygulamaya yönetici onayı vermesini isteyin. Onay istemek için, yöneticiyi aşağıdaki yönetici onayı uç noktası URL'sine yönlendirin:

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 AADSTS50011 ve URL'nin yeniden yönlendirme URI'si olmadığından hata oluşur. Bu hatayı gönül rahatlığıyla yoksayabilirsiniz.

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

.NET

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

Java

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

Node.js

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

Piton

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

.NET düşük seviye

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