Verwenden der OAuth-Authentifizierung mit Microsoft Dataverse

OAuth 2.0 ist das branchenübliche Protokoll für die Autorisierung. Nachdem Anwendungsbenutzenden Anmeldeinformationen zur Authentifizierung angegeben haben, bestimmt OAuth, ob sie zum Zugriff auf die Ressourcen berechtigt sind.

Client-Anwendungen müssen die Verwendung von OAuth für den Datenzugriff über die Web-API unterstützen. OAuth ermöglicht eine Zwei-Faktor-Authentifizierung (2FA) oder eine zertifikatsbasierte Authentifizierung für Server-zu-Server-Anwendungsszenarien.

OAuth benötigt für die Authentifizierung einen Identitätsanbieter. Für Dataverse ist der Identitätsanbieter Microsoft Entra ID. Um sich mit einem Geschäfts-, Schul- oder Unikonto von Microsoft zu authentifizieren, nutzen Sie die Microsoft Authentication Library (MSAL).

App-Registrierung

Wenn Sie sich über OAuth verbinden, müssen Sie zunächst eine Anwendung in Ihrem Microsoft Entra ID-Mandant registrieren. Wie Sie Ihre App registrieren sollten, hängt von der Art der App ab, die Sie erstellen möchten.

Beginnen Sie in allen Fällen mit den grundlegenden Schritten zur Registrierung einer App, wie im Artikel beschrieben: Schnellstart: Eine Anwendung bei der Microsoft Identity Platform registrieren. Spezifische Anweisungen zu Dataverse finden Sie unter Walkthrough: Register an app with Microsoft Entra ID.

Die Entscheidungen, die Sie in diesem Schritt treffen müssen, hängen hauptsächlich von der Auswahl des Anwendungstyps ab (siehe nächster Abschnitt).

Arten der App-Registrierung

Wenn Sie eine App mit Microsoft Entra ID registrieren, ist eine der Entscheidungen, die Sie treffen müssen, der Anwendungstyp. Es gibt zwei Arten von Anwendungen, die Sie registrieren können:

Wenn Sie Web-App/API auswählen, müssen Sie eine Anmelde-URL angeben, die die URL ist, unter der Microsoft Entra ID die Authentifizierungsantwort sendet, einschließlich eines Token, wenn die Authentifizierung erfolgreich war. Während Sie eine App entwickeln, lautet diese URL in der Regel auf https://localhost/appname:[port], sodass Sie Ihre App lokal entwickeln und debuggen können. Wenn Sie Ihre App veröffentlichen, müssen Sie diesen Wert auf die veröffentlichte URL der App ändern.

Wenn Sie Native wählen, müssen Sie eine Umleitungs-URI bereitstellen. Diese URL ist eine eindeutige Kennung, an die Microsoft Entra ID den Benutzer-Agenten in einer OAuth 2.0-Anfrage weiterleitet. Diese URL ist normalerweise ein Wert, der so formatiert ist: app://<guid>.

Zugriff auf Dataverse geben

Wenn Ihre Anwendung ein Client ist, der es dem authentifizierten Benutzenden ermöglicht, Vorgänge auszuführen, müssen Sie die Anwendung so konfigurieren, dass die Access Dynamics 365 als Berechtigung von Organisationsbenutzenden vergeben wird.

Konkrete Schritte zum Festlegen von Berechtigungen finden Sie unter Registrieren einer App bei Microsoft Entra ID.

Wenn Ihre Anwendung die Server-zu-Server-(S2S-)Authentifizierung verwendet, ist dieser Schritt nicht erforderlich. Für diese Konfiguration ist ein bestimmter Systembenutzer und die Vorgänge erforderlich, die von diesem Benutzerkonto ausgeführt werden, und nicht für jeden Benutzer, der authentifiziert werden muss.

Verwenden von geheimen Clientschlüsseln und Zertifikaten

Für Server-zu-Server-Szenarien gibt es kein interaktives Benutzerkonto, das authentifiziert werden soll. In diesen Fällen müssen Sie einige Mittel bereitstellen, um zu bestätigen, dass die Anwendung vertrauenswürdig ist. Die Bestätigung erfolgt mithilfe von geheimen Clientschlüsseln oder Zertifikaten.

Für Apps, die mit dem Applikationstyp Web App /API registriert sind, können Sie Geheimnisse konfigurieren. Diese geheimen Schlüssel werden mithilfe des Schlüsselbereichs unter API Access in den Einstellungen für die App-Registrierung festgelegt.

Für beide Anwendungsarten können Sie ein Zertifikat hochladen.

Weitere Informationen: Als App verbinden

Authentifizierungsbibliotheken verwenden, um eine Verbindung herzustellen

Verwenden Sie eine der von Microsoft unterstützten Microsoft Entra ID-Authentifizierungs-Clientbibliotheken, um eine Verbindung zu Dataverse herzustellen, z. B. Microsoft Authentication Library (MSAL). Diese Bibliothek ist für verschiedene Plattformen verfügbar, wie in den bereitgestellten Links beschrieben:

Ein Codebeispiel, das die Verwendung von MSAL-Bibliotheken für die Authentifizierung mit Dataverse demonstriert, finden Sie unter Schnellstartbeispiel.

.NET-Clientbibliotheken

Dataverse unterstützt die Anwendungsauthentifizierung mit dem Web-API-Endpunkt unter Verwendung des OAuth 2.0-Protokolls. Verwenden Sie für Ihre benutzerdefinierten .NET-Anwendungen MSAL für die Anwendungsauthentifizierung mit dem Web-API-Endpunkt.

Dataverse SDK für .NET enthält Clientklassen CrmServiceClient und ServiceClient, um Authentifizierung zu behandeln. Die CrmServiceClient-Klasse verwendet derzeit ADAL für die Authentifizierung während ServiceClient MSAL verwendet. Durch das Schreiben Ihres Anwendungscodes zur Verwendung dieser Clients entfällt die Notwendigkeit, die Authentifizierung direkt zu verwalten. Beide Clients arbeiten mit den SDK- und Web-API-Endpunkten.

Verwenden Sie den AccessToken für Ihre Anfragen.

Der Sinn der Verwendung der Authentifizierungsbibliotheken besteht darin, ein Zugriffstoken zu erhalten, das Sie in Ihre Anfragen aufnehmen können. Das Abrufen des Tokens erfordert nur ein paar Zeilen Code und nur ein paar weitere Zeilen, um einen HttpClient zur Ausführung einer Anfrage zu konfigurieren.

Ein einfaches Beispiel

Das folgende Beispiel ist die Mindestmenge an Code, der zum Ausführen einer einzelnen Web-API-Anforderung erforderlich ist, aber nicht der empfohlene Ansatz. Der Beispielcode verwendet die MSAL-Bibliothek und stammt aus dem Schnellstartbeispiel .

string resource = "https://contoso.api.crm.dynamics.com";
var clientId = "51f81489-12ee-4a9e-aaae-a2591f45987d";
var redirectUri = "http://localhost"; // Loopback for the interactive login.

// MSAL authentication
var authBuilder = PublicClientApplicationBuilder.Create(clientId)
    .WithAuthority(AadAuthorityAudience.AzureAdMultipleOrgs)
    .WithRedirectUri(redirectUri)
    .Build();
var scope = resource + "/user_impersonation";
string[] scopes = { scope };

AuthenticationResult token =
    authBuilder.AcquireTokenInteractive(scopes).ExecuteAsync().Result;

// Set up the HTTP client
var client = new HttpClient
{
    BaseAddress = new Uri(resource + "/api/data/v9.2/"),
    Timeout = new TimeSpan(0, 2, 0)  // Standard two minute timeout.
};

HttpRequestHeaders headers = client.DefaultRequestHeaders;
headers.Authorization = new AuthenticationHeaderValue("Bearer", token.AccessToken);
headers.Add("OData-MaxVersion", "4.0");
headers.Add("OData-Version", "4.0");
headers.Accept.Add(
    new MediaTypeWithQualityHeaderValue("application/json"));

// Web API call
var response = client.GetAsync("WhoAmI").Result;

Dieser einfache Ansatz ist kein gutes Muster zum Nachahmen, da die token in etwa einer Stunde abläuft. MSAL-Bibliotheken zwischenspeichern das Token für Sie und aktualisieren es jedes Mal, wenn die AcquireTokenInteractive Methode aufgerufen wird. In diesem einfachen Beispiel wird der Token jedoch nur einmal erworben.

Beispiel zur Demonstration eines delegierten Meldungshandlers

Der empfohlene Ansatz besteht darin, eine Klasse zu implementieren, die von der Klasse "willDelegatingHandler" abgeleitet ist und an den Konstruktor des HttpClient übergeben wird. Mit diesem Handler können Sie die HttpClient.SendAsync -Methode außer Kraft setzen, sodass das Zugriffstoken von den AcquireToken* Methodenaufrufen mit jeder anforderung aktualisiert wird, die vom Http-Client gesendet wird.

Der folgende Code ist ein Beispiel für eine kundenspezifische Klasse, die von DelegatingHandler abgeleitet ist. Dieser Code stammt aus dem Erweiterten Schnellstartbeispiel , das die MSAL-Authentifizierungsbibliothek verwendet.

class OAuthMessageHandler : DelegatingHandler
{
    private AuthenticationHeaderValue authHeader;
    public OAuthMessageHandler(string serviceUrl, string clientId, string redirectUrl, string username, string password,
            HttpMessageHandler innerHandler)
        : base(innerHandler)
    {
        string apiVersion = "9.2";
        string webApiUrl = $"{serviceUrl}/api/data/v{apiVersion}/";
        var authBuilder = PublicClientApplicationBuilder.Create(clientId)
                        .WithAuthority(AadAuthorityAudience.AzureAdMultipleOrgs)
                        .WithRedirectUri(redirectUrl)
                        .Build();
        var scope = serviceUrl + "/user_impersonation";
        string[] scopes = { scope };
        // First try to get an authentication token from the cache using a hint.
        AuthenticationResult authBuilderResult=null;
        try
        {
            authBuilderResult = authBuilder.AcquireTokenSilent(scopes, username)
               .ExecuteAsync().Result;
        }
        catch (Exception ex)
        {
            System.Diagnostics.Debug.WriteLine(
                $"Error acquiring auth token from cache:{System.Environment.NewLine}{ex}");
            // Token cache request failed, so request a new token.
            try
            {
                if (username != string.Empty && password != string.Empty)
                {
                    // Request a token based on username/password credentials.
                    authBuilderResult = authBuilder.AcquireTokenByUsernamePassword(scopes, username, password)
                                .ExecuteAsync().Result;
                }
                else
                {
                    // Prompt the user for credentials and get the token.
                    authBuilderResult = authBuilder.AcquireTokenInteractive(scopes)
                                .ExecuteAsync().Result;
                }
            }
            catch (Exception msalex)
            {
                System.Diagnostics.Debug.WriteLine(
                    $"Error acquiring auth token with user credentials:{System.Environment.NewLine}{msalex}");
                throw;
            }
        }
        //Note that an Microsoft Entra ID access token has finite lifetime, default expiration is 60 minutes.
        authHeader = new AuthenticationHeaderValue("Bearer", authBuilderResult.AccessToken);
    }

    protected override Task<HttpResponseMessage> SendAsync(
              HttpRequestMessage request, System.Threading.CancellationToken cancellationToken)
    {
        request.Headers.Authorization = authHeader;
        return base.SendAsync(request, cancellationToken);
    }
}

Bei Verwendung dieser OAuthMessageHandler Klasse würde die einfache Main Methode wie folgt aussehen.

class Program
{
    static void Main(string[] args)
    {
        try
        {
            //Get configuration data from App.config connectionStrings
            string connectionString = ConfigurationManager.ConnectionStrings["Connect"].ConnectionString;

            using (HttpClient client = SampleHelpers.GetHttpClient(connectionString, SampleHelpers.clientId,
                SampleHelpers.redirectUrl))
            {
                // Use the WhoAmI function
                var response = client.GetAsync("WhoAmI").Result;

                if (response.IsSuccessStatusCode)
                {
                    //Get the response content and parse it.
                    JObject body = JObject.Parse(response.Content.ReadAsStringAsync().Result);
                    Guid userId = (Guid)body["UserId"];
                    Console.WriteLine("Your UserId is {0}", userId);
                }
                else
                {
                    Console.WriteLine("The request failed with a status of '{0}'",
                                response.ReasonPhrase);
                }
                Console.WriteLine("Press any key to exit.");
                Console.ReadLine();
            }
        }
        catch (Exception ex)
        {
            SampleHelpers.DisplayException(ex);
            Console.WriteLine("Press any key to exit.");
            Console.ReadLine();
        }
    }
}

Lesen Sie die folgenden wichtigen Informationen zur Verwendung einer Verbindungszeichenfolge oder zur Authentifizierung mit Benutzername/Kennwort im Anwendungscode.

Die Konfigurationszeichenfolgenwerte wurden in eine App.config Dateiverbindungszeichenfolge verschoben, und der Http-Client wird in der GetHttpClient Methode konfiguriert.

public static HttpClient GetHttpClient(string connectionString, string clientId, string redirectUrl, string version = "v9.2")
{
    string url = GetParameterValueFromConnectionString(connectionString, "Url");
    string username = GetParameterValueFromConnectionString(connectionString, "Username");
    string password = GetParameterValueFromConnectionString(connectionString, "Password");
    try
    {
        HttpMessageHandler messageHandler = new OAuthMessageHandler(url, clientId, redirectUrl, username, password,
                        new HttpClientHandler());

        HttpClient httpClient = new HttpClient(messageHandler)
        {
            BaseAddress = new Uri(string.Format("{0}/api/data/{1}/", url, version)),

            Timeout = new TimeSpan(0, 2, 0)  //2 minutes
        };

        return httpClient;
    }
    catch (Exception)
    {
        throw;
    }
}

Weitere Informationen zum vollständigen Coden finden Sie im Beispiel für den verbesserten Schnellstart.

Obwohl in diesem Beispiel HttpClient anstelle der überschriebenen SendAsync verwendet wird, gilt der gleiche Codefluss für jede der HttpClient Methoden, die eine Anforderung senden.

Als App verbinden

Einige Apps, die Sie erstellen, sind nicht für die interaktive Ausführung durch einen Benutzer vorgesehen. Beispielsweise können Sie eine Web-Client-Anwendung erstellen, die Operationen mit Dataverse-Daten ausführen kann, oder eine Konsolenanwendung, die eine geplante Aufgabe in irgendeiner Form ausführt.

Während Sie diese Szenarien mit Anmeldeinformationen für einen normalen Benutzer erreichen könnten, müsste dieses Benutzerkonto eine kostenpflichtige Lizenz verwenden. Dieser Ansatz wird nicht empfohlen.

In diesen Fällen können Sie einen speziellen Anwendungsbenutzer erstellen, der an eine registrierte Microsoft Entra-ID gebunden ist. Verwenden Sie als Nächstes entweder einen schlüsselschlüssel, der für die App konfiguriert ist, oder laden Sie ein X.509-Zertifikat hoch. Ein weiterer Vorteil dieses Ansatzes ist, dass er keine kostenpflichtige Lizenz verbraucht.

Anforderungen für die Verbindung als App

Um sich als App zu verbinden, benötigen Sie:

• Eine registrierte App
• Einen Dataverse-Benutzer, der an die registrierte App gebunden ist
• Verbinden Sie sich entweder über das Anwendungsgeheimnis oder über einen Zertifikat-Fingerabdruck.

Registrieren Sie die App

Wenn Sie eine App registrieren, führen Sie viele der gleichen Schritte aus, die in walkthrough beschrieben werden: Registrieren einer App mit Microsoft Entra ID mit den folgenden Ausnahmen:

• Sie müssen die Berechtigung für den Zugriff auf Dynamics 365 als Organisationsbenutzer nicht erteilen.

  Diese Anwendung ist an ein bestimmtes Benutzerkonto gebunden.

• Sie müssen ein Geheimnis für die App-Registrierung konfigurieren ODER ein Public-Key-Zertifikat hochladen.

Sie können Anmeldeinformationen in Ihrer App-Registrierung unter Verwalten>Zertifikate & Geheimnisse erstellen oder anzeigen.

So fügen Sie ein Zertifikat (öffentlicher Schlüssel) hinzu:

1. Wählen Sie auf der Registerkarte Zertifikate die Option Zertifikat hochladen aus.
2. Wählen Sie die Datei aus, die Sie hochladen möchten. Es muss einer der folgenden Dateitypen sein: .cer,.pem,.crt.
3. Geben Sie eine Beschreibungen an.
4. Wählen Sie Hinzufügen aus.

So fügen Sie einen geheimen Clientschlüssel (Anwendungskennwort) hinzu:

1. Fügen Sie auf der Registerkarte Geheime Clientschlüssel eine Beschreibung für Ihren geheimen Clientschlüssel hinzu.
2. Wählen Sie einen Ablaufzeitraum aus.
3. Wählen Sie Hinzufügen aus.

Weitere Informationen: Anmeldeinformationen hinzufügen

Dataverse-Benutzerkonto, das an die registrierte App gebunden ist

Als Erstes müssen Sie eine benutzerdefinierte Sicherheitsrolle erstellen, die definiert, über welche Zugriffsrechte und Berechtigungen dieses Kontos innerhalb der Dataverse-Organisation verfügt. Weitere Information finden Sie unter Erstellen oder Konfigurieren einer benutzerdefinierten Sicherheitsrolle

Nachdem Sie die benutzerdefinierte Sicherheitsrolle erstellt haben, müssen Sie das Benutzerkonto erstellen, das sie verwendet.

Manuelles Erstellen eines Dataverse-Anwendungsbenutzers

Die Vorgehensweise zum Erstellen eines Anwendungsbenutzers finden Sie im Artikel zur Power Platform-Administration: Anwendungsbenutzer erstellen.

Nach der Erstellung eines Anwendungsbenutzers ordnen Sie den Anwendungsbenutzer der angepassten Sicherheitsrolle zu, die Sie erstellt haben.

Verbindung über das Anwendungsgeheimnis herstellen

Wenn Sie eine Verbindung mit einem geheimen Clientschlüssel herstellen und den Microsoft.Xrm.Tooling.Connector.CrmServiceClient verwenden, können Sie ähnlichen Code wie hier gezeigt verwenden:

string SecretID = "00000000-0000-0000-0000-000000000000";
string AppID = "00001111-aaaa-2222-bbbb-3333cccc4444";
string InstanceUri = "https://yourorg.crm.dynamics.com";

string ConnectionStr = $@"AuthType=ClientSecret;
                        SkipDiscovery=true;url={InstanceUri};
                        Secret={SecretID};
                        ClientId={AppID};
                        RequireNewInstance=true";
using (ServiceClient svc = new ServiceClient(ConnectionStr))
{
    if (svc.IsReady)
    {
    //your code goes here
    }

}

Verbindung über einen Zertifikatsfingerabdruck herstellen

Wenn Sie eine Verbindung mit einem Zertifikat herstellen und das Microsoft.Xrm.Tooling.Connector.CrmServiceClient verwenden, können Sie ähnlichen Code wie hier gezeigt verwenden:

string CertThumbPrintId = "DC6C689022C905EA5F812B51F1574ED10F256FF6";
string AppID = "00001111-aaaa-2222-bbbb-3333cccc4444";
string InstanceUri = "https://yourorg.crm.dynamics.com";

string ConnectionStr = $@"AuthType=Certificate;
                        SkipDiscovery=true;url={InstanceUri};
                        thumbprint={CertThumbPrintId};
                        ClientId={AppID};
                        RequireNewInstance=true";
using (ServiceClient svc = new ServiceClient(ConnectionStr))
{
    if (svc.IsReady)
    {
    //your code goes here
    }

}

Siehe auch

Authentifizierung mit Microsoft Dataverse-Webdiensten
Authentifizierung von .NET Framework-Anwendungen
Übersicht über die Microsoft-Authentifizierungsbibliothek