A Microsoft Entra ellenőrzött azonosítója tartalmazza a Kérelemszolgáltatás REST API-ját. Ez az API lehetővé teszi a hitelesítő adatok kiállítását és ellenőrzését. Ez a cikk bemutatja, hogyan kezdheti el használni a Request Service REST API-t.
API hozzáférési jogkivonat
Az alkalmazásnak tartalmaznia kell egy érvényes hozzáférési jogkivonatot a szükséges engedélyekkel, hogy hozzáférhessen a Kérelemszolgáltatás REST API-hoz. A Microsoft identitásplatform által kibocsátott hozzáférési jogkivonatok olyan információkat (hatóköröket) tartalmaznak, amelyeket a Kérelemszolgáltatás REST API a hívó ellenőrzésére használ. A hozzáférési jogkivonat biztosítja, hogy a hívó megfelelő engedélyekkel rendelkezik a kért művelet végrehajtásához.
A hozzáférési jogkivonat megszerzéséhez az alkalmazást regisztrálni kell a Microsoft identitásplatformján, és a rendszergazdának engedélyeznie kell a Request Service REST API elérését. Ha még nem regisztrálta a ellenőrizhető hitelesítési adatok alkalmazást, tekintse meg a útmutatót az alkalmazás regisztrálására, majd hozzon létre egy alkalmazástitkos kulcsot.
Hozzáférési jogkivonat lekérése
Az OAuth 2.0 ügyfél-hitelesítési adatfolyamot használva szerezze be a hozzáférési tokent a Microsoft identitásplatform használatával. Ehhez használjon megbízható kódtárat. Ebben az oktatóanyagban a Microsoft Authentication Library (MSAL) használatát használjuk. Az MSAL leegyszerűsíti a hitelesítés és az engedélyezés hozzáadását egy olyan alkalmazáshoz, amely biztonságos webes API-t hívhat meg.
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();
Az előző kódban adja meg a következő paramétereket:
Paraméter
Feltétel
Leírás
Hatóság
Szükséges
Az a címtárbérlő, amellyel az alkalmazás működni fog. Például: https://login.microsoftonline.com/{your-tenant}. (Cserélje le your-tenant a bérlőazonosítóra vagy -névre.)
Ügyfélazonosító
Szükséges
Az alkalmazáshoz rendelt alkalmazásazonosító. Ezeket az információkat az Azure Portalon találja, ahol regisztrálta az alkalmazást.
Titkos ügyfélkód
Szükséges
Az alkalmazáshoz létrehozott ügyfélkód.
Hatókörök
Szükséges
A értéknek 3db474b9-6a0c-4840-96ac-1fceb342124f/.defaultkell lennie. Ez a beállítás létrehoz egy hozzáférési jogkivonatot, amiben VerifiableCredential.Create.All jogcím található.
A hozzáférési jogkivonat konzolalkalmazás identitásának használatával történő beszerzéséről az alábbi cikkek egyikében talál további információt:
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();
Az API meghívása
Ellenőrizhető hitelesítő adatok kiállítása vagy ellenőrzése:
HTTP POST-kérés létrehozása a Kérelemszolgáltatás REST API-jának. A bérlőazonosítóra már nincs szükség az URL-címben, mert jogcímként szerepel a hozzáférési jogkivonatban.
probléma
POST https://verifiedid.did.msidentity.com/v1.0/verifiableCredentials/createIssuanceRequest
Ellenőrizze
POST https://verifiedid.did.msidentity.com/v1.0/verifiableCredentials/createPresentationRequest
Csatolja a hozzáférési jogkivonatot tulajdonosi jogkivonatként egy HTTP-kérés engedélyezési fejlécéhez.
Authorization: Bearer <token>
Állítsa a Content-Type fejlécet Application/jsonértékre.
Készítse elő és csatolja a kiállítási vagy bemutatási kérelem rakományát a kérés törzséhez.
Küldje el a kérést a Request Service REST API-nak.
A Request Service API egy HTTP-állapotkódot ad vissza, 201 Created egy sikeres hívás esetén. Ha az API-hívás hibát ad vissza, ellenőrizze a hibahivatkozás dokumentációját.
Kiállítási kérelem példa
Az alábbi példa egy ellenőrizhető hitelesítőadat-kiállítási kérést mutat be. Az adatterheléssel kapcsolatos információkért lásd a Kérelemszolgáltatás REST API kiállítási specifikációját .
POST https://verifiedid.did.msidentity.com/v1.0/verifiableCredentials/createIssuanceRequest
Content-Type: application/json
Authorization: Bearer <token>
{...JSON payload...}
A kérés hasznos adatai tartalmazzák a kiállítás és a bemutatás visszahívási végpontot. A végpont a webalkalmazás része, és nyilvánosan elérhetőnek kell lennie a HTTPS protokollon keresztül. A Request Service API meghívja a végpontot, hogy tájékoztassa az alkalmazást bizonyos eseményekről. Ilyen esemény lehet például, ha egy felhasználó megvizsgálja a QR-kódot, használja a hitelesítő alkalmazásra mutató mélyhivatkozást, vagy befejezi a bemutató folyamatát.
Az alábbi ábra bemutatja, milyen hívást indít az alkalmazás a Request Service REST API-hoz, valamint az alkalmazásnak szóló visszahívásokat.
Konfigurálja a végpontot a bejövő HTTP POST-kérelmek figyelésére. Az alábbi kódrészlet bemutatja, hogyan kezelhető a kiállítási visszahívási HTTP-kérés, és hogyan frissíthető a felhasználói felület ennek megfelelően:
Nem alkalmazható. Válasszon egyet a többi programozási nyelv közül.
[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
}
}
A teljes kódért tekintse meg a kiadás és bemutatási kódot a GitHub tárhelyen.
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()
})
