Microsoft Entra Verified ID zahrnuje rozhraní REST API služby žádosti. Toto rozhraní API umožňuje vydávat a ověřovat přihlašovací údaje. V tomto článku se dozvíte, jak začít používat rozhraní REST API služby požadavků.
Přístupový token rozhraní API
Vaše aplikace musí obsahovat platný přístupový token s požadovanými oprávněními, aby měla přístup k rozhraní REST API služby požadavku. Přístupové tokeny vydané platformou Microsoft Identity Platform obsahují informace (obory), které rozhraní REST API vyžádané služby používá k ověření volajícího. Přístupový token zajišťuje, že volající má správná oprávnění k provedení operace, kterou požaduje.
Pokud chcete získat přístupový token, musí být vaše aplikace zaregistrovaná na platformě Microsoft Identity Platform a musí být autorizována správcem pro přístup k rozhraní REST API služby žádosti. Pokud jste nezaregistrovali aplikaci pro ověřitelné přihlašovací údaje, podívejte se , jak aplikaci zaregistrovat, a pak vygenerovat tajemství aplikace.
Získání přístupového tokenu
Pomocí přihlašovacích údajů klienta OAuth 2.0 udělte toku k získání přístupového tokenu pomocí platformy Microsoft Identity Platform. Pro tento účel použijte důvěryhodnou knihovnu. V tomto kurzu používáme knihovnu Microsoft Authentication Library (MSAL). MSAL zjednodušuje přidávání ověřování a autorizace do aplikace, která může volat zabezpečené webové rozhraní 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();
V předchozím kódu zadejte následující parametry:
Parametr
Podmínka
Popis
Autorita
Požadovaný
Tenant adresáře, na kterém aplikace plánuje pracovat. Příklad: https://login.microsoftonline.com/{your-tenant}. (Nahraďte your-tenant vaším ID tenanta nebo názvem.)
ID klienta
Požadovaný
ID aplikace, které je přiřazené k vaší aplikaci. Tyto informace najdete na webu Azure Portal, kde jste aplikaci zaregistrovali.
Klientské tajemství
Povinný
Tajný klíč klienta, který jste vygenerovali pro aplikaci.
Oblasti
Povinný
Musí být nastavena na 3db474b9-6a0c-4840-96ac-1fceb342124f/.default. Toto nastavení vytvoří přístupový token s rolemi deklarací identity VerifiableCredential.Create.All.
Další informace o získání přístupového tokenu pomocí identity konzolové aplikace najdete v jednom z následujících článků:
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();
Zavolejte rozhraní API
Pokud chcete vydat nebo ověřit ověřitelné přihlašovací údaje:
Vytvořte požadavek HTTP POST na rozhraní REST API služby Request. ID tenanta už není v adrese URL potřeba, protože se v přístupovém tokenu nachází jako deklarace identity.
Úkol
POST https://verifiedid.did.msidentity.com/v1.0/verifiableCredentials/createIssuanceRequest
Ověřit
POST https://verifiedid.did.msidentity.com/v1.0/verifiableCredentials/createPresentationRequest
Připojte přístupový token jako nosný token k autorizační hlavičce v požadavku HTTP.
Authorization: Bearer <token>
Nastavte záhlaví Content-Type na Application/json.
Připravte a připojte datovou část požadavku vystavení nebo prezentaci do obsahu požadavku.
Odešlete požadavek do rozhraní REST API služby.
API rozhraní požadavku služby vrátí stavový kód HTTP 201 Created v případě úspěšného volání. Pokud volání rozhraní API vrátí chybu, zkontrolujte dokumentaci pro referenci chyby .
Datová část požadavku obsahuje koncový bod zpětného volání pro vystavení a prezentace. Koncový bod je součástí vaší webové aplikace a měl by být veřejně dostupný prostřednictvím protokolu HTTPS. Rozhraní API vyžádané služby volá koncový bod, aby informoval vaši aplikaci o určitých událostech. Takové události můžou být například, když uživatel naskenuje kód QR, použije přímý odkaz na ověřovací aplikaci nebo dokončí proces prezentace.
Následující diagram popisuje volání, které vaše aplikace provede do rozhraní REST API služby Request, a zpětná volání do vaší aplikace.
Nakonfigurujte koncový bod tak, aby naslouchal příchozím požadavkům HTTP POST. Následující ukázka kódu demonstruje, jak zpracovat HTTP požadavek zpětného volání při vystavení a jak odpovídajícím způsobem aktualizovat UI:
Nelze použít. Zvolte jeden z dalších programovacích jazyků.
[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
}
}
