Microsoft Entra – verifierat ID innehåller REST-API:et för begärandetjänsten. Med det här API:et kan du utfärda och verifiera autentiseringsuppgifter. Den här artikeln visar hur du börjar använda REST-API:et för begärandetjänsten.
API-åtkomsttoken
Ditt program måste innehålla en giltig åtkomsttoken med nödvändiga behörigheter så att det kan komma åt REST-API:et för begärandetjänsten. Åtkomsttoken som utfärdats av Microsofts identitetsplattform innehåller information (omfång) som REST API:et för begärandetjänsten använder för att verifiera anroparen. En åtkomsttoken säkerställer att anroparen har rätt behörighet att utföra den åtgärd som de begär.
För att få en åtkomsttoken måste din app registreras med Microsofts identitetsplattform och godkännas av en administratör för åtkomst till REST-API:et för begärandetjänsten. Om du inte har registrerat appen verifiable-credentials-app kan du läsa om hur du registrerar appen och sedan genererar en programhemlighet.
Hämta en åtkomsttoken
Använd beviljandeflödet för OAuth 2.0-klientautentiseringsuppgifter för att hämta åtkomsttoken med hjälp av Microsofts identitetsplattform. Använd ett betrott bibliotek för det här ändamålet. I den här självstudien använder vi Microsoft Authentication Library (MSAL). MSAL förenklar tillägg av autentisering och auktorisering till en app som kan anropa ett säkert webb-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();
I föregående kod anger du följande parametrar:
Parameter
Villkor
beskrivning
Utfärdare
Obligatoriskt
Katalogklientorganisationen som programmet planerar att arbeta mot. Exempel: https://login.microsoftonline.com/{your-tenant}. (Ersätt your-tenant med ditt klientorganisations-ID eller namn.)
Client ID
Obligatoriskt
Det program-ID som har tilldelats till din app. Du hittar den här informationen i Azure-portalen, där du registrerade din app.
Klienthemlighet
Obligatoriskt
Klienthemligheten som du genererade för din app.
Omfattningar
Obligatoriskt
Måste anges till 3db474b9-6a0c-4840-96ac-1fceb342124f/.default. Den här inställningen skapar en åtkomsttoken med ett rollanspråk på VerifiableCredential.Create.All.
Mer information om hur du hämtar en åtkomsttoken med hjälp av en konsolapps identitet finns i någon av följande artiklar:
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();
Anropa API
Så här utfärdar eller verifierar du en verifierbar autentiseringsuppgift:
Skapa en HTTP POST-begäran till REST-API:et för begärandetjänsten. Klientorganisations-ID:t behövs inte längre i URL:en eftersom det finns som ett anspråk i åtkomsttoken.
Problem
POST https://verifiedid.did.msidentity.com/v1.0/verifiableCredentials/createIssuanceRequest
Verifiera
POST https://verifiedid.did.msidentity.com/v1.0/verifiableCredentials/createPresentationRequest
Bifoga åtkomsttoken som en ägartoken i auktoriseringshuvudet i en HTTP-begäran.
Skicka begäran till REST-API:et för begärandetjänsten.
API:et för begärandetjänsten returnerar en HTTP-statuskod 201 Created vid ett lyckat anrop. Om API-anropet returnerar ett fel kontrollerar du dokumentationen för felreferensen.
Exempel på utfärdandebegäran
I följande exempel visas en verifierbar begäran om utfärdande av autentiseringsuppgifter. Information om nyttolasten finns i Rest API-utfärdandespecifikation för begärandetjänsten.
POST https://verifiedid.did.msidentity.com/v1.0/verifiableCredentials/createIssuanceRequest
Content-Type: application/json
Authorization: Bearer <token>
{...JSON payload...}
I följande exempel visas en presentationsförfrågan om verifierbara autentiseringsuppgifter. Information om nyttolasten finns i Presentationsspecifikation för REST API för begärandetjänst.
POST https://verifiedid.did.msidentity.com/v1.0/verifiableCredentials/createPresentationRequest
Content-Type: application/json
Authorization: Bearer <token>
{...JSON payload...}
Nyttolasten för begäran innehåller slutpunkten för utfärdande och presentationsåteranrop . Slutpunkten är en del av webbprogrammet och bör vara offentligt tillgänglig via HTTPS-protokollet. API:et för begärandetjänsten anropar slutpunkten för att informera din app om vissa händelser. Sådana händelser kan till exempel vara när en användare söker igenom QR-koden, använder den djupa länken till autentiseringsappen eller avslutar presentationsprocessen.
I följande diagram beskrivs det anrop som din app gör till REST-API:et för begärandetjänsten och återanropen till ditt program.
Konfigurera slutpunkten så att den lyssnar på inkommande HTTP POST-begäranden. Följande kodfragment visar hur du hanterar HTTP-begäran om återanrop till utfärdande och hur du uppdaterar användargränssnittet i enlighet med detta:
Ej tillämpbart. Välj något av de andra programmeringsspråken.
[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
}
}