Android-Konfigurationsdatei für die Microsoft-Authentifizierungsbibliothek

Artikel
04/10/2024

Die Microsoft-Authentifizierungsbibliothek (Microsoft Authentication Library, MSAL) wird mit einer JSON-Standardkonfigurationsdatei ausgeliefert, die Sie anpassen, um das Verhalten Ihrer öffentlichen Client-App zu definieren, z. B. als Standardautorität, die von Ihnen verwendeten Autoritäten usw.

Dieser Artikel soll Ihnen helfen, die verschiedenen Einstellungen in der Konfigurationsdatei zu verstehen, und es wird darin erläutert, wie Sie die Konfigurationsdatei zur Verwendung in Ihrer MSAL-basierten App angeben.

Konfigurationseinstellungen

Allgemeine Einstellungen

Eigenschaft	Datentyp	Erforderlich	Hinweise
`client_id`	String	Ja	Die Client-ID Ihrer App von der Seite für die Anwendungsregistrierung
`redirect_uri`	String	Ja	Der Umleitungs-URI Ihrer App von der Seite für die Anwendungsregistrierung
`broker_redirect_uri_registered`	Boolesch	Nein	Mögliche Werte: `true`, `false`
`authorities`	List<Authority>	Nein	Die Liste der von Ihrer App benötigten Autoritäten
`authorization_user_agent`	AuthorizationAgent (enum)	Nein	Mögliche Werte: `WEBVIEW`, `BROWSER`
`http`	HttpConfiguration	Nein	Konfigurieren Sie `HttpUrlConnection` `connect_timeout` und `read_timeout`.
`logging`	LoggingConfiguration	Nein	Gibt die Stufe des Protokollierungsdetails an. Optionale Konfigurationen umfassen: `pii_enabled`, die einen booleschen Wert annimmt, und `log_level`, die `ERROR`, `WARNING`, `INFO` oder `VERBOSE` annimmt.

client_id

Die Client-ID oder App-ID, die beim Registrieren Ihrer Anwendung erstellt wurde.

redirect_uri

Der Umleitungs-URI, den Sie beim Registrieren Ihrer Anwendung registriert haben. Wenn der Umleitungs-URI zu einer Broker-App gehört, lesen Sie Umleitungs-URI für öffentliche Client-Apps, um sicherzustellen, dass Sie das richtige Umleitungs-URI-Format für Ihre Broker-App verwenden.

broker_redirect_uri_registered

Wenn Sie die Brokerauthentifizierung verwenden möchten, muss die Eigenschaft broker_redirect_uri_registered auf true festgelegt werden. Wenn die Anwendung in einem Szenario mit Brokerauthentifizierung nicht das richtige Format für die Kommunikation mit dem Broker (wie unter Umleitungs-URI für öffentliche Client-Apps beschrieben) aufweist, überprüft die Anwendung Ihren Umleitungs-URI und löst eine Ausnahme aus, wenn sie gestartet wird.

authorities

Die Liste von Autoritäten, die Ihnen bekannt sind und von Ihnen als vertrauenswürdig eingestuft werden. Zusätzlich zu den hier aufgelisteten Autoritäten fragt die MSAL auch Microsoft ab, um eine Liste der Clouds und Autoritäten zu erhalten, die Microsoft bekannt sind. Geben Sie in dieser Liste von Autoritäten den Typ der Autorität und alle zusätzlichen optionalen Parameter an, z.B. "audience", die auf der Grundlage der Registrierung Ihrer App mit der Zielgruppe Ihrer App übereinstimmen sollten. Im Folgenden finden Sie eine Beispielliste von Autoritäten:

// Example AzureAD and Personal Microsoft Account
{
    "type": "AAD",
    "audience": {
        "type": "AzureADandPersonalMicrosoftAccount"
    },
    "default": true // Indicates that this is the default to use if not provided as part of the acquireToken call
},
// Example AzureAD My Organization
{
    "type": "AAD",
    "audience": {
        "type": "AzureADMyOrg",
        "tenant_id": "contoso.com" // Provide your specific tenant ID here
    }
},
// Example AzureAD Multiple Organizations
{
    "type": "AAD",
    "audience": {
        "type": "AzureADMultipleOrgs"
    }
},
//Example PersonalMicrosoftAccount
{
    "type": "AAD",
    "audience": {
        "type": "PersonalMicrosoftAccount"
    }
}

Zuordnen der Microsoft Entra-Autorität & -Zielgruppe zu Microsoft Identity Platform-Endpunkten

type	Zielgruppe	Mandanten-ID	Authority_Url	Resultierender Endpunkt	Hinweise
Microsoft Entra ID	AzureADandPersonalMicrosoftAccount			`https://login.microsoftonline.com/common`	`common` ist ein Mandantenalias für den Speicherort des Kontos. Beispielsweise ein bestimmter Microsoft Entra Mandant oder das Microsoft-Kontosystem.
Microsoft Entra ID	AzureADMyOrg	contoso.com		`https://login.microsoftonline.com/contoso.com`	Nur Konten, die in „contoso.com“ vorhanden sind, können ein Token abrufen. Jede beliebige überprüfte Domäne oder die Mandanten-GUID kann als Mandanten-ID verwendet werden.
Microsoft Entra ID	AzureADMultipleOrgs			`https://login.microsoftonline.com/organizations`	Mit diesem Endpunkt können nur Microsoft Entra-Konten verwendet werden. Microsoft-Konten können Mitglieder von Organisationen sein. Wenn Sie ein Token über ein Microsoft-Konto für eine Ressource in einer Organisation abrufen möchten, geben Sie den Organisationsmandanten an, dessen Token Sie verwenden möchten.
Microsoft Entra ID	PersonalMicrosoftAccount			`https://login.microsoftonline.com/consumers`	Dieser Endpunkt kann nur von Microsoft-Konten verwendet werden.
B2C			Anzeigen des resultierenden Endpunkts	`https://login.microsoftonline.com/tfp/contoso.onmicrosoft.com/B2C_1_SISOPolicy/`	Nur Konten, die im Mandanten „contoso.onmicrosoft.com“ vorhanden sind, können ein Token abrufen. In diesem Beispiel ist die B2C-Richtlinie Teil des Autoritäts-URL-Pfads.

Hinweis

Die Autoritätsüberprüfung kann in der MSAL nicht aktiviert und deaktiviert werden. Autoritäten sind Ihnen entweder als Entwickler bekannt, wie über die Konfiguration festgelegt wurde, oder sie sind Microsoft über Metadaten bekannt. Wenn die MSAL eine Anforderung für ein Token an eine unbekannte Autorität erhält, wird eine MsalClientException vom Typ UnknownAuthority ausgegeben. Die Brokerauthentifizierung funktioniert nicht für Azure AD B2C.

Eigenschaften von Autoritäten

Eigenschaft	Datentyp	Erforderlich	Hinweise
`type`	String	Ja	Entspricht der Zielgruppe oder dem Kontotyp Ihrer App-Ziele. Mögliche Werte: `AAD`, `B2C`
`audience`	Object	Nein	Gilt nur, wenn „type“=`AAD` ist. Gibt die Identität ihrer App-Ziele an. Verwenden Sie den Wert aus Ihrer App-Registrierung.
`authority_url`	String	Ja	Nur erforderlich, wenn „type“=`B2C` ist. Optional für type=`AAD`. Gibt die Autoritäts-URL oder Richtlinie an, die Ihre App verwenden sollte.
`default`	boolean	Ja	Wenn eine oder mehrere Autoritäten angegeben werden, ist ein einzelnes `"default":true` erforderlich.

Eigenschaften der Zielgruppe

Eigenschaft	Datentyp	Erforderlich	Hinweise
`type`	String	Ja	Gibt die Zielgruppe an, auf die Ihre App abzielen möchte. Mögliche Werte: `AzureADandPersonalMicrosoftAccount`, `PersonalMicrosoftAccount`, `AzureADMultipleOrgs`, `AzureADMyOrg`
`tenant_id`	String	Ja	Nur erforderlich, wenn `"type":"AzureADMyOrg"` ist. Optional bei anderen `type`-Werten. Dies kann eine Mandantendomäne (z. B. `contoso.com`) oder eine Mandanten-ID sein (z. B. `aaaabbbb-0000-cccc-1111-dddd2222eeee`)

authorization_user_agent

Gibt an, ob eine eingebettete Webansicht oder der Standardbrowser auf dem Gerät verwendet werden soll, wenn ein Konto angemeldet oder der Zugriff auf eine Ressource autorisiert wird.

Mögliche Werte:

WEBVIEW: Verwendet die eingebettete Webansicht.
BROWSER: Verwendet den Standardbrowser auf dem Gerät.

multiple_clouds_supported

Geben Sie bei Clients, die mehrere nationale Clouds unterstützen, true an. Die Microsoft Identity Platform leitet dann während der Autorisierung und der Einlösung von Token automatisch zur richtigen nationalen Cloud um. Sie können die nationale Cloud des angemeldeten Kontos ermitteln, indem Sie die dem AuthenticationResult zugeordnete Autorität untersuchen. Beachten Sie, dass das AuthenticationResult nicht die für die nationale Cloud spezifische Endpunktadresse der Ressource liefert, für die Sie ein Token anfordern.

broker_redirect_uri_registered

Ein boolescher Wert, der angibt, ob Sie einen mit Microsoft-Identitätsbroker kompatiblen Umleitungs-URI für den Broker verwenden. Legen Sie den Wert auf false fest, wenn Sie den Broker nicht innerhalb Ihrer App verwenden möchten.

Wenn Sie die Microsoft Entra-Autorität verwenden, bei der die Zielgruppe auf "MicrosoftPersonalAccount" festgelegt wurde, wird der Broker nicht verwendet.

http

Konfigurieren Sie globale Einstellungen für HTTP-Zeitlimits, z.B.:

Eigenschaft	Datentyp	Erforderlich	Notizen
`connect_timeout`	INT	Nein	Zeit in Millisekunden
`read_timeout`	INT	Nein	Zeit in Millisekunden

logging

Die folgenden globalen Einstellungen gelten für die Protokollierung:

Eigenschaft	Datentyp	Erforderlich	Notizen
`pii_enabled`	boolean	Nein	Gibt an, ob persönliche Daten ausgegeben werden sollen.
`log_level`	Zeichenfolge	Nein	Gibt an, welche Protokollmeldungen ausgegeben werden sollen. Die unterstützten Protokollierungsebenen sind beispielsweise `ERROR`, `WARNING`, `INFO` und `VERBOSE`.
`logcat_enabled`	boolean	Nein	Gibt an, ob die Ausgabe an die Protokollkategorie zusätzlich zur Protokollierungsschnittstelle ausgegeben werden soll.

account_mode

Gibt an, wie viele Konten in Ihrer App gleichzeitig verwendet werden können. Mögliche Werte:

MULTIPLE (Standard)
SINGLE

Das Erstellen einer PublicClientApplication unter Verwendung eines Kontomodus, der dieser Einstellung nicht entspricht, führt zu einer Ausnahme.

Weitere Informationen zu den Unterschieden zwischen einzelnen und mehreren Konten finden Sie unter Apps für einzelne und mehrere Konten.

browser_safelist

Eine Zulassungsliste der mit der MSAL kompatiblen Browser. Diese Browser verarbeiten ordnungsgemäß Umleitungen an benutzerdefinierte Absichten. Sie können sie dieser Liste hinzufügen. Der Standardwert wird in der unten gezeigten Standardkonfiguration bereitgestellt. ``

Die MSAL-Standardkonfigurationsdatei

Die MSAL-Standardkonfiguration, die mit MSAL ausgeliefert wird, ist unten dargestellt. Die neueste Version können Sie auf GitHub sehen.

Diese Konfiguration wird durch von Ihnen bereitgestellte Werte ergänzt. Die von Ihnen bereitgestellten Werte setzen die Standardwerte außer Kraft.

{
  "authorities": [
    {
      "type": "AAD",
      "audience": {
        "type": "AzureADandPersonalMicrosoftAccount"
      },
      "default": true
    }
  ],
  "authorization_user_agent": "DEFAULT",
  "multiple_clouds_supported": false,
  "broker_redirect_uri_registered": false,
  "http": {
    "connect_timeout": 10000,
    "read_timeout": 30000
  },
  "logging": {
    "pii_enabled": false,
    "log_level": "WARNING",
    "logcat_enabled": false
  },
  "shared_device_mode_supported": false,
  "account_mode": "MULTIPLE",
  "browser_safelist": [
    {
      "browser_package_name": "com.android.chrome",
      "browser_signature_hashes": [
        "aB1cD2eF3gH4iJ5kL6-mN7oP8qR=="
      ],
      "browser_use_customTab" : true,
      "browser_version_lower_bound": "45"
    },
    {
      "browser_package_name": "com.android.chrome",
      "browser_signature_hashes": [
        "cD2eF3gH4iJ5kL6mN7-oP8qR9sT=="
      ],
      "browser_use_customTab" : false
    },
    {
      "browser_package_name": "org.mozilla.firefox",
      "browser_signature_hashes": [
        "eF3gH4iJ5kL6mN7oP8-qR9sT0uV=="
      ],
      "browser_use_customTab" : false
    },
    {
      "browser_package_name": "org.mozilla.firefox",
      "browser_signature_hashes": [
        "gH4iJ5kL6mN7oP8qR9-sT0uV1wX=="
      ],
      "browser_use_customTab" : true,
      "browser_version_lower_bound": "57"
    },
    {
      "browser_package_name": "com.sec.android.app.sbrowser",
      "browser_signature_hashes": [
        "iJ5kL6mN7oP8qR9sT0-uV1wX2yZ=="
      ],
      "browser_use_customTab" : true,
      "browser_version_lower_bound": "4.0"
    },
    {
      "browser_package_name": "com.sec.android.app.sbrowser",
      "browser_signature_hashes": [
        "kL6mN7oP8qR9sT0uV1-wX2yZ3aB=="
      ],
      "browser_use_customTab" : false
    },
    {
      "browser_package_name": "com.cloudmosa.puffinFree",
      "browser_signature_hashes": [
        "mN7oP8qR9sT0uV1wX2-yZ3aB4dE="
      ],
      "browser_use_customTab" : false
    },
    {
      "browser_package_name": "com.duckduckgo.mobile.android",
      "browser_signature_hashes": [
        "S5Av4...jAi4Q=="
      ],
      "browser_use_customTab" : false
    },
    {
      "browser_package_name": "com.explore.web.browser",
      "browser_signature_hashes": [
        "BzDzB...YHCag=="
      ],
      "browser_use_customTab" : false
    },

    {
      "browser_package_name": "com.ksmobile.cb",
      "browser_signature_hashes": [
        "lFDYx...7nouw=="
      ],
      "browser_use_customTab" : false
    },

    {
      "browser_package_name": "com.microsoft.emmx",
      "browser_signature_hashes": [
        "Ivy-R...A6fVQ=="
      ],
      "browser_use_customTab" : false
    },

    {
      "browser_package_name": "com.opera.browser",
      "browser_signature_hashes": [
        "FIJ3I...jWJWw=="
      ],
      "browser_use_customTab" : false
    },

    {
      "browser_package_name": "com.opera.mini.native",
      "browser_signature_hashes": [
        "TOTyH...mmUYQ=="
      ],
      "browser_use_customTab" : false
    },

    {
      "browser_package_name": "mobi.mgeek.TunnyBrowser",
      "browser_signature_hashes": [
        "RMVoXgjjgyjjmbj4578fcbkyyQ=="
      ],
      "browser_use_customTab" : false
    },

    {
      "browser_package_name": "org.mozilla.focus",
      "browser_signature_hashes": [
        "L72dT...q0oYA=="
      ],
      "browser_use_customTab" : false
    }
  ]
}

Beispiel für eine Standardkonfiguration

Das folgende Beispiel veranschaulicht eine Standardkonfiguration, die die Client-ID, den Umleitungs-URI, ob eine Brokerumleitung registriert ist, und eine Liste von Autoritäten angibt.

{
  "client_id" : "00001111-aaaa-2222-bbbb-3333cccc4444",
  "redirect_uri" : "msauth://com.microsoft.identity.client.sample.local/1wIqXSqBj7w%2Bh11ZifsnqwgyKrY%3D",
  "broker_redirect_uri_registered": true,
  "authorities" : [
    {
      "type": "AAD",
      "audience": {
        "type": "AzureADandPersonalMicrosoftAccount"
      }
      "default": true
    }
  ]
}

Verwenden einer Konfigurationsdatei

Erstellen Sie eine Konfigurationsdatei. Es wird empfohlen, dass Sie Ihre benutzerdefinierte Konfigurationsdatei in res/raw/auth_config.json erstellen. Sie können sie aber an einem beliebigen Ort speichern.

Informieren Sie die MSAL, wo sie nach ihrer Konfiguration suchen soll, wenn Sie die PublicClientApplication erstellen. Beispiel:

//On Worker Thread
IMultipleAccountPublicClientApplication sampleApp = null; 
sampleApp = new PublicClientApplication.createMultipleAccountPublicClientApplication(getApplicationContext(), R.raw.auth_config);

Teilen über

Android-Konfigurationsdatei für die Microsoft-Authentifizierungsbibliothek

Konfigurationseinstellungen

Allgemeine Einstellungen

client_id

redirect_uri

broker_redirect_uri_registered

authorities

Zuordnen der Microsoft Entra-Autorität & -Zielgruppe zu Microsoft Identity Platform-Endpunkten

Eigenschaften von Autoritäten

Eigenschaften der Zielgruppe

authorization_user_agent

multiple_clouds_supported

broker_redirect_uri_registered

http

logging

account_mode

browser_safelist

Die MSAL-Standardkonfigurationsdatei

Beispiel für eine Standardkonfiguration

Verwenden einer Konfigurationsdatei

Feedback

Zusätzliche Ressourcen