Application démon conçue pour appeler des API web - acquisition d'un jeton

Une fois l’application cliente confidentielle construite, vous pouvez acquérir un jeton pour celle-ci en appelant AcquireTokenForClient, en transmettant l’étendue, voire en forçant une actualisation du jeton.

Étendues à demander

L'étendue à demander pour un flux d'informations d'identification client est le nom de la ressource suivi de /.default. Cette notation indique à Azure Active Directory (Azure AD) d’utiliser les autorisations de niveau application déclarées de manière statique lors de l’inscription de l’application. En outre, ces autorisations d’API doivent être accordées par un administrateur client.

.NET

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

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

Dans MSAL Python, le fichier de configuration ressemble à l’extrait de code suivant :

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

Ressources Azure AD (v1.0)

L’étendue utilisée pour les informations d’identification client doit toujours être l’ID de ressource suivi de /.default.

Important

Quand MSAL demande un jeton d’accès pour une ressource acceptant un jeton d’accès de version 1.0, Azure AD analyse l’audience souhaitée d’après l’étendue demandée, en prenant tout ce qui précède la dernière barre oblique et en l’utilisant comme identificateur de la ressource. Par conséquent, si, comme Azure SQL Database (https://database.windows.net), la ressource attend une audience se terminant par une barre oblique (pour Azure SQL Database, https://database.windows.net/), vous devez demander une étendue de https://database.windows.net//.default. (Notez la double barre oblique.) Voir aussi le problème MSAL.NET no 747 : Resource url's trailing slash is omitted, which caused sql auth failure.

API AcquireTokenForClient

Pour acquérir un jeton pour l’application, vous devez utiliser AcquireTokenForClient ou l’équivalent, en fonction de la plateforme.

.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 utilise le cache de jetons d’application

Dans MSAL.NET, AcquireTokenForClient utilise le cache de jetons de l’application (toutes les autres méthodes AcquireTokenXX utilisent le cache de jetons de l’utilisateur). N’appelez pas AcquireTokenSilent avant d’appeler AcquireTokenForClient, car AcquireTokenSilent utilise le cache de jetons de l’utilisateur. AcquireTokenForClient vérifie le cache de jetons d'application et le met à jour.

Java

Ce code est extrait des exemples de développement 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

L’extrait de code ci-dessous illustre l’acquisition de jeton dans une application cliente confidentielle MSAL Node :

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 AAD.")
    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.

Protocol

Si vous n’avez pas encore de bibliothèque pour la langue de votre choix, vous pouvez utiliser directement le protocole :

Premier cas : accéder à la demande de jeton à l’aide d’un secret partagé

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=535fb089-9ff3-47b6-9bfb-4f1264799865
&scope=https%3A%2F%2Fgraph.microsoft.com%2F.default
&client_secret=qWgdYAmab0YSkuL1qKv5bPX
&grant_type=client_credentials

Deuxième cas : accéder à la demande de jeton à l’aide d’un certificat

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=97e0a5b7-d745-40b6-94fe-5f77d35c6e05
&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
&client_assertion=eyJhbGciOiJSUzI1NiIsIng1dCI6Imd4OHRHeXN5amNScUtqRlBuZDdSRnd2d1pJMCJ9.eyJ{a lot of characters here}M8U3bSUKKJDEg
&grant_type=client_credentials

Pour plus d'informations, consultez la documentation du protocole : Plateforme d’identités Microsoft et flux d’informations d’identification du client OAuth 2.0.

Dépannage

Avez-vous utilisé l'étendue resource/.default ?

Si vous recevez un message d'erreur indiquant que vous avez utilisé une étendue non valide, cela signifie probablement que vous n'avez pas utilisé l'étendue resource/.default.

Avez-vous oublié de fournir le consentement administrateur ? Les applications démon en ont besoin !

Si vous rencontrez l’erreur Privilèges insuffisants pour effectuer l’opération lors de l’appel de l’API, cela signifie que l’administrateur client doit accorder des autorisations à l’application. Consultez l'étape 6 de la section Inscrire l'application cliente ci-dessus. En général, une erreur similaire à celle-ci s’affiche :

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

Appelez-vous votre propre API ?

Si votre application démon appelle votre propre API web et que vous n’avez pas pu ajouter d’autorisation d’application à l’inscription de l’application du démon, vous devez Ajouter des rôles d’application à l’inscription d’application de l’API web.

Étapes suivantes

.NET

Passez à l’article suivant de ce scénario, Appeler une API web.

Java

Passez à l’article suivant de ce scénario, Appeler une API web.

Node.JS

Passez à l’article suivant de ce scénario, Appeler une API web.

Python

Passez à l’article suivant de ce scénario, Appeler une API web.