You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Verifiable credentials are made up of two components, the rules and display definitions. The rules definition determines what the user needs to provide before they receive a verifiable credential. The display definition controls the branding of the credential and styling of the claims. In this guide, we'll explain how to modify both files to meet the requirements of your organization.
19
+
Verifiable credentials are made up of two components, *rules* definitions and *display* definitions. A rules definition determines what users need to provide before they receive a verifiable credential. A display definition controls the branding of the credential and styling of the claims.
20
+
21
+
This article explains how to modify both types of files to meet the requirements of your organization.
20
22
21
23
> [!IMPORTANT]
22
-
> Microsoft Entra Verified ID is currently in public preview.
23
-
> This preview version is provided without a service level agreement, and it's not recommended for production workloads. Certain features might not be supported or might have constrained capabilities.
24
+
> Microsoft Entra Verified ID is currently in preview. This preview version is provided without a service-level agreement, and it's not recommended for production workloads. Certain features might not be supported or might have constrained capabilities.
24
25
> For more information, see [Supplemental Terms of Use for Microsoft Azure Previews](https://azure.microsoft.com/support/legal/preview-supplemental-terms/).
25
26
26
27
## Rules definition: Requirements from the user
27
28
28
29
The rules definition is a simple JSON document that describes important properties of verifiable credentials. In particular, it describes how claims are used to populate your verifiable credential.
29
30
30
-
There are currently four input types that are available to configure in the rules definition. These types are used by the verifiable credential issuing service to insert claims into a verifiable credential and attest to that information with your DID. The following are the four types with explanations.
31
+
### User-input types
32
+
33
+
The following four user-input types are currently available to be configured in the rules definition. They're used by the verifiable credential issuing service to insert claims into a verifiable credential and attest to that information with your decentralized identifier (DID).
31
34
32
-
- ID Token
33
-
- ID Token Hint
34
-
- Verifiable credentials via a verifiable presentation.
35
-
- Self-Attested Claims
35
+
***ID token**: When this option is configured, you'll need to provide an Open ID Connect configuration URI and include the claims that should be included in the verifiable credential. Users are prompted to 'Sign in' on the Authenticator app to meet this requirement and add the associated claims from their account.
36
36
37
-
**ID token:**When this option is configured, you'll need to provide an Open ID Connect configuration URI and include the claims that should be included in the VC. The user will be prompted to 'Sign in' on the Authenticator app to meet this requirement and add the associated claims from their account.
37
+
***ID token hint**: The sample App and Tutorial use the ID token Hint. When this option is configured, the relying party app will need to provide claims that should be included in the verifiable credential in the Request Service API issuance request. Where the relying party app gets the claims from is up to the app, but it can come from the current sign-in session, from backend CRM systems or even from self asserted user input.
38
38
39
-
**ID token hint:** The sample App and Tutorial use the ID Token Hint. When this option is configured, the relying party app will need to provide claims that should be included in the VC in the Request Service API issuance request. Where the relying party app gets the claims from is up to the app, but it can come from the current sign-in session, from backend CRM systems or even from self asserted user input.
39
+
***Verifiable credentials**: The end result of an issuance flow is to produce a verifiable credential but you may also ask the user to Present a verifiable credential in order to issue one. The rules definition is able to take specific claims from the presented verifiable credential and include those claims in the newly issued verifiable credential from your organization.
40
40
41
-
**Verifiable credentials:** The end result of an issuance flow is to produce a Verifiable Credential but you may also ask the user to Present a Verifiable Credential in order to issue one. The rules definition is able to take specific claims from the presented Verifiable Credential and include those claims in the newly issued Verifiable Credential from your organization.
41
+
***Self-attested claims**: When this option is selected, the user can type information directly into Authenticator. At this time, strings are the only supported input for self attested claims.
42
42
43
-
**Self attested claims:** When this option is selected, the user will be able to directly type information into Authenticator. At this time, strings are the only supported input for self attested claims.
43
+
44
44
45
-
45
+
### Static claims
46
46
47
-
**Static claims:**Additionally we can declare a static claim in the rules definition, however this input doesn't come from the user. The Issuer defines a static claim in the rules definition and would look like any other claim in the Verifiable Credential. Add a credentialSubject after vc.type and declare the attribute and the claim.
47
+
Additionally, you can declare a static claim in the rules definition, but this input doesn't come from the user. The issuer defines a static claim in the rules definition, and it looks like any other claim in the verifiable credential. You add credentialSubject after vc.type and declare the attribute and the claim.
48
48
49
49
```json
50
50
"vc": {
@@ -59,7 +59,7 @@ There are currently four input types that are available to configure in the rule
59
59
60
60
## Input type: ID token
61
61
62
-
To get ID Token as input, the rules definition needs to configure the well-known endpoint of the OIDC compatible Identity system. In that system you need to register an application with the correct information from [Issuer service communication examples](issuer-openid.md). Additionally, the client_id needs to be put in the rules definition, and a scope parameter needs to be filled in with the correct scopes. For example, Azure Active Directory needs the email scope if you want to return an email claim in the ID token.
62
+
To get an ID token as input, the rules definition needs to configure the well-known endpoint of the OpenID Connect (OIDC)-compatible identity system. In that system you need to register an application with the correct information from the [Issuer service communication examples](issuer-openid.md). Additionally, you need to put client_id in the rules definition and fill in a scope parameter with the correct scopes. For example, Azure Active Directory needs the email scope if you want to return an email claim in the ID token.
63
63
64
64
```json
65
65
{
@@ -94,11 +94,11 @@ To get ID Token as input, the rules definition needs to configure the well-known
94
94
}
95
95
```
96
96
97
-
See [idToken attestation](rules-and-display-definitions-model.md#idtokenattestation-type) for reference of properties.
97
+
For more information about properties, see [idTokenAttestation type](rules-and-display-definitions-model.md#idtokenattestation-type).
98
98
99
99
## Input type: ID token hint
100
100
101
-
To get ID Token hint as input, the rules definition shouldn't contain configuration for and OIDC Identity system but instead have the special value `https://self-issued.me` for the configuration property. The claims mappings are the same as for the ID token type, but the difference is that the claim values need to be provided by the issuance relying party app in the Request Service API issuance request.
101
+
To get an ID token hint as input, the rules definition shouldn't contain configuration for an OIDC identity system. Instead, it should have the special value `https://self-issued.me` for the configuration property. The claims mappings are the same as for the ID token type, but the difference is that the claim values need to be provided by the issuance relying party app in the Request Service API issuance request.
102
102
103
103
```json
104
104
{
@@ -130,28 +130,30 @@ To get ID Token hint as input, the rules definition shouldn't contain configurat
130
130
}
131
131
```
132
132
133
-
See [idTokenHint attestation](rules-and-display-definitions-model.md#idtokenhintattestation-type) for reference of properties.
133
+
For more information about properties, see [idTokenHintAttestation type](rules-and-display-definitions-model.md#idtokenhintattestation-type).
134
134
135
-
### vc.type: Choose credential type(s)
135
+
### vc.type: Choose credential types
136
136
137
-
All verifiable credentials must declare their "type" in their rules definition. The type of a credential distinguishes your verifiable credentials from credentials issued by other organizations and ensures interoperability between issuers and verifiers. To indicate a credential type, you must provide one or more credential types that the credential satisfies. Each type is represented by a unique string - often a URI will be used to ensure global uniqueness. The URI doesn't need to be addressable; it's treated as a string.
137
+
All verifiable credentials must declare their *type* in their rules definition. The credential type distinguishes your verifiable credentials from credentials that are issued by other organizations, and it ensures interoperability between issuers and verifiers.
138
+
139
+
To indicate a credential type, provide one or more credential types that the credential satisfies. Each type is represented by a unique string. Often, a URI is used to ensure global uniqueness. The URI doesn't need to be addressable. It's treated as a string.
138
140
139
141
As an example, a diploma credential issued by Contoso University might declare the following types:
140
142
141
143
| Type | Purpose |
142
144
| ---- | ------- |
143
-
|`https://schema.org/EducationalCredential`| Declares that diplomas issued by Contoso University contain attributes defined by schema.org's`EducationaCredential` object. |
144
-
|`https://schemas.ed.gov/universityDiploma2020`| Declares that diplomas issued by Contoso University contain attributes defined by the United States department of education. |
145
+
|`https://schema.org/EducationalCredential`| Declares that diplomas issued by Contoso University contain attributes defined by the schema.org `EducationaCredential` object. |
146
+
|`https://schemas.ed.gov/universityDiploma2020`| Declares that diplomas issued by Contoso University contain attributes defined by the U.S. Department of Education. |
145
147
|`https://schemas.contoso.edu/diploma2020`| Declares that diplomas issued by Contoso University contain attributes defined by Contoso University. |
146
148
147
-
Contoso declaring three types of diplomas, allows them to issue credentials that satisfy different requests from verifiers. A bank can request a set of `EducationCredential`s from a user, and the diploma can be used to satisfy the request. But the Contoso University Alumni Association can request a credential of type `https://schemas.contoso.edu/diploma2020`, and the diploma will also satisfy the request.
149
+
By declaring three types of diplomas, Contoso can issue credentials that satisfy different requests from verifiers. A bank can request a set of `EducationCredential`s from a user, and the diploma can be used to satisfy the request. Or the Contoso University Alumni Association can request a credential of type `https://schemas.contoso.edu/diploma2020`, and the diploma can also satisfy the request.
148
150
149
-
To ensure interoperability of your credentials, it's recommended that you work closely with related organizations to define credential types, schemas, and URIs for use in your industry. Many industry bodies provide guidance on the structure of official documents that can be repurposed for defining the contents of verifiable credentials. You should also work closely with the verifiers of your credentials to understand how they intend to request and consume your verifiable credentials.
151
+
To ensure interoperability of your credentials, we recommend that you work closely with related organizations to define credential types, schemas, and URIs for use in your industry. Many industry bodies provide guidance on the structure of official documents that can be repurposed for defining the contents of verifiable credentials. You should also work closely with the verifiers of your credentials to understand how they intend to request and consume your verifiable credentials.
150
152
151
153
## Input type: Verifiable credential
152
154
153
-
>[!NOTE]
154
-
>rules definitions that ask for a verifiable credential do not use the presentation exchange format for requesting credentials. This will be updated when the Issuing Service supports the standard, Credential Manifest.
155
+
>[!NOTE]
156
+
>Rules definitions that ask for a verifiable credential don't use the presentation exchange format for requesting credentials. This approach will be updated when the issuing service supports the standard, Credential Manifest.
155
157
156
158
```json
157
159
{
@@ -192,11 +194,11 @@ To ensure interoperability of your credentials, it's recommended that you work c
192
194
}
193
195
```
194
196
195
-
See [verifiablePresentation attestation](rules-and-display-definitions-model.md#verifiablepresentationattestation-type) for reference of properties.
197
+
For more information about properties, see [verifiablePresentationAttestation type](rules-and-display-definitions-model.md#verifiablepresentationattestation-type).
196
198
197
-
## Input type: Selfattested claims
199
+
## Input type: Self-attested claims
198
200
199
-
During the issuance flow, the user can be asked to input some self-attested information. As of now, the only input type is a 'string'.
201
+
During the issuance flow, users can be asked to input some self-attested information. As of now, the only input type is 'string'.
200
202
201
203
```json
202
204
{
@@ -227,26 +229,26 @@ During the issuance flow, the user can be asked to input some self-attested info
227
229
}
228
230
```
229
231
230
-
See [selfIssued attestation](rules-and-display-definitions-model.md#selfissuedattestation-type) for reference of properties.
232
+
For more information about properties, see [selfIssuedAttestation type](rules-and-display-definitions-model.md#selfissuedattestation-type).
231
233
232
234
## Display definition: Verifiable credentials in Microsoft Authenticator
233
235
234
-
Verifiable credentials offer a limited set of options that can be used to reflect your brand. This article provides instructions how to customize your credentials, and best practices for designing credentials that look great once issued to users.
236
+
Verifiable credentials offer a limited set of options that can be used to reflect your brand. This article provides instructions how to customize your credentials, and best practices for designing credentials that look great after they're issued to users.
235
237
236
-
Verifiable credentials issued to users are displayed as cards in Microsoft Authenticator. As the administrator, you may choose card color, icon, and text strings to match your organization's brand.
238
+
Authenticator displays verifiable credentials that are issued to users as cards. As an administrator, you can choose card colors, icons, and text strings to match your organization's brand.
239
241
240
242
Cards also contain customizable fields. You can use these fields to let users know the purpose of the card, the attributes it contains, and more.
241
243
242
244
## Create a credential display definition
243
245
244
-
Much like the rules definition, the display definition is a simple JSON document that describes how the contents of your verifiable credentials should be displayed in the Microsoft Authenticator app.
246
+
Much like the rules definition, the display definition is a simple JSON document that describes how the Authenticator app should display the contents of your verifiable credentials.
245
247
246
248
>[!NOTE]
247
-
> At this time, this display model is only used by Microsoft Authenticator.
249
+
> This display model is currently used only by Microsoft Authenticator.
248
250
249
-
The display definition has the following structure.
251
+
The display definition has the following structure:
250
252
251
253
```json
252
254
{
@@ -278,11 +280,11 @@ The display definition has the following structure.
278
280
}
279
281
```
280
282
281
-
See [Display definition model](rules-and-display-definitions-model.md#displaymodel-type) for reference of properties.
283
+
For more information about properties, see [displayModel type](rules-and-display-definitions-model.md#displaymodel-type).
282
284
283
285
## Next steps
284
286
285
-
Now you have a better understanding of verifiable credential design and how you can create your own to meet your needs.
287
+
Now that you have a better understanding of verifiable credential design and how to create your own, see:
286
288
287
289
- [Issuer service communication examples](issuer-openid.md)
288
-
- Reference for [Rules and Display definitions](rules-and-display-definitions-model.md)
290
+
- [Rules and display definition reference](rules-and-display-definitions-model.md)
0 commit comments