Uzyskiwanie tokenów do wywoływania webowego API przy użyciu aplikacji demona

2025-06-26

Dotyczy: Dzierżawcy siły roboczej Biały okrąg z szarym symbolem X. dzierżawcy zewnętrzni (White circle with a gray X symbol.dowiedz się więcej)

Po utworzeniu poufnej aplikacji klienckiej możesz uzyskać token dla aplikacji, wywołując AcquireTokenForClient, przekazując zakres i opcjonalnie wymuszając odświeżenie tokenu.

Zakresy wymagane do żądania

Zakres dla żądania przepływu poświadczeń klienta to nazwa zasobu, po której następuje /.default. Ta notacja informuje identyfikator Entra firmy Microsoft o użyciu uprawnień na poziomie aplikacji zadeklarowanych statycznie podczas rejestracji aplikacji. Ponadto te uprawnienia interfejsu API muszą zostać przyznane przez administratora dzierżawy.

Oto przykład definiowania zakresów internetowego interfejsu API w ramach konfiguracji w pliku appsettings.json. Ten przykład pochodzi z przykładu kodu demon konsolowy .NET w witrynie GitHub.

{
    "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'
};

W bibliotece MSAL dla Pythona plik konfiguracji wygląda jak ten fragment kodu:

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

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

Zasoby usługi Azure AD (wersja 1.0)

Zakres używany dla poświadczeń klienta powinien zawsze być identyfikatorem zasobu, po którym /.defaultnastępuje .

Ważne

Gdy MSAL żąda tokenu dostępu dla zasobu, który akceptuje token dostępu w wersji 1.0, Microsoft Entra ID analizuje docelową grupę z żądanego zakresu, przyjmując wszystko przed ostatnim ukośnikiem i używając tego jako identyfikatora zasobu. Jeśli więc, podobnie jak usługa Azure SQL Database (https://database.windows.net), zasób oczekuje odbiorców kończących się ukośnikiem (dla usługi Azure SQL Database, https://database.windows.net/), musisz zażądać zakresu https://database.windows.net//.default. (Zwróć uwagę na podwójny ukośnik kreski). Zobacz również MSAL.NET issue #747: Resource url's trailing slash is omitted, which caused sql auth failure.

AcquireTokenForClient API

Aby uzyskać token dla aplikacji, użyj AcquireTokenForClient lub jej odpowiednik, w zależności od platformy.

W przypadku aplikacji Microsoft.Identity.Web nie musisz uzyskiwać tokenu. Możesz używać interfejsów API wyższego poziomu, tak jak pokazano w Wywoływaniu internetowego interfejsu API z poziomu aplikacji demona. Jeśli jednak używasz zestawu SDK, który wymaga tokenu, poniższy fragment kodu pokazuje, jak uzyskać ten token.

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;

Ten kod jest wyodrębniany z przykładów deweloperskich biblioteki 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;
 }

Poniższy fragment kodu ilustruje pozyskiwanie tokenów w poufnej aplikacji klienckiej biblioteki MSAL Node:

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

Element AcquireTokenForClient używa pamięci podręcznej tokenu aplikacji

W MSAL.NET AcquireTokenForClient używa pamięci podręcznej tokenów aplikacji. (Wszystkie pozostałe metody AcquireTokenXX używają pamięci podręcznej tokenów użytkownika). Nie wywołuj AcquireTokenSilent przed wywołaniem AcquireTokenForClient metody, ponieważ AcquireTokenSilent używa pamięci podręcznej tokenów użytkownika. AcquireTokenForClient sprawdza samą pamięć podręczną tokenu aplikacji i aktualizuje ją.

Protokół

Jeśli nie masz jeszcze biblioteki dla wybranego języka, możesz chcieć użyć protokołu bezpośrednio:

Pierwszy przypadek: Dostęp do żądania tokenu przy użyciu wspólnego sekretu

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

Drugi przypadek: Uzyskiwanie dostępu do żądania tokenu przy użyciu certyfikatu

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

Aby uzyskać więcej informacji, zobacz dokumentację protokołu: Platforma tożsamości Microsoft i przepływ poświadczeń klienta OAuth 2.0.

Rozwiązywanie problemów

Czy użyto zakresu resource/.default?

Jeśli zostanie wyświetlony komunikat o błędzie informujący o tym, że użyto nieprawidłowego zakresu, prawdopodobnie nie użyto resource/.default zakresu.

Jeśli otrzymasz błąd niewystarczające uprawnienia do ukończenia operacji podczas wywoływania interfejsu API, administrator najemcy musi udzielić uprawnień aplikacji.

Jeśli nie udzielasz zgody administratora aplikacji, wystąpi następujący błąd:

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

Wybierz jedną z następujących opcji, w zależności od roli.

Administrator aplikacji w chmurze

W przypadku administratora aplikacji w chmurze przejdź do pozycji Aplikacje dla przedsiębiorstw w centrum administracyjnym firmy Microsoft Entra. Wybierz rejestrację aplikacji i wybierz pozycję Uprawnienia w sekcji Zabezpieczenia w okienku po lewej stronie. Następnie wybierz duży przycisk z etykietą Udziel zgody administratora dla {Nazwa dzierżawy} (gdzie {Nazwa dzierżawy} jest nazwą katalogu).

Użytkownik standardowy

Dla standardowego użytkownika Twojej dzierżawy poproś administratora aplikacji w chmurze o udzielenie zgody administracyjnej dla aplikacji. W tym celu podaj następujący adres URL administratorowi:

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

W adresie URL:

Zastąp ciąg Enter_the_Tenant_Id_Here identyfikatorem dzierżawy lub nazwą dzierżawy (na przykład contoso.microsoft.com).
Enter_the_Application_Id_Here to identyfikator aplikacji (klienta) zarejestrowanej aplikacji.

Błąd AADSTS50011: No reply address is registered for the application może być wyświetlany po udzieleniu zgody aplikacji przy użyciu poprzedniego adresu URL. Ten błąd występuje, ponieważ aplikacja i adres URL nie mają URI przekierowania. Możesz go zignorować.

Czy wywołujesz własny interfejs API?

Jeśli aplikacja demona wywołuje własny interfejs API sieci i nie możesz dodać uprawnienia aplikacji do rejestracji aplikacji demona, musisz dodać role aplikacji do rejestracji aplikacji interfejsu API sieci.

Następne kroki

Przejdź do następnego artykułu w tym scenariuszu Wywoływanie internetowego interfejsu API.

Udostępnij za pośrednictwem