Microsoft Entra Ellenőrzött azonosító tartalmazza a Request Service REST API-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 beszerzéséhez az alkalmazást regisztrálnia kell a Microsoft Identitásplatform, és a rendszergazda engedélyt kell adnia a kérelemszolgáltatás REST API-jának elérésére. Ha még nem regisztrálta az ellenőrizhető hitelesítő adatok alkalmazásalkalmazást , tekintse meg , hogyan regisztrálhatja az alkalmazást , és hogyan hozhat létre egy alkalmazáskulcsot.
Hozzáférési jogkivonat lekérése
Az OAuth 2.0 ügyfél hitelesítő adataival a hozzáférési jogkivonatot a Microsoft Identitásplatform használatával szerezheti be. Ehhez használjon megbízható kódtárat. Ebben az oktatóanyagban a Microsoft Authentication Libraryt (MSAL) 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=535fb089-9ff3-47b6-9bfb-4f1264799865
&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
Kötelező
Az alkalmazás által üzemeltetni kívánt címtár-bérlő. Például: https://login.microsoftonline.com/{your-tenant} (Cserélje le your-tenant a bérlő azonosítóját vagy nevét.)
Ügyfél azonosítója
Kötelező
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
Kötelező
Az alkalmazáshoz létrehozott ügyfélkód.
Hatókörök
Kötelező
A beállításnak a 3db474b9-6a0c-4840-96ac-1fceb342124f/.defaultkövetkezőnek kell lennie: . Ez a beállítás létrehoz egy hozzáférési jogkivonatot, amelynek szerepkör-jogcíme a VerifiableCredential.Create.All.
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=12345678-0000-0000-00000000000000000
&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 hí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 be a Content-Type fejlécet a következőre Application/json: .
Készítse elő és csatolja a kiállítási vagy bemutatókérés hasznos adatait a kérelem törzséhez.
Küldje el a kérést a Request Service REST API-nak.
A Request Service API egy HTTP-állapotkódot 201 Created ad vissza egy sikeres híváshoz. Ha az API-hívás hibát ad vissza, tekintse meg a hibahivatkozás dokumentációját.
A kérelem hasznos adattartalma tartalmazza a kiállítási és bemutató 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 azt ismerteti, hogy az alkalmazás milyen hívást indít a Request Service REST API-ra és az alkalmazás visszahívására.
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
}
}
