Så här konfigurerar du daemonappar som anropar webb-API:er

Artikel
02/01/2024

Lär dig hur du konfigurerar koden för ditt daemonprogram som anropar webb-API:er.

Microsoft-bibliotek som stöder daemonappar

Följande Microsoft-bibliotek stöder daemon-appar:

Språk/ramverk	Projekt på GitHub	Paket	Få komma igång	Allmänt tillgänglig (GA) eller Offentlig förhandsversion¹
.NET	MSAL.NET	Microsoft.Identity.Client	Snabbstart	Allmän tillgänglighet
Java	MSAL4J	msal4j	—	Allmän tillgänglighet
Nod	MSAL-nod	msal-node	Snabbstart	Allmän tillgänglighet
Python	MSAL Python	msal-python	Snabbstart	Allmän tillgänglighet

¹ Universella licensvillkor för onlinetjänster gäller för bibliotek i offentlig förhandsversion.

Konfigurera utfärdaren

Daemon-program använder programbehörigheter i stället för delegerade behörigheter. Därför kan deras kontotyp som stöds inte vara ett konto i någon organisationskatalog eller något personligt Microsoft-konto (till exempel Skype, Xbox Outlook.com). Det finns ingen klientorganisationsadministratör som beviljar medgivande till ett daemonprogram för ett personligt Microsoft-konto. Du måste välja konton i min organisation eller konton i någon organisation.

Den utfärdare som anges i programkonfigurationen ska vara klientorganisation (ange ett klient-ID eller ett domännamn som är associerat med din organisation).

Även om du vill tillhandahålla ett verktyg för flera klienter bör du använda ett klientorganisations-ID eller domännamn, och inte common eller organizations med det här flödet, eftersom tjänsten inte på ett tillförlitligt sätt kan härleda vilken klientorganisation som ska användas.

Konfigurera och instansiera programmet

I MSAL-bibliotek skickas klientautentiseringsuppgifterna (hemligheten eller certifikatet) som en parameter för den konfidentiella klientprogramkonstruktionen.

Viktigt!

Även om ditt program är ett konsolprogram som körs som en tjänst måste det vara ett konfidentiellt klientprogram om det är ett daemonprogram.

Konfigurationsfil

Konfigurationsfilen definierar:

Molninstansen och klient-ID:t, som tillsammans utgör utfärdaren.
Det klient-ID som du fick från programregistreringen.
Antingen en klienthemlighet eller ett certifikat.

Här är ett exempel på hur du definierar konfigurationen i en appsettings.json-fil . Det här exemplet är hämtat från daemonkodexemplet för .NET-konsolen på GitHub.

{
    "AzureAd": {
        "Instance": "https://login.microsoftonline.com/",
        "TenantId": "[Enter here the tenantID or domain name for your Azure AD tenant]",
        "ClientId": "[Enter here the ClientId for your application]",
        "ClientCredentials": [
            {
                "SourceType": "ClientSecret",
                "ClientSecret": "[Enter here a client secret for your application]"
            }
        ]
    }
}

Du anger ett certifikat i stället för klienthemligheten eller autentiseringsuppgifter för arbetsbelastningsidentitetsfederation .

 private final static String CLIENT_ID = "";
 private final static String AUTHORITY = "https://login.microsoftonline.com/<tenant>/";
 private final static String CLIENT_SECRET = "";
 private final static Set<String> SCOPE = Collections.singleton("https://graph.microsoft.com/.default");

Konfigurationsparametrar för Node.js daemon-exemplet finns i en .env-fil :

# Credentials
TENANT_ID=Enter_the_Tenant_Info_Here
CLIENT_ID=Enter_the_Application_Id_Here

// You provide either a ClientSecret or a CertificateConfiguration, or a ClientAssertion. These settings are exclusive
CLIENT_SECRET=Enter_the_Client_Secret_Here
CERTIFICATE_THUMBPRINT=Enter_the_certificate_thumbprint_Here
CERTIFICATE_PRIVATE_KEY=Enter_the_certificate_private_key_Here
CLIENT_ASSERTION=Enter_the_Assertion_String_Here

# Endpoints
// the Azure AD endpoint is the authority endpoint for token issuance
AAD_ENDPOINT=Enter_the_Cloud_Instance_Id_Here // https://login.microsoftonline.com/
// the graph endpoint is the application ID URI of Microsoft Graph
GRAPH_ENDPOINT=Enter_the_Graph_Endpoint_Here // https://graph.microsoft.com/

När du skapar en konfidentiell klient med klienthemligheter är parameters.json konfigurationsfilen i Python-daemonexemplet följande:

{
  "authority": "https://login.microsoftonline.com/<your_tenant_id>",
  "client_id": "your_client_id",
  "scope": [ "https://graph.microsoft.com/.default" ],
  "secret": "The secret generated by Azure AD during your confidential app registration",
  "endpoint": "https://graph.microsoft.com/v1.0/users"
}

När du skapar en konfidentiell klient med certifikat är parameters.json-konfigurationsfilen i Python-daemonexemplet följande:

{
  "authority": "https://login.microsoftonline.com/<your_tenant_id>",
  "client_id": "your_client_id",
  "scope": [ "https://graph.microsoft.com/.default" ],
  "thumbprint": "790E... The thumbprint generated by Azure AD when you upload your public cert",
  "private_key_file": "server.pem",
  "endpoint": "https://graph.microsoft.com/v1.0/users"
}

Här är ett exempel på hur du definierar konfigurationen i en appsettings.json-fil . Det här exemplet är hämtat från daemonkodexemplet för .NET-konsolen på GitHub.

{
  "Instance": "https://login.microsoftonline.com/{0}",
  "Tenant": "[Enter here the tenantID or domain name for your Azure AD tenant]",
  "ClientId": "[Enter here the ClientId for your application]",
  "ClientSecret": "[Enter here a client secret for your application]",
  "CertificateName": "[Or instead of client secret: Enter here the name of a certificate (from the user cert store) as registered with your application]"
}

Du anger antingen en ClientSecret eller en CertificateName. De här inställningarna är exklusiva.

Instansiera MSAL-programmet

Om du vill instansiera MSAL-programmet lägger du till, refererar till eller importerar MSAL-paketet (beroende på språk).

Konstruktionen skiljer sig beroende på om du använder klienthemligheter eller certifikat (eller, som ett avancerat scenario, signerade intyg).

Referera till paketet

Referera till MSAL-paketet i programkoden.

Lägg till NuGet-paketet Microsoft.Identity.Web.TokenAcquisition i ditt program. Om du vill anropa Microsoft Graph kan du också lägga till paketet Microsoft.Identity.Web.GraphServiceClient . Projektet kan vara följande. Den appsettings.json filen måste kopieras till utdatakatalogen.

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net7.0</TargetFramework>
    <RootNamespace>daemon_console</RootNamespace>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.Identity.Web.GraphServiceClient" Version="2.12.2" />
  </ItemGroup>

  <ItemGroup>
    <None Update="appsettings.json">
      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
    </None>
  </ItemGroup>
</Project>

I filen Program.cs lägger du till ett using direktiv i koden för att referera till Microsoft.Identity.Web.

using Microsoft.Identity.Abstractions;
using Microsoft.Identity.Web;

import com.microsoft.aad.msal4j.ClientCredentialFactory;
import com.microsoft.aad.msal4j.ClientCredentialParameters;
import com.microsoft.aad.msal4j.ConfidentialClientApplication;
import com.microsoft.aad.msal4j.IAuthenticationResult;
import com.microsoft.aad.msal4j.IClientCredential;
import com.microsoft.aad.msal4j.MsalException;
import com.microsoft.aad.msal4j.SilentParameters;

Installera paketen genom att köra npm install i mappen där package.json filen finns. Importera msal-node sedan paketet:

const msal = require('@azure/msal-node');

import msal
import json
import sys
import logging

Lägg till NuGet-paketet Microsoft.Identity.Client i ditt program och lägg sedan till ett using direktiv i koden för att referera till det.

I MSAL.NET representeras det konfidentiella klientprogrammet av IConfidentialClientApplication gränssnittet.

using Microsoft.Identity.Client;
IConfidentialClientApplication app;

Instansiera det konfidentiella klientprogrammet med en klienthemlighet

Här är koden för att instansiera det konfidentiella klientprogrammet med en klienthemlighet:

   class Program
    {
        static async Task Main(string[] _)
        {
            // Get the Token acquirer factory instance. By default it reads an appsettings.json
            // file if it exists in the same folder as the app (make sure that the 
            // "Copy to Output Directory" property of the appsettings.json file is "Copy if newer").
            TokenAcquirerFactory tokenAcquirerFactory = TokenAcquirerFactory.GetDefaultInstance();

            // Configure the application options to be read from the configuration
            // and add the services you need (Graph, token cache)
            IServiceCollection services = tokenAcquirerFactory.Services;
            services.AddMicrosoftGraph();
            // By default, you get an in-memory token cache.
            // For more token cache serialization options, see https://aka.ms/msal-net-token-cache-serialization

            // Resolve the dependency injection.
            var serviceProvider = tokenAcquirerFactory.Build();

            // ...
        }
    }

Konfigurationen läse från appsettings.json:

IClientCredential credential = ClientCredentialFactory.createFromSecret(CLIENT_SECRET);

ConfidentialClientApplication cca =
        ConfidentialClientApplication
                .builder(CLIENT_ID, credential)
                .authority(AUTHORITY)
                .build();


const msalConfig = {
  auth: {
    clientId: process.env.CLIENT_ID,
    authority: process.env.AAD_ENDPOINT + process.env.TENANT_ID,
    clientSecret: process.env.CLIENT_SECRET,
  }
};

const apiConfig = {
  uri: process.env.GRAPH_ENDPOINT + 'v1.0/users',
};

const tokenRequest = {
  scopes: [process.env.GRAPH_ENDPOINT + '.default'],
};

const cca = new msal.ConfidentialClientApplication(msalConfig);

# Pass the parameters.json file as an argument to this Python script. E.g.: python your_py_file.py parameters.json
config = json.load(open(sys.argv[1]))

# Create a preferably long-lived app instance that maintains a token cache.
app = msal.ConfidentialClientApplication(
    config["client_id"], authority=config["authority"],
    client_credential=config["secret"],
    # token_cache=...  # Default cache is in memory only.
                       # You can learn how to use SerializableTokenCache from
                       # https://msal-python.rtfd.io/en/latest/#msal.SerializableTokenCache
    )

app = ConfidentialClientApplicationBuilder.Create(config.ClientId)
           .WithClientSecret(config.ClientSecret)
           .WithAuthority(new Uri(config.Authority))
           .Build();

Authority är en sammanlänkning av molninstansen och klientorganisations-ID:t, till exempel https://login.microsoftonline.com/contoso.onmicrosoft.com eller https://login.microsoftonline.com/aaaabbbb-0000-cccc-1111-dddd2222eeee. I den appsettings.json fil som visas i avsnittet Konfigurationsfil representeras instansen Instance och klientorganisationen av värdena och Tenant .

I kodexemplet som föregående kodfragment hämtades från Authority är en egenskap i klassen AuthenticationConfig och definieras som sådan:

/// <summary>
/// URL of the authority
/// </summary>
public string Authority
{
    get
    {
        return String.Format(CultureInfo.InvariantCulture, Instance, Tenant);
    }
}

Instansiera det konfidentiella klientprogrammet med ett klientcertifikat

Här är koden för att skapa ett program med ett certifikat:

Själva koden är exakt densamma. Certifikatet beskrivs i konfigurationen. Det finns många sätt att hämta certifikatet. Mer information finns i https://aka.ms/ms-id-web-certificates. Så här gör du för att hämta certifikatet från KeyVault. Microsoft-identitet delegerar till Azure Identitys DefaultAzureCredential och använde hanterad identitet när den är tillgänglig för åtkomst till certifikatet från KeyVault. Du kan felsöka ditt program lokalt eftersom det sedan använder dina autentiseringsuppgifter för utvecklare.

  "ClientCredentials": [
      {
        "SourceType": "KeyVault",
        "KeyVaultUrl": "https://yourKeyVaultUrl.vault.azure.net",
        "KeyVaultCertificateName": "NameOfYourCertificate"
      }

I MSAL Java finns det två byggare som instansierar det konfidentiella klientprogrammet med certifikat:


InputStream pkcs12Certificate = ... ; /* Containing PCKS12-formatted certificate*/
string certificatePassword = ... ;    /* Contains the password to access the certificate */

IClientCredential credential = ClientCredentialFactory.createFromCertificate(pkcs12Certificate, certificatePassword);

ConfidentialClientApplication cca =
        ConfidentialClientApplication
                .builder(CLIENT_ID, credential)
                .authority(AUTHORITY)
                .build();

eller

PrivateKey key = getPrivateKey(); /* RSA private key to sign the assertion */
X509Certificate publicCertificate = getPublicCertificate(); /* x509 public certificate used as a thumbprint */

IClientCredential credential = ClientCredentialFactory.createFromCertificate(key, publicCertificate);

ConfidentialClientApplication cca =
        ConfidentialClientApplication
                .builder(CLIENT_ID, credential)
                .authority(AUTHORITY)
                .build();


const config = {
    auth: {
        clientId: process.env.CLIENT_ID,
        authority: process.env.AAD_ENDPOINT + process.env.TENANT_ID,
        clientCertificate: {
            thumbprint:  process.env.CERTIFICATE_THUMBPRINT, // a 40-digit hexadecimal string
            privateKey:  process.env.CERTIFICATE_PRIVATE_KEY,
        }
    }
};

// Create an MSAL application object
const cca = new msal.ConfidentialClientApplication(config);

Mer information finns i Använda certifikatautentiseringsuppgifter med MSAL Node.

# Pass the parameters.json file as an argument to this Python script. E.g.: python your_py_file.py parameters.json
config = json.load(open(sys.argv[1]))

# Create a preferably long-lived app instance that maintains a token cache.
app = msal.ConfidentialClientApplication(
    config["client_id"], authority=config["authority"],
    client_credential={"thumbprint": config["thumbprint"], "private_key": open(config['private_key_file']).read()},
    # token_cache=...  # Default cache is in memory only.
                       # You can learn how to use SerializableTokenCache from
                       # https://msal-python.rtfd.io/en/latest/#msal.SerializableTokenCache
    )

X509Certificate2 certificate = ReadCertificate(config.CertificateName);
app = ConfidentialClientApplicationBuilder.Create(config.ClientId)
    .WithCertificate(certificate)
    .WithAuthority(new Uri(config.Authority))
    .Build();

Avancerat scenario: Instansiera det konfidentiella klientprogrammet med klientkontroller

Förutom att använda en klienthemlighet eller ett certifikat kan även konfidentiella klientprogram bevisa sin identitet med hjälp av klientkontroller. Mer information finns i CredentialDescription .

IClientCredential credential = ClientCredentialFactory.createFromClientAssertion(assertion);

ConfidentialClientApplication cca =
        ConfidentialClientApplication
                .builder(CLIENT_ID, credential)
                .authority(AUTHORITY)
                .build();

const clientConfig = {
    auth: {
        clientId: process.env.CLIENT_ID,
        authority: process.env.AAD_ENDPOINT + process.env.TENANT_ID,
        clientAssertion:  process.env.CLIENT_ASSERTION
    }
};
const cca = new msal.ConfidentialClientApplication(clientConfig);

Mer information finns i Initiera objektet ConfidentialClientApplication.

I MSAL Python kan du ange klientanspråk med hjälp av de anspråk som ska signeras av den här ConfidentialClientApplicationprivata nyckeln.

# Pass the parameters.json file as an argument to this Python script. E.g.: python your_py_file.py parameters.json
config = json.load(open(sys.argv[1]))

# Create a preferably long-lived app instance that maintains a token cache.
app = msal.ConfidentialClientApplication(
    config["client_id"], authority=config["authority"],
    client_credential={"thumbprint": config["thumbprint"], "private_key": open(config['private_key_file']).read()},
    client_claims = {"client_ip": "x.x.x.x"}
    # token_cache=...  # Default cache is in memory only.
                       # You can learn how to use SerializableTokenCache from
                       # https://msal-python.rtfd.io/en/latest/#msal.SerializableTokenCache
    )

Mer information finns i REFERENSdokumentationen för MSAL Python för ConfidentialClientApplication.

I stället för en klienthemlighet eller ett certifikat kan det konfidentiella klientprogrammet också bevisa sin identitet med hjälp av klientkontroller.

MSAL.NET har två metoder för att tillhandahålla signerade intyg till den konfidentiella klientappen:

.WithClientAssertion()
.WithClientClaims()

När du använder WithClientAssertionanger du en signerad JWT. Det här avancerade scenariot beskrivs i Klientkontroller.

string signedClientAssertion = ComputeAssertion();
app = ConfidentialClientApplicationBuilder.Create(config.ClientId)
                                          .WithClientAssertion(signedClientAssertion)
                                          .Build();

När du använder WithClientClaimsskapar MSAL.NET en signerad försäkran som innehåller de anspråk som förväntas av Microsoft Entra-ID,plus ytterligare klientanspråk som du vill skicka. Den här koden visar hur du gör så här:

string ipAddress = "192.168.1.2";
var claims = new Dictionary<string, string> { { "client_ip", ipAddress } };
X509Certificate2 certificate = ReadCertificate(config.CertificateName);
app = ConfidentialClientApplicationBuilder.Create(config.ClientId)
                                          .WithAuthority(new Uri(config.Authority))
                                          .WithClientClaims(certificate, claims)
                                          .Build();

Mer information finns i Klientkontroller.

Nästa steg

Gå vidare till nästa artikel i det här scenariot, Hämta en token för appen.

Dela via