Microsoft Entra Doğrulanmış Kimliği İstek Hizmeti REST API'sini içerir. Bu API, kimlik bilgilerini vermenizi ve doğrulamanızı sağlar. Bu makalede İstek Hizmeti REST API'sini kullanmaya nasıl başlayacağınız gösterilmektedir.
API erişim belirteci
Uygulamanızın İstek Hizmeti REST API'sine erişebilmesi için gerekli izinlere sahip geçerli bir erişim belirteci içermesi gerekir. Microsoft kimlik platformu tarafından verilen erişim belirteçleri, İstek Hizmeti REST API'sinin çağıranı doğrulamak için kullandığı bilgileri (kapsamları) içerir. Erişim belirteci, çağıranın istediği işlemi gerçekleştirmek için uygun izinlere sahip olmasını sağlar.
Erişim belirteci almak için uygulamanızın Microsoft kimlik platformuna kayıtlı olması ve İstek Hizmeti REST API'sine erişim için bir yönetici tarafından yetkilendirilmiş olması gerekir. verifiable-credentials-app uygulamasını kaydetmediyseniz, uygulamayı nasıl kaydedeceğinizi görmek için bkz. ve ardından bir uygulama gizli anahtarı oluşturun.
Erişim belirteci alma
Microsoft kimlik platformunu kullanarak erişim belirtecini almak için OAuth 2.0 istemci kimlik bilgileri verme akışı kullanın. Bu amaçla güvenilen bir kitaplık kullanın. Bu öğreticide, Microsoft Kimlik Doğrulama Kitaplığı'nı (MSAL) kullanacağız. MSAL, güvenli bir web API'sini çağırabilen bir uygulamaya kimlik doğrulaması ve yetkilendirme eklemeyi kolaylaştırır.
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();
Yukarıdaki kodda aşağıdaki parametreleri sağlayın:
Parametre
Koşul
Açıklama
Otorite
Gerekli
Uygulamanın üzerinde çalışmak üzere planladığı dizin kiracısı. Örneğin: https://login.microsoftonline.com/{your-tenant}. (your-tenant ile kiracı kimliğinizi veya adınızıdeğiştirin.)
İstemci Kimliği
Gerekli
Uygulamanıza atanan uygulama kimliği. Bu bilgileri uygulamanızı kaydettiğiniz Azure portalında bulabilirsiniz.
İstemci sırrı
Gerekli
Uygulamanız için oluşturduğunuz istemci gizli anahtarı.
Kapsam
Gerekli
3db474b9-6a0c-4840-96ac-1fceb342124f/.defaultolarak ayarlanmalıdır. Bu ayar, talebi rolleri olan bir erişim belirteci oluşturur.
Konsol uygulamasının kimliğini kullanarak erişim belirteci alma hakkında daha fazla bilgi için aşağıdaki makalelerden birine bakın:
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();
API'yi çağırma
Doğrulanabilir bir kimlik belgesi vermek veya doğrulamasını yapmak için:
İstek Hizmeti REST API'sine bir HTTP POST isteği oluşturun. Erişim belirtecinde talep olarak bulunduğundan artık URL'de kiracı kimliği gerekli değildir.
Sorun
POST https://verifiedid.did.msidentity.com/v1.0/verifiableCredentials/createIssuanceRequest
Doğrula
POST https://verifiedid.did.msidentity.com/v1.0/verifiableCredentials/createPresentationRequest
Erişim belirtecini bir HTTP isteğindeki yetkilendirme üst bilgisine taşıyıcı belirteç olarak ekleyin.
Authorization: Bearer <token>
Content-Type üst bilgisini Application/jsonolarak ayarlayın.
İstek gövdesine verme veya sunu talep yükünü hazırlayın ve ekleyin.
İsteği İstek Hizmeti REST API'sine gönderin.
İstek Hizmeti API'si, başarılı bir çağrıda bir HTTP Durum Kodu 201 Created döndürür. API çağrısı bir hata döndürürse,hata başvurusu belgelerine bakın.
Aşağıdaki örnekte doğrulanabilir kimlik bilgileri sunu isteği gösterilmektedir. Yük hakkında daha fazla bilgi için bkz. İstek Hizmeti REST API sunum belirtimi.
POST https://verifiedid.did.msidentity.com/v1.0/verifiableCredentials/createPresentationRequest
Content-Type: application/json
Authorization: Bearer <token>
{...JSON payload...}
İstek yükü, oluşturma ve sunum geri çağırma uç noktasını içerir. Uç nokta web uygulamanızın bir parçasıdır ve HTTPS protokolü aracılığıyla genel kullanıma açık olmalıdır. İstek Hizmeti API'si, uygulamanızı belirli olaylar hakkında bilgilendirmek için uç noktanızı çağırır. Örneğin, bu tür olaylar bir kullanıcı QR kodunu taradığında, doğrulayıcı uygulamasının derin bağlantısını kullandığında veya sunu işlemini tamamladığında olabilir.
Aşağıdaki diyagramda uygulamanızın İstek Hizmeti REST API'sine yaptığı çağrı ve uygulamanıza yapılan geri çağırmalar açıklanmaktadır.
API'ye çağrıyı ve geri çağırma olaylarını gösteren
Uç noktanızı gelen HTTP POST isteklerini dinleyecek şekilde yapılandırın. Aşağıdaki kod parçacığı, verme geri çağırma HTTP isteğinin nasıl işleneceğini ve kullanıcı arabiriminin buna göre nasıl güncelleştirileceklerini gösterir:
Uygulanamaz. Diğer programlama dillerinden birini seçin.
[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
}
}
Tam kod için GitHub deposundaki yayım ve sunum koduna bakın.
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()
})
