Microsoft has launched ION hosting (beta) on Bitcoin Mainnet, and has started preview for verifiable credentials service (private preview) on Microsoft Entra Verified ID (Azure AD Verifiable Credentials).
ION is an open source and permission-less, Decentralized Identifier (DID) network, which runs on Sidetree protocol. (See here for ION network.)
On contrary, verification credentials (VC) handles the workflow of proofs and assertions between users, issuers, and verifiers. Verifiable credential services in Microsoft runs on ION network.
For instance, in our real physical world, the users will submit one’s proofs, such as, student’s ID card, driver’s license, so on and so forth, for getting some kind of permissions. This process will be achieved between the users and some proven parties, such as, public organizations, schools, companies, and other agencies.
The flow of digital verification credentials handles the same manners along with W3C open standard specification (see here).
In this post, I’ll show you the outline (the concepts and flows) of verifiable credentials (VC) with several payload examples in Microsoft Verifiable Credential services.
Note : The payload written in this post are examples in Microsoft Entra Verified ID (Azure AD Verifiable Credentials) private preview on June 2020. The detailed payload might be changed in the future release.
However, it will help you to understand the outline of decentralized credential flow.
Before starting, I have several notices.
In the perspective of W3C specification, verifiable credential (VC) doesn’t rely on DID specification. (i.e, The “id” property used in VC shouldn’t be necessarily a DID.) However, in its real implementations, it might be expected that verifiable credentials will resolve DIDs with consistent decentralized manners and technologies. We then also assume that DID is used with verifiable credentials in this post.
In order to make things clear, I’ll include not only VC flows, but also other parts of flows, such as, DID flows or OpenID compliant flows. I note that I won’t explicitly separate these descriptions in this post.
For details about exact W3C specification of verifiable credentials, see “Verifiable Credentials Data Model 1.0“.
Users (Holders), Issuers, and Verifiers
Before starting, here I’ll show you the base concepts and ideas of Verifiable Credentials.
Imagine that you will get the discount for students in some specific service.
In this scenario, you will receive the student ID card from your belonging school (agency), and submit this card to this service provider. This service provider will see your card and verify whether it’s a correct (valid) ID – i.e, this ID is surely issued by an existing agent (school) – and it’s surely issued for you.
In general scenarios, there will exist multiple issuers and verifiers. Then the holder (the user) might submit not only one credential but also more credentials for verifiers.
The credential issued by issuer (authority) is called a verifiable credential. The verifiable credential will include not only ID (in this post, we assume id has a DID format), but also other attributes called claims, such as, degree, major, badge, and so on. When one or more credentials are requested by verifiers (service providers), the holder will assemble collections of verifiable credentials (which might be issued from different issuers) into a single artifact, called a verifiable presentation.
Credential Format
Both verifiable credentials and verifiable presentations are tamper-evidents, in which authorship and non tampering are proved by digital signatures. These format can be either of JWT (including both Json and Json-LD) or Linked Data Proofs (LD-Proofs).
Throughout this post, I’ll explain using a JWT format (plain Json).
As I explained in my early post about Microsoft Entra ID (see here), JWT consists of the following components. (Below is an example of JWT used in OAuth.)
- JWT has 3 string tokens delimited by the dot (.) character.
- Each delimited tokens (each 3 string tokens) consists of :
- Meta information about key :
e.g, the type of key, key id, X.509 Thumbprint, and so on. - Claims :
e.g, subject (sub), issuer (iss), expiration (nbfandexp), so on and so forth. (It depends on the applications.) - Digital signature :
A digital signature signed by a private key. This is a byte code, not UTF string.
- Meta information about key :
- Each delimited tokens should be encodes by Base64 URL encoding (encoded by RFC 4686), which is the Base64 string replaced with : “+” to “-“, “/” to “_”, and removed all “=” characters in its termination.
By verifying a digital signature with public key, you can ensure that this JWT is signed by the correct user (or agent) who has a private key.
If the claims will be changed, the digital signature should also be changed. Therefore, you can also ensure that these claims are not tampered by malicious programs.
For simplicity, we only focus on the above 2nd token (i.e, JWT claims) in this post. (Remember, the entire message will be signed by issuers, holders or verifiers, as I mentioned above.)
With DID ecosystem, a digital signature can be verified using public keys in DID network without any specific servers or providers. (See here for details.)
Note : The payload in JWT will be easily parsed with https://jwt.io/ .
Run Issuer
First of all, the issuer registration will be needed in verifiable credential’s system.
All issuers, holders, and verifiers should have corresponding cryptographic key pairs.
There’ll exist multiple issuers, so each issuer will have the corresponding id (DID) and corresponding key pairs.
These will be managed and shared in decentralized platform, such as blockchain and content addressable store (CAS). (See this post for how ION manages these keys in bitcoin and sidetree.)
For example, in Verifiable Credentials Service on Microsoft Entra Verified ID, you can register your own issuer with cryptographic key pairs (which are stored in your key vault on Azure) by configuring the required settings in the Azure Portal. (See Verifiable Credential document for details about settings.)
Note : When you’re using Verifiable Credentials Service on Entra Verified ID, you can see whether DID is active or not, by online ION explorer or connecting
https://beta.discover.did.microsoft.com/1.0/identifiers/{your DID}.
Unlike this post, this DID format (in VC Service on Azure AD) is a long-formed DID.
Issuance
Once the issuer is ready, now we can start to issue a verifiable credential for user (holder).
There will be needed several steps for issuing new verifiable credential with decentralized identifiers (DID).
First, the user (holder) should generate key pairs (both private key and public key) for user’s DID. (In ION, secp256k1 with ECDSA algorithm should be used. See here.)
The private key will be saved on user’s wallet, and this key will be used for generating a signature. This wallet should be the secure personal storage, such like a local storage on browser, a device app (Authenticator), an isolated desktop application, so on and so forth. (In the complete system, this key can be backed-up or duplicated in secure storage, since it’s crucial for you.)
The public key is registered into the DID network, and everyone can use this public key for verifying user’s signature.
Now the issuer can register this user’s key and issue user’s verifiable credential (VC).
In the real system, the issuer will have to check whether the user is allowed or not. This process is not described on the specification and the implementation depends on each corresponding systems. For instance, in order to run this validation on Microsoft Entra Verified ID, open-id compliant providers can be registered as trusted providers in issuer, and the user should submit id token, which is issued by this trusted open-id provider.
The following is the example of json payload of VC, which is issued by Entra Verified ID.
The following iss is issuer’s DID, and the sub is user’s DID.
As I mentioned above (see my description about JWT), this payload will be signed using issuer’s key (i.e, issuer’s DID, did:ion:EiBz3b8v9c...) and formatted as a JWT. Therefore the users (holders) cannot change these claims (such as, “degree”, “major”, …) by their wills. It means that this credential is proved to be surely issued by this agent.
{
"vc": {
"@context": [
"https://www.w3.org/2018/credentials/v1",
"https://beta.did.msidentity.com/v1.0/1f659db9-9812-4c4d-b958-405e30571b65/verifiableCredential/contracts/TestCredential01"
],
"type": [
"VerifiableCredential",
"VerifiedCredentialTest"
],
"credentialSubject": {
"givenname": "Tsuyoshi",
"surname": "Matsuzaki"
"degree": "master",
"major": "mathematics"
},
"credentialStatus": {
"id": "https://beta.did.msidentity.com/v1.0/1f659db9-9812-4c4d-b958-405e30571b65/verifiableCredential/card/status",
"type": "PortableIdentityCardServiceCredentialStatus2020"
},
"exchangeService": {
"id": "https://beta.did.msidentity.com/v1.0/1f659db9-9812-4c4d-b958-405e30571b65/verifiableCredential/card/exchange",
"type": "PortableIdentityCardServiceExchange2020"
},
"revokeService": {
"id": "https://beta.did.msidentity.com/v1.0/1f659db9-9812-4c4d-b958-405e30571b65/verifiableCredential/card/revoke",
"type": "PortableIdentityCardServiceRevoke2020"
}
},
"jti": "urn:pic:7e276b5558cc46ad82b461bbe83ec8a0",
"iss": "did:ion:EiBz3b8v9c...",
"sub": "did:ion:EiDYHnvoiz...",
"iat": 1592992800,
"exp": 1595584800
}In this payload, the properties in credentialSubject are claims, and others are metedata.
The claims will depend on each issuers. For instance, I have defined above 4 claims, “givenname”, “surname”, “degree”, and “major”, but some other university’s issuer might have “certificate” or “badge”.
In the verification phase (which I’ll explain later in this post), the verifier might expect some specific types of claims. For instance, some service provider (verifier) might require “age” claim for ensuring that the user is over 20 years old.
The type property in above metadata declares what type of data is this credential. In my example, this credential has the type called “VerifiedCredentialTest”.
Note : In Entra Verified ID, you should define these issuer’s settings (such as, credential type, claims, etc) on rule file. See tutorial for details.
Let’s briefly see this flow using Microsoft Entra Verified ID.
In Entra Verified ID, Microsoft Authenticator app (for both iOS and Android) is used as a wallet application.
First, the issuer shows QR code for the user, which will redirect for starting issuance. When the user reads this QR code and go to this url, the issuer will reply the issuer’s manifest location. The authenticator will then retrieve issue’s metadata and start issuance.
As I mentioned above, open-id compliant provider is used to issue the user’s VC in Entra Verified ID. First, the user should then login to this open-id provider in Authenticator app. (See below.)
Fig : The user should login to current OpenID provider for allowing issuance
After the user has successfully signed into open-id provider, Authenticator app will request the VC issuance to issuer with user’s id token which is issued by open-id provider.
The issuer verifies this submitted id token and issue user’s VC. In this phase, the claims of this open-id token (source token) is mapped into the verifiable credential’s claims. The issuer submits this issued DID into decentralized network, ION. (This registration will take a while, but you can soon use the issued VC, since the long-formed DID is used as DID format in Entra Verified ID.)
The issued VC is displayed as card UI in Authenticator app. (See above.)
Once it’s issued, the user will use this verifiable credential for sign-in (verification), then this source provider (traditional open-id provider) will no longer be used.
Here I don’t go so far, but, in Microsoft Entra Verified ID, all workflows (issuance, verification, …) in verifiable credentials are performed by open-id compliant manners using request_uri, redirect_uri, id_token, so on and so forth. (The used protocol name is “openid://”.)
For details about this open-id compliant flow, see SIOP (Self-Issued OpenID Connect Provider) DID Profile in DIF documentation.
Verification – Authenticate with VC
Next I’ll show you the outline of authentication with issued verifiable credential.
In this scenario, we assume 2 roles, the verifier and the user (holder). (We also assume that the verifier has one’s own key pair.)
First, the verifier (who provides some services) will request the submission of credentials for the user.
Imagine that some verifier might require “age” claim for ensuring the user is over 20 years old. In order to tell the user these requirements, the verifier will specify the type of credentials (such as “VC issued by US gov for some purposes”) to the user in the submission request. As you saw above, this type is the same as type property written in a verifiable credential (in our example, “VerifiedCredentialTest”).
I note that the verifier might request the multiple VCs, i.e, multiple types. (In current identity technology, multiple federations at a time will be impossible though.)
Note : This request will also be expected to be signed by verifier’s DID (corresponding private key), and the user can check whether this request is valid or not using a public key.
After the user has accepted to pass owning credentials to this verifier, the user aggregates the corresponding credentials in one’s wallet and create a submission, called a verifiable presentation. This presentation is signed (as a JWT format) by user’s private key as a tamper-evident. (See below illustrated.)
After the user agent passes a verifiable presentation (JWT) to the verifier, then the verifier will extract user’s public key from DID network and check (verify) the signature to ensure it’s surely generated by this user.
On contrary, all verifiable credentials in this verifiable presentation is signed by the corresponding issuers, and the verifier can then ensure that these are surely issued by the corresponding issuers.
(These public keys are all shared in decentralized network.)
Using metadata and claims in each credentials, the verifier will also check whether the submitted credential is exactly same as the requested type, whether it’s expired or not, and other additional requirements, such as, not underage, having a license, so on and so forth. (These verification will depend on application’s requirements in the verifier.)
If it’s valid, finally the verifier (service provider) will provide the services.
The following is an example of a verifiable presentation in Microsoft Entra Verified ID.
The “eyJraWQiOiJkaWQ6aW9u...” in verifiableCredential property is a JWT string of above verifiable credential (which is signed by corresponding issuer, not a user). If multiple credentials are required, you can add more VCs in this verifiableCredential array in Json.
The iss is user’s DID. As I mentioned above, this entire payload (verifiable presentation) is signed by the user’s private key (i.e, did:ion:EiDYHnvoiz...) and formatted as a JWT.
The aud means “audience”, i.e, verifier’s DID.
{
"jti": "934000f9-1a34-4c38-a9f4-cdfaeb5d35be",
"vp": {
"@context": [
"https://www.w3.org/2018/credentials/v1"
],
"type": [
"VerifiablePresentation"
],
"verifiableCredential": [
"eyJraWQiOiJkaWQ6aW9u..."
]
},
"iss": "did:ion:EiDYHnvoiz...",
"aud": "did:ion:EiCHvJcU0B...",
"iat": 1592992800,
"exp": 1595584800,
"nbf": 1592992800
}I note that these are communicated between Authenticator app and verifier application in Entra Verified ID platform. Therefore, the verification result will have to be synchronized with user’s transaction session (such as, web UI in front of the user).
In sample application (which uses Verifiable Credentials NodeJS SDK), this synchronization is done by using state (which can be used for recording application’s state) in SIOP and web session on server side. (See the source code for details.)
For the source code used in Authenticator app’s side, see the source code of Verifiable Credentials SDK on Android.
In this post, I summarized what is verifiable credential, how it’s used in applications, and how it’s implemented in Microsoft VC service.
This style of identity and credentials are very much like ones in our real physical world. I hope this new credentials backed by decentralized technology will mitigate the impedance mismatch between the real world and the digital world.
Reference :
Microsoft Entra Verified ID documentation
https://docs.microsoft.com/en-us/azure/active-directory/verifiable-credentials/
Categories: Uncategorized
tsmatz 
3 replies »