Проверенный идентификатор Microsoft Entra включает REST API службы запросов. Этот API позволяет выдавать и проверять учетные данные. В этой статье показано, как начать использовать REST API службы запросов.
Маркер доступа API
Приложение должно включить действительный маркер доступа с необходимыми разрешениями, чтобы он смог получить доступ к REST API службы запросов. Маркеры доступа, выданные платформой удостоверений Майкрософт, содержат сведения (области), которые REST API Службы Запросов использует для проверки клиента. Маркер доступа гарантирует, что пользователь имеет соответствующие разрешения, чтобы выполнить запрашиваемую операцию.
Чтобы получить маркер доступа, приложение должно быть зарегистрировано на платформе удостоверений Майкрософт и авторизовано администратором для доступа к REST API службы запросов. Если вы не зарегистрировали приложение verifiable-credentials-app, ознакомьтесь с тем, как зарегистрировать это приложение, а затем создайте секретный ключ приложения.
Получение токена доступа
Используйте поток предоставления клиентских учетных данных OAuth 2.0 для получения токена доступа с помощью платформы удостоверений Майкрософт. Используйте надежную библиотеку для этой цели. В этом руководстве мы используем библиотеку проверки подлинности Майкрософт (MSAL). MSAL упрощает добавление аутентификации и авторизации в приложение, которое может обращаться к защищенному веб-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();
В приведенном выше коде укажите следующие параметры:
Параметр
Состояние
Описание
Авторитет
Обязательно
Арендатор каталога, с которым приложение планирует взаимодействовать. Например, https://login.microsoftonline.com/{your-tenant}. (Замените your-tenant идентификатором клиента или именем.)
Идентификатор клиента
Обязательно
Идентификатор приложения, назначенный приложению. Эти сведения можно найти на портале Azure, где вы зарегистрировали приложение.
Секрет клиента
Обязательно
Секрет клиента, созданный для вашего приложения.
Сферы
Обязательно
Необходимо задать значение 3db474b9-6a0c-4840-96ac-1fceb342124f/.default. Этот параметр создает маркер доступа с утверждением ролей и значениемVerifiableCredential.Create.All.
Дополнительные сведения о том, как получить маркер доступа с помощью удостоверения консольного приложения, см. в одной из следующих статей:
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
Чтобы выдать или проверить удостоверения:
Создайте HTTP-запрос POST для REST API службы запросов. Идентификатор арендатора больше не нужен в URL-адресе, так как он присутствует в качестве утверждения в маркере доступа.
проблема
POST https://verifiedid.did.msidentity.com/v1.0/verifiableCredentials/createIssuanceRequest
Проверка
POST https://verifiedid.did.msidentity.com/v1.0/verifiableCredentials/createPresentationRequest
Прикрепите токен типа bearer к заголовку авторизации в HTTP-запросе.
Authorization: Bearer <token>
Задайте для заголовка Content-Type значение Application/json.
Подготовьте и прикрепите полезную нагрузку запроса для выдачи или презентации к телу запроса.
Отправьте запрос в REST API службы запросов.
API службы запросов возвращает код состояния HTTP 201 Created при успешном вызове. Если вызов API возвращает ошибку, проверьте документацию по ссылкам на ошибки .
Запрос презентации с помощью FaceCheck. При использовании FaceCheck includeReceipt должен быть ложным, так как получение квитанции в этом случае не поддерживается.
Полезные данные запроса содержат выдачу и конечную точку обратного вызова презентацию. Конечная точка является частью веб-приложения и должна быть общедоступной через протокол HTTPS. API службы запросов вызывает конечную точку, чтобы сообщить приложению о определенных событиях. Например, такие события могут возникать, когда пользователь сканирует QR-код, использует глубокую ссылку на приложение проверки подлинности или завершает процесс презентации.
На следующей схеме показано, как ваше приложение обращается к REST API службы запросов и как происходят обратные вызовы в ваше приложение.
Настройте конечную точку для прослушивания входящих HTTP-запросов POST. В следующем фрагменте кода показано, как обрабатывать HTTP-запрос обратного вызова выдачи и как обновить пользовательский интерфейс соответствующим образом:
Неприменимо. Выберите один из других языков программирования.
[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
}
}
