Microsoft Entra-verifierat ID innehåller REST-API:et för begärandetjänsten. Med det här API:et kan du utfärda och verifiera autentiseringsuppgifter. Den här artikeln visar hur du börjar använda REST-API:et för begärandetjänsten.
API-åtkomsttoken
Ditt program måste innehålla en giltig åtkomsttoken med nödvändiga behörigheter så att det kan komma åt REST-API:et för begärandetjänsten. Åtkomsttoken som utfärdats av Microsofts identitetsplattform innehåller information (omfång) som REST-API:et för begärandetjänsten använder för att verifiera anroparen. En åtkomsttoken säkerställer att anroparen har rätt behörighet att utföra den åtgärd som de begär.
För att få en åtkomsttoken måste din app registreras med Microsofts identitetsplattform och godkännas av en administratör för åtkomst till REST-API:et för begärandetjänsten. Om du inte har registrerat appen verifierbar app för autentiseringsuppgifter kan du läsa hur du registrerar appen och sedan generera en programhemlighet.
Hämta en åtkomsttoken
Använd OAuth 2.0-flödet för klientuppgifters åtkomst för att erhålla åtkomsttoken med hjälp av Microsofts identitetsplattform. Använd ett betrott bibliotek för det här ändamålet. I den här självstudien använder vi Microsoft Authentication Library (MSAL). MSAL förenklar tillägg av autentisering och auktorisering till en app som kan anropa ett säkert webb-API.
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();
I föregående kod anger du följande parametrar:
Parameter
Tillstånd
Beskrivning
Auktoritet
Krävs
Katalogklientorganisationen som programmet planerar att arbeta mot. Till exempel: https://login.microsoftonline.com/{your-tenant}. (Ersätt your-tenant med ditt klientorganisations-ID eller namn.)
Klient-ID
Krävs
Det program-ID som har tilldelats till din app. Du hittar den här informationen i Azure-portalen, där du registrerade din app.
Klienthemlighet
Krävs
Klienthemligheten som du genererade för din app.
Scope
Krävs
Måste anges till 3db474b9-6a0c-4840-96ac-1fceb342124f/.default. Den här inställningen skapar en åtkomsttoken med ett roll anspråk på VerifiableCredential.Create.All.
Mer information om hur du hämtar en åtkomsttoken med hjälp av en konsolapps identitet finns i någon av följande artiklar:
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();
Anropa API:et
Så här utfärdar eller verifierar du en verifierbar autentiseringsuppgift:
Skapa en HTTP POST-begäran till REST-API:et för begärandetjänsten. Klientorganisations-ID:t behövs inte längre i URL:en eftersom det finns som ett anspråk i åtkomsttoken.
Fråga
POST https://verifiedid.did.msidentity.com/v1.0/verifiableCredentials/createIssuanceRequest
Verifiera
POST https://verifiedid.did.msidentity.com/v1.0/verifiableCredentials/createPresentationRequest
Bifoga åtkomsttoken som en ägartoken i auktoriseringshuvudet i en HTTP-begäran.
Authorization: Bearer <token>
Ställ in Content-Type-rubriken till Application/json.
Förbered och bifoga utfärdande eller presentation begära nyttolast till begärandetexten.
Skicka begäran till REST-API:et för begärandetjänsten.
API:et för begärandetjänsten returnerar en HTTP-statuskod 201 Created vid ett lyckat anrop. Om API-anropet returnerar ett fel, kontrollera felreferensdokumentationen .
Nyttolasten för begäran innehåller utfärdande och presentation slutpunkt för återanrop. Slutpunkten är en del av webbprogrammet och bör vara offentligt tillgänglig via HTTPS-protokollet. API:et för begärandetjänsten anropar slutpunkten för att informera din app om vissa händelser. Sådana händelser kan till exempel vara när en användare söker igenom QR-koden, använder den djupa länken till autentiseringsappen eller avslutar presentationsprocessen.
I följande diagram beskrivs det anrop som din app gör till REST-API:et för begärandetjänsten och återanropen till ditt program.
Konfigurera slutpunkten så att den lyssnar på inkommande HTTP POST-begäranden. Följande kodfragment visar hur du hanterar återanropsbegäran för utfärdande via HTTP och hur du därefter uppdaterar användargränssnittet:
Inte tillämpligt. Välj något av de andra programmeringsspråken.
[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
}
}
För den fullständiga koden, se utfärdandekoden och presentationskoden på GitHub-repot.
mainApp.app.post('/api/issuer/issuance-request-callback', parser, async (req, res) => {
var body = '';
req.on('data', function (data) {
body += data;
});
req.on('end', function () {
requestTrace( req );
console.log( body );
var issuanceResponse = JSON.parse(body.toString());
var message = null;
if ( issuanceResponse.code == "request_retrieved" ) {
message = "QR Code is scanned. Waiting for issuance to complete...";
}
if ( issuanceResponse.code == "issuance_successful" ) {
message = "Credential successfully issued";
}
if ( issuanceResponse.code == "issuance_error" ) {
message = issuanceResponse.error.message;
}
// More code here
res.send()
});
res.send()
})
