Microsoft Entra Verified ID umfasst die REST-API für den Anforderungsdienst. Mit dieser API können Sie Anmeldeinformationen ausstellen und überprüfen. In diesem Artikel wird gezeigt, wie Sie mit der Arbeit mit der Anforderungsdienst-REST-API beginnen.
API-Zugriffstoken
Damit Ihre Anwendung auf die Anforderungsdienst-REST-API zugreifen kann, müssen Sie neben den erforderlichen Berechtigungen ein gültiges Zugriffstoken hinzufügen. Die von Microsoft Identity Platform ausgestellten Zugriffstoken enthalten Informationen (Bereiche), welche die Anforderungsdienst-REST-API verwendet, um den Aufrufer zu überprüfen. Durch ein Zugriffstoken wird sichergestellt, dass der Anrufer die ordnungsgemäßen Berechtigungen hat, um den Vorgang auszuführen, der angefordert wird.
Um ein Zugriffstoken zu erhalten, muss Ihre App bei der Plattform Microsoft Identity Platform registriert sein und von einem*einer Administrator*in für den Zugriff auf die Anforderungsdienst-API autorisiert werden. Wenn Sie die verifiable-credentials-app (Nachweise-App) noch nicht registriert haben, führen Sie die unter Registrieren der App beschriebenen Schritte aus und generieren Sie dann ein Anwendungsgeheimnis.
Abrufen eines Zugriffstokens
Verwenden Sie den Flow zur Gewährung von OAuth 2.0-Clientanmeldeinformationen, um mithilfe von Microsoft Identity Platform das Zugriffstoken anzufordern. Verwenden Sie dazu eine vertrauenswürdige Bibliothek. In diesem Tutorial wird die Microsoft-Authentifizierungsbibliothek (Microsoft Authentication Library), (MSAL) verwendet. MSAL vereinfacht das Hinzufügen von Authentifizierung und Autorisierung zu einer Anwendung, die eine sichere Web-API aufrufen kann.
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=3db474b9-6a0c-4840-96ac-1fceb342124f/.default
&client_secret=sampleCredentia1s
&grant_type=client_credentials
// Initialize MSAL library by using the following code
ConfidentialClientApplicationBuilder.Create(AppSettings.ClientId)
.WithClientSecret(AppSettings.ClientSecret)
.WithAuthority(new Uri(AppSettings.Authority))
.Build();
// Acquire an access token
result = await app.AcquireTokenForClient(AppSettings.Scopes)
.ExecuteAsync();
// Initialize MSAL library by using the following code
const msalConfig = {
auth: {
clientId: config.azClientId,
authority: `https://login.microsoftonline.com/${config.azTenantId}`,
clientSecret: config.azClientSecret,
},
system: {
loggerOptions: {
loggerCallback(loglevel, message, containsPii) {
console.log(message);
},
piiLoggingEnabled: false,
logLevel: msal.LogLevel.Verbose,
}
}
};
const cca = new msal.ConfidentialClientApplication(msalConfig);
const msalClientCredentialRequest = {
scopes: ["3db474b9-6a0c-4840-96ac-1fceb342124f/.default"],
skipCache: false,
};
module.exports.msalCca = cca;
module.exports.msalClientCredentialRequest = msalClientCredentialRequest;
// Acquire an access token
const result = await mainApp.msalCca.acquireTokenByClientCredential(mainApp.msalClientCredentialRequest);
if ( result ) {
accessToken = result.accessToken;
}
# Initialize MSAL library by using the following code
msalCca = msal.ConfidentialClientApplication( config["azClientId"],
authority="https://login.microsoftonline.com/" + config["azTenantId"],
client_credential=config["azClientSecret"],
)
# Acquire an access token
accessToken = ""
result = msalCca.acquire_token_for_client( scopes="3db474b9-6a0c-4840-96ac-1fceb342124f/.default" )
if "access_token" in result:
accessToken = result['access_token']
// Initialize MSAL library by using the following code
ConfidentialClientApplication app = ConfidentialClientApplication.builder(
clientId,
ClientCredentialFactory.createFromSecret(clientSecret))
.authority(authority)
.build();
// Acquire an access token
ClientCredentialParameters clientCredentialParam = ClientCredentialParameters.builder(
Collections.singleton(scope))
.build();
CompletableFuture<IAuthenticationResult> future = app.acquireToken(clientCredentialParam);
IAuthenticationResult result = future.get();
return result.accessToken();
Geben Sie im vorangehenden Code die folgenden Parameter an:
Parameter
Condition
BESCHREIBUNG
Authority
Erforderlich
Der Verzeichnismandant, der von der Anwendung für den Betrieb verwendet werden soll. Beispiel: https://login.microsoftonline.com/{your-tenant}. (Ersetzen Sie your-tenant mit Ihrer Mandanten-ID oder Ihrem Namen.)
Client-ID
Erforderlich
Die Anwendungs-ID, die Ihrer App zugewiesen ist. Diese Informationen finden Sie im Azure-Portal, in dem Sie Ihre App registriert haben.
Geheimer Clientschlüssel
Erforderlich
Der geheime Clientschlüssel, den Sie für Ihre App generiert haben.
Bereiche
Erforderlich
Muss auf 3db474b9-6a0c-4840-96ac-1fceb342124f/.default festgelegt sein. Mit dieser Einstellung wird ein Zugriffstoken mit einem Rollenanspruch von VerifiableCredential.Create.All erstellt.
Weitere Informationen zum Abrufen eines Zugriffstokens mithilfe der Identität einer Konsolen-App finden Sie in einem der folgenden Artikel:
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=3db474b9-6a0c-4840-96ac-1fceb342124f/.default
&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
// Initialize MSAL library by using the following code
X509Certificate2 certificate = AppSettings.ReadCertificate(AppSettings.CertificateName);
app = ConfidentialClientApplicationBuilder.Create(AppSettings.ClientId)
.WithCertificate(certificate)
.WithAuthority(new Uri(AppSettings.Authority))
.Build();
// Acquire an access token
result = await app.AcquireTokenForClient(AppSettings.Scopes)
.ExecuteAsync();
// Initialize MSAL library by using the following code
const msalConfig = {
auth: {
clientId: config.azClientId,
authority: `https://login.microsoftonline.com/${config.azTenantId}`,
clientCertificate: {
thumbprint: "CERT_THUMBPRINT", // a 40-digit hexadecimal string
privateKey: "CERT_PRIVATE_KEY"
}
},
system: {
loggerOptions: {
loggerCallback(loglevel, message, containsPii) {
console.log(message);
},
piiLoggingEnabled: false,
logLevel: msal.LogLevel.Verbose,
}
}
};
const cca = new msal.ConfidentialClientApplication(msalConfig);
const msalClientCredentialRequest = {
scopes: ["3db474b9-6a0c-4840-96ac-1fceb342124f/.default"],
skipCache: false,
};
module.exports.msalCca = cca;
module.exports.msalClientCredentialRequest = msalClientCredentialRequest;
// Acquire an access token
const result = await mainApp.msalCca.acquireTokenByClientCredential(mainApp.msalClientCredentialRequest);
if ( result ) {
accessToken = result.accessToken;
}
# Initialize MSAL library by using the following code
with open(config["azCertificatePrivateKeyLocation"], "rb") as file:
private_key = file.read()
with open(config["azCertificateLocation"]) as file:
public_certificate = file.read()
cert = load_pem_x509_certificate(data=bytes(public_certificate, 'UTF-8'), backend=default_backend())
thumbprint = (cert.fingerprint(hashes.SHA1()).hex())
msalCca = msal.ConfidentialClientApplication( config["azClientId"],
authority="https://login.microsoftonline.com/" + config["azTenantId"],
client_credential={
"private_key": private_key,
"thumbprint": thumbprint,
"public_certificate": public_certificate
}
)
# Acquire an access token
accessToken = ""
result = msalCca.acquire_token_for_client( scopes="3db474b9-6a0c-4840-96ac-1fceb342124f/.default" )
if "access_token" in result:
accessToken = result['access_token']
// Initialize MSAL library by using the following code
PKCS8EncodedKeySpec spec = new PKCS8EncodedKeySpec(Files.readAllBytes(Paths.get(certKeyLocation)));
PrivateKey key = KeyFactory.getInstance("RSA").generatePrivate(spec);
java.io.InputStream certStream = (java.io.InputStream)new ByteArrayInputStream(Files.readAllBytes(Paths.get(certLocation)));
X509Certificate cert = (X509Certificate) CertificateFactory.getInstance("X.509").generateCertificate(certStream);
ConfidentialClientApplication app = ConfidentialClientApplication.builder(
clientId,
ClientCredentialFactory.createFromCertificate(key, cert))
.authority(authority)
.build();
// Acquire an access token
ClientCredentialParameters clientCredentialParam = ClientCredentialParameters.builder(
Collections.singleton(scope))
.build();
CompletableFuture<IAuthenticationResult> future = app.acquireToken(clientCredentialParam);
IAuthenticationResult result = future.get();
return result.accessToken();
Aufrufen der API
Um einen Nachweis auszustellen oder zu überprüfen:
Erstellen Sie eine HTTP POST-Anforderung für die Anforderungsdienst-REST-API. Die Mandanten-ID wird in der URL nicht mehr benötigt, da sie als Anspruch im Zugriffstoken enthalten ist.
Abgang
POST https://verifiedid.did.msidentity.com/v1.0/verifiableCredentials/createIssuanceRequest
Überprüfen
POST https://verifiedid.did.msidentity.com/v1.0/verifiableCredentials/createPresentationRequest
Fügen Sie das Zugriffstoken als Bearertoken an den Autorisierungsheader einer HTTP-Anforderung an.
Authorization: Bearer <token>
Legen Sie den Header Content-Type auf Application/json fest.
Bereiten Sie die Ausstellungs- oder Präsentations-Anforderungsnutzdaten vor, und fügen Sie sie an den Anforderungstext an.
Übermitteln Sie die Anforderung an die Anforderungsdienst-REST-API.
Die Anforderungsdienst-API gibt für einen erfolgreichen Aufruf einen HTTP-Statuscode 201 Created zurück. Wenn der API-Aufruf einen Fehler zurückgibt, überprüfen Sie die Fehlerreferenzdokumentation.
Die Anforderungsnutzdaten enthalten den Ausstellungs- und Präsentations-Rückrufendpunkt. Der Endpunkt ist Bestandteil Ihrer Webanwendung und sollte über das HTTPS-Protokoll öffentlich verfügbar sein. Die Anforderungsdienst-API ruft Ihren Endpunkt auf, um Ihre App über bestimmte Ereignisse zu informieren. Solche Ereignisse können beispielsweise das Scannen des QR-Codes durch einen Benutzer, das Verwenden des Deep-Links zur Authentifikator-App oder das Beenden des Präsentationsprozesses sein.
Im folgenden Diagramm werden der Aufruf ihrer App an die Anforderungsdienst-REST-API und die Rückrufe an Ihre Anwendung beschrieben.
Konfigurieren Sie Ihren Endpunkt für das Lauschen auf eingehende HTTP POST-Anforderungen. Im folgenden Codeausschnitt wird veranschaulicht, wie die HTTP-Anforderung für den Ausstellungsrückruf behandelt und die Benutzeroberfläche entsprechend aktualisiert werden kann:
Nicht zutreffend. Wählen Sie eine der anderen Programmiersprachen aus.
[HttpPost]
public async Task<ActionResult> IssuanceCallback()
{
try
{
string content = new System.IO.StreamReader(this.Request.Body).ReadToEndAsync().Result;
_log.LogTrace("callback!: " + content);
JObject issuanceResponse = JObject.Parse(content);
// More code here
if (issuanceResponse["code"].ToString() == "request_retrieved")
{
var cacheData = new
{
status = "request_retrieved",
message = "QR Code is scanned. Waiting for issuance...",
};
_cache.Set(state, JsonConvert.SerializeObject(cacheData));
// More code here
}
}
