ID Terverifikasi Microsoft Entra menyertakan REST API Layanan Permintaan. API ini memungkinkan Anda mengeluarkan dan memverifikasi info masuk. Artikel ini menunjukkan cara untuk mulai menggunakan Layanan Permintaan REST API.
Token akses API
Aplikasi Anda perlu menyertakan token akses yang valid dengan izin yang diperlukan agar dapat mengakses Layanan Permintaan REST API. Token akses yang dikeluarkan platform identitas Microsoft berisi informasi (cakupan) yang digunakan Layanan Permintaan REST API untuk memvalidasi pemanggil. Token akses memastikan bahwa pemanggil memiliki izin yang tepat untuk melakukan operasi yang mereka minta.
Untuk mendapatkan token akses, aplikasi Anda harus didaftarkan ke platform identitas Microsoft dan diotorisasi oleh administrator untuk akses ke REQUEST Service REST API. Jika Anda belum mendaftarkan aplikasi verifiable-credentials-app, lihat cara mendaftarkan aplikasi lalu buat rahasia aplikasi.
Mendapatkan token akses
Gunakan alur pemberian kredensial klien OAuth 2.0 untuk memperoleh token akses menggunakan platform identitas Microsoft. Gunakan pustaka tepercaya untuk tujuan ini. Dalam tutorial ini, kami menggunakan Microsoft Authentication Library (MSAL). MSAL menyederhanakan penambahan autentikasi dan otorisasi ke aplikasi yang dapat memanggil API web yang aman.
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();
Dalam kode sebelumnya, berikan parameter berikut:
Parameter
Kondisi
Deskripsi
Otoritas
Diperlukan
Penyewa direktori yaitu tempat aplikasi akan dioperasikan sesuai rencana. Misalnya: https://login.microsoftonline.com/{your-tenant}. (Ganti your-tenant dengan nama atau ID penyewa Anda.)
ID klien
Diperlukan
ID aplikasi yang ditetapkan ke aplikasi Anda. Anda dapat menemukan informasi ini di portal Microsoft Azure, tempat Anda mendaftarkan aplikasi Anda.
Rahasia Klien
Diperlukan
Rahasia klien yang Anda buat untuk aplikasi Anda.
Cakupan
Diperlukan
Harus diatur ke 3db474b9-6a0c-4840-96ac-1fceb342124f/.default. Pengaturan ini menghasilkan token akses dengan klaim peran .VerifiableCredential.Create.All
Untuk informasi selengkapnya tentang cara mendapatkan token akses dengan menggunakan identitas aplikasi konsol, lihat salah satu artikel berikut ini:
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();
Panggil API
Untuk menerbitkan atau memverifikasi kredensial yang dapat diverifikasi:
Buat permintaan HTTP POST ke Permintaan Layanan REST API. ID penyewa tidak diperlukan lagi di URL karena ada sebagai klaim dalam token akses.
Masalah
POST https://verifiedid.did.msidentity.com/v1.0/verifiableCredentials/createIssuanceRequest
Verifikasi
POST https://verifiedid.did.msidentity.com/v1.0/verifiableCredentials/createPresentationRequest
Lampirkan token akses sebagai token pembawa ke header otorisasi dalam permintaan HTTP.
Authorization: Bearer <token>
Atur header Content-Type ke Application/json.
Siapkan dan lampirkan payload permintaan penerbitan atau presentasi ke isi permintaan.
Kirimkan permintaan ke Layanan Permintaan REST API.
API Layanan Permintaan mengembalikan Kode Status HTTP 201 Created pada panggilan yang berhasil. Jika panggilan API mengembalikan kesalahan, periksa dokumentasi referensi kesalahan.
Payload permintaan berisi titik akhir panggilan balik penerbitan dan presentasi. Titik akhir adalah bagian dari aplikasi web Anda dan harus tersedia untuk umum melalui protokol HTTPS. API Layanan Permintaan memanggil titik akhir Anda untuk memberi tahu aplikasi Anda tentang peristiwa tertentu. Misalnya, peristiwa seperti itu mungkin ketika pengguna memindai kode QR, menggunakan tautan mendalam ke aplikasi pengautentikasi, atau menyelesaikan proses presentasi.
Diagram berikut menjelaskan panggilan yang dilakukan aplikasi Anda ke REQUEST Service REST API dan panggilan balik ke aplikasi Anda.
Konfigurasikan titik akhir Anda untuk mendengarkan permintaan HTTP POST yang masuk. Cuplikan kode berikut menunjukkan cara menangani permintaan HTTP panggilan balik penerbitan dan cara memperbarui UI yang sesuai:
Tidak berlaku. Pilih salah satu bahasa pemrograman lainnya.
[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
}
}
Untuk kode lengkapnya, lihat kode penerbitan dan presentasi di repositori GitHub.
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()
})
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat: https://aka.ms/ContentUserFeedback.
