Memanggil REST API Permintaan Layanan

ID Terverifikasi Microsoft Entra menyertakan REST API Layanan Permintaan. API ini memungkinkan Anda mengeluarkan dan memverifikasi kredensial. Artikel ini menunjukkan kepada Anda cara mulai menggunakan REST API Layanan Permintaan.

Token akses API

Aplikasi Anda perlu menyertakan token akses yang valid dengan izin yang diperlukan sehingga dapat mengakses REQUEST Service REST API. Token akses yang dikeluarkan oleh platform identitas Microsoft berisi informasi (cakupan) yang digunakan REST API Layanan Permintaan 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 terdaftar di 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 tersebut dan kemudian buat rahasia aplikasi.

Mendapatkan token akses

Gunakan alur pemberian kredensial klien OAuth 2.0 untuk memperoleh token akses dengan 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.

HTTP

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

C#

// 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();

Node.js

// 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;
    }

Python

# 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']

Java

// 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	Keadaan	Deskripsi
Wewenang	Diperlukan	Penyewa direktori tempat aplikasi berencana beroperasi. Misalnya: https://login.microsoftonline.com/{your-tenant}. (Ganti your-tenant dengan ID penyewa atau nama.)
ID Klien	Diperlukan	ID aplikasi yang ditetapkan ke aplikasi Anda. Anda dapat menemukan informasi ini di portal Microsoft Azure, tempat Anda mendaftarkan aplikasi.
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 dan dari VerifiableCredential.Create.All.

Untuk informasi selengkapnya tentang cara mendapatkan token akses dengan menggunakan identitas aplikasi konsol, lihat salah satu artikel berikut ini:

• C#
• Python
• Node.js
• Java

Anda juga dapat mengakses permintaan token dengan sertifikat sebagai pengganti rahasia klien.

HTTP

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

C#

// 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();

Node.js

// 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;
    }

Python

# 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']

Java

// 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();

Memanggil API

Untuk menerbitkan atau memverifikasi kredensial yang dapat diverifikasi:

1. Buat permintaan HTTP POST ke REQUEST Service 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
   

2. Lampirkan token akses sebagai token pembawa ke header otorisasi dalam permintaan HTTP.

   Authorization: Bearer <token>
   

3. Atur header Content-Type ke Application/json.

4. Siapkan dan lampirkan penerbitan atau presentasi meminta payload ke isi permintaan.

5. Kirim permintaan ke REQUEST Service REST API.

API Layanan Permintaan mengembalikan Kode Status HTTP 201 Created pada panggilan yang berhasil. Jika panggilan API mengembalikan kesalahan, periksa dokumentasi referensi kesalahan .

Contoh permintaan penerbitan

Contoh berikut menunjukkan permintaan penerbitan kredensial yang dapat diverifikasi. Untuk informasi tentang payload, lihat spesifikasi penerbitan Layanan Permohonan REST API .

POST https://verifiedid.did.msidentity.com/v1.0/verifiableCredentials/createIssuanceRequest
Content-Type: application/json
Authorization: Bearer  <token>

{...JSON payload...}

permintaan penerbitan

Permintaan penerbitan menggunakan alur pengesahan idTokenHint:

{
    "authority": "did:web:verifiedid.contoso.com",
    "callback": {
        "url": "https://contoso.com/api/issuer/issuanceCallback",
        "state": "de19cb6b-36c1-45fe-9409-909a51292a9c",
        "headers": {
            "api-key": "OPTIONAL API-KEY for CALLBACK EVENTS"
        }
    },
    "registration": {
        "clientName": "Verifiable Credential Expert Sample"
    },
    "type": "VerifiedCredentialExpert",
    "manifestUrl": "https://verifiedid.did.msidentity.com/v1.0/00001111-aaaa-2222-bbbb-3333cccc4444/verifiableCredentials/contracts/VerifiedCredentialExpert1",
    "pin": {
        "value": "3539",
        "length": 4
    },
    "claims": {
        "given_name": "Megan",
        "family_name": "Bowen"
    }
}

Dengan tanggal kedaluwarsa

Permintaan penerbitan dengan alur pengesahan idTokenHint oleh yang menetapkan tanggal kedaluwarsa:

{
    "authority": "did:web:verifiedid.contoso.com",
    "callback": {
        "url": "https://contoso.com/api/issuer/issuanceCallback",
        "state": "de19cb6b-36c1-45fe-9409-909a51292a9c",
        "headers": {
            "api-key": "OPTIONAL API-KEY for CALLBACK EVENTS"
        }
    },
    "registration": {
        "clientName": "Verifiable Credential Expert Sample"
    },
    "type": "VerifiedCredentialExpert",
    "manifestUrl": "https://verifiedid.did.msidentity.com/v1.0/00001111-aaaa-2222-bbbb-3333cccc4444/verifiableCredentials/contracts/VerifiedCredentialExpert1",
    "pin": {
        "value": "3539",
        "length": 4
    },
    "claims": {
        "given_name": "Megan",
        "family_name": "Bowen"
    },
    "expirationDate": "2024-12-31T23:59:59.000Z"
}

Untuk kode lengkapnya, lihat salah satu sampel kode berikut:

• C#
• Node.js
• Python
• Java

Contoh permintaan presentasi

Contoh berikut menunjukkan permintaan presentasi kredensial yang dapat diverifikasi. Untuk informasi tentang payload, lihat spesifikasi presentasi Request Service REST API.

POST https://verifiedid.did.msidentity.com/v1.0/verifiableCredentials/createPresentationRequest
Content-Type: application/json
Authorization: Bearer  <token>

{...JSON payload...}

permintaan presentasi

Permintaan presentasi untuk kredensial dengan jenis dan pengeluar sertifikat tertentu:

{
  "authority": "did:web:verifiedid.contoso.com",
  "callback": {
    "url": "https://contoso.com/api/verifier/presentationCallback",
    "state": "92d076dd-450a-4247-aa5b-d2e75a1a5d58",
    "headers": {
      "api-key": "OPTIONAL API-KEY for CALLBACK EVENTS"
    }
  },
  "registration": {
    "clientName": "Veritable Credential Expert Verifier"
  },
  "includeReceipt": true,
  "requestedCredentials": [
    {
      "type": "VerifiedCredentialExpert",
      "purpose": "So we can see that you a veritable credentials expert",
      "acceptedIssuers": [
        "did:web:verifiedid.contoso.com"
      ],
      "configuration": {
        "validation": {
          "allowRevoked": true,
          "validateLinkedDomain": true
        }
      }
    }
  ]
}

Dengan batasan klaim

Permintaan presentasi dengan batasan klaim :

{
  "authority": "did:web:verifiedid.contoso.com",
  "includeReceipt": false,
  "registration": {
    "clientName": "Contoso Job Application Center",
    "purpose": "Provide proof of attended courses"
  },
  "callback": {
    "url": "https://contoso.com/api/verifier/presentationCallback",
    "state": "92d076dd-450a-4247-aa5b-d2e75a1a5d58",
    "headers": {
      "api-key": "OPTIONAL API-KEY for CALLBACK EVENTS"
    }
  },
  "requestedCredentials": [
    {
      "type": "FabrikamCourseCertification",
      "acceptedIssuers": [ "did:web:learn.fabrikam.com" ],
      "constraints": [ 
        {  
          "claimName": "courseCode",
          "values": ["FC100", "FC110", "FC150"], 
        }, 
        {  
          "claimName": "courseTitle",
          "contains": "network", 
        } 
      ],
      "configuration": {
        "validation": {
          "allowRevoked": false,
          "validateLinkedDomain": true
        }
      }
    }
  ]
}

Dengan FaceCheck

Permintaan presentasi dengan FaceCheck. Saat menggunakan FaceCheck, includeReceipt harus salah karena tanda terima tidak didukung saat itu.

{
  "authority": "did:web:verifiedid.contoso.com",
  "includeReceipt": false,
  "registration": {
    "clientName": "Contoso Job Application Center",
    "purpose": "Provide proof of attended courses"
  },
  "callback": {
    "url": "https://contoso.com/api/verifier/presentationCallback",
    "state": "92d076dd-450a-4247-aa5b-d2e75a1a5d58",
    "headers": {
      "api-key": "OPTIONAL API-KEY for CALLBACK EVENTS"
    }
  },
  "requestedCredentials": [
    {
      "type": "VerifiedEmployee",
      "acceptedIssuers": [ "did:web:learn.contoso.com" ],
      "configuration": {
        "validation": {
          "allowRevoked": false,
          "validateLinkedDomain": true,
          "faceCheck": {
            "sourcePhotoClaimName": "photo",
            "matchConfidenceThreshold": 70
          }
        }
      }
    }
  ]
}

Untuk kode lengkapnya, lihat salah satu sampel kode berikut:

• C#
• Node.js
• Python
• Java

Peristiwa panggilan balik

Payload permintaan berisi penerbitan dan presentasi titik akhir panggilan balik. 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 masuk. Cuplikan kode berikut menunjukkan cara menangani permintaan HTTP panggilan balik penerbitan dan cara memperbarui UI yang sesuai:

HTTP

Tidak berlaku. Pilih salah satu bahasa pemrograman lainnya.

C#

[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 kode presentasi pada repositori GitHub.

Node.js

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()
})

Python

@app.route("/api/issuer/issuance-request-callback", methods = ['POST'])
def issuanceRequestApiCallback():
    if request.headers['api-key'] != apiKey:
        return Response( jsonify({'error':'api-key wrong or missing'}), status=401, mimetype='application/json')

    issuanceResponse = request.json
    if issuanceResponse["code"] == "request_retrieved":
        cacheData = {
            "status": issuanceResponse["code"],
            "message": "QR Code is scanned. Waiting for issuance to complete..."
        }
        cache.set( issuanceResponse["state"], json.dumps(cacheData) )
        return ""

    if issuanceResponse["code"] == "issuance_successful":
        cacheData = {
            "status": issuanceResponse["code"],
            "message": "Credential successfully issued"
        }
        cache.set( issuanceResponse["state"], json.dumps(cacheData) )
        return ""

    if issuanceResponse["code"] == "issuance_error":
        cacheData = {
            "status": issuanceResponse["code"],
            "message": issuanceResponse["error"]["message"]
        }
        cache.set( issuanceResponse["state"], json.dumps(cacheData) )
        return ""

    return ""

Java

@RequestMapping(value = "/api/issuer/issue-request-callback", method = RequestMethod.POST, produces = "application/json", consumes = "application/json")
    public ResponseEntity<String> issueRequestCallback( HttpServletRequest request
                                                      , @RequestHeader HttpHeaders headers
                                                      , @RequestBody String body ) {
        ObjectMapper objectMapper = new ObjectMapper();
        try {
            if ( !request.getHeader("api-key").equals(apiKey) ) {
                lgr.info( "api-key wrong or missing" );
                return ResponseEntity.status(HttpStatus.UNAUTHORIZED).body( "api-key wrong or missing" );
            }
            JsonNode presentationResponse = objectMapper.readTree( body );
            String code = presentationResponse.path("code").asText();
            ObjectNode data = null;
            if ( code.equals( "request_retrieved" )  ) {
                data = objectMapper.createObjectNode();
                data.put("message", "QR Code is scanned. Waiting for issuance to complete..." );
            }
            if ( code.equals("issuance_successful") ) {
                data = objectMapper.createObjectNode();
                data.put("message", "Credential successfully issued" );
            }
            if ( code.equals( "issuance_error" ) ) {
                data = objectMapper.createObjectNode();
                data.put("message", presentationResponse.path("error").path("message").asText() );
            }
            if ( data != null ) {
                data.put("status", code );
                cache.put( presentationResponse.path("state").asText(), objectMapper.writerWithDefaultPrettyPrinter().writeValueAsString(data) );
            }
        } catch (java.io.IOException ex) {
            ex.printStackTrace();
            return ResponseEntity.status(HttpStatus.BAD_REQUEST).body( "Technical error" );
        }
        return ResponseEntity.ok().body( "{}" );
    }

Untuk kode lengkapnya, lihat kode penerbitan dan presentasi pada repositori GitHub.

Langkah berikutnya

Pelajari selengkapnya tentang spesifikasi ini:

• spesifikasi API Penerbitan
• Spesifikasi API Presentasi