Microsoft Entra geverifieerde ID bevat de REST API van de aanvraagservice. Met deze API kunt u referenties uitgeven en verifiëren. In dit artikel leest u hoe u de REST API van de aanvraagservice kunt gaan gebruiken.
API-toegangstoken
Uw toepassing moet een geldig toegangstoken met de vereiste machtigingen bevatten, zodat deze toegang heeft tot de REST API van de aanvraagservice. Toegangstokens die zijn uitgegeven door het Microsoft Identity Platform bevatten informatie (bereiken) die door de REST API van de aanvraagservice worden gebruikt om de aanroeper te valideren. Een toegangstoken zorgt ervoor dat de aanroeper over de juiste machtigingen beschikt om de bewerking uit te voeren die ze aanvragen.
Als u een toegangstoken wilt ophalen, moet uw app worden geregistreerd bij het Microsoft Identity Platform en worden geautoriseerd door een beheerder voor toegang tot de REST API van de aanvraagservice. Als u de toepassing verifieerbare referenties-app niet hebt geregistreerd, raadpleegt u hoe u de app registreert en vervolgens een toepassingsgeheim genereert.
Een toegangstoken opvragen
Gebruik de stroom voor het verlenen van OAuth 2.0-clientreferenties om het toegangstoken te verkrijgen met behulp van het Microsoft Identity Platform. Gebruik hiervoor een vertrouwde bibliotheek. In deze zelfstudie gebruiken we de Microsoft Authentication Library (MSAL). MSAL vereenvoudigt het toevoegen van verificatie en autorisatie aan een app die een beveiligde web-API kan aanroepen.
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();
Geef in de voorgaande code de volgende parameters op:
Parameter
Voorwaarde
Beschrijving
Instantie
Vereist
De directorytenant waarop de toepassing van plan is te werken. Voorbeeld: https://login.microsoftonline.com/{your-tenant}. (Vervang door your-tenant uw tenant-id of -naam.)
Client ID
Vereist
De toepassings-ID die aan uw app is toegewezen. U vindt deze informatie in Azure Portal, waar u uw app hebt geregistreerd.
Clientgeheim
Vereist
Het clientgeheim dat u hebt gegenereerd voor uw app.
Bereiken
Vereist
Moet worden ingesteld op 3db474b9-6a0c-4840-96ac-1fceb342124f/.default. Deze instelling produceert een toegangstoken met een rolclaim van VerifiableCredential.Create.All.
Zie een van de volgende artikelen voor meer informatie over het verkrijgen van een toegangstoken met behulp van de identiteit van een console-app:
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();
De API aanroepen
Een verifieerbare referentie uitgeven of verifiëren:
Maak een HTTP POST-aanvraag naar de REST API van de aanvraagservice. De tenant-id is niet meer nodig in de URL omdat deze aanwezig is als een claim in het toegangstoken.
Probleem
POST https://verifiedid.did.msidentity.com/v1.0/verifiableCredentials/createIssuanceRequest
Verifiëren
POST https://verifiedid.did.msidentity.com/v1.0/verifiableCredentials/createPresentationRequest
Koppel het toegangstoken als bearer-token aan de autorisatieheader in een HTTP-aanvraag.
Authorization: Bearer <token>
Stel de Content-Type koptekst in op Application/json.
Bereid de nettolading van de uitgifte - of presentatieaanvraag voor en koppel deze aan de hoofdtekst van de aanvraag.
Dien de aanvraag in bij de REST API van de aanvraagservice.
De AANVRAAGservice-API retourneert een HTTP-statuscode 201 Created voor een geslaagde aanroep. Als de API-aanroep een fout retourneert, raadpleegt u de documentatie voor foutreferenties.
Presentatieaanvraag met FaceCheck. Wanneer u FaceCheck gebruikt, moet de waarde onwaar zijn omdat het includeReceipt ontvangstbewijs vervolgens niet wordt ondersteund.
De nettolading van de aanvraag bevat het callback-eindpunt voor uitgifte en presentatie . Het eindpunt maakt deel uit van uw webtoepassing en moet openbaar beschikbaar zijn via het HTTPS-protocol. De Api voor aanvraagservice roept uw eindpunt aan om uw app te informeren over bepaalde gebeurtenissen. Dergelijke gebeurtenissen kunnen bijvoorbeeld zijn wanneer een gebruiker de QR-code scant, de dieptekoppeling naar de verificator-app gebruikt of het presentatieproces voltooit.
In het volgende diagram wordt de aanroep van uw app beschreven in de REST API van de aanvraagservice en de callbacks naar uw toepassing.
Configureer uw eindpunt om te luisteren naar binnenkomende HTTP POST-aanvragen. In het volgende codefragment ziet u hoe u de HTTP-aanvraag voor de uitgifteaanroep kunt verwerken en hoe u de gebruikersinterface dienovereenkomstig bijwerkt:
Niet van toepassing. Kies een van de andere programmeertalen.
[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
}
}
