Skip to content

Commit 7e26e4e

Browse files
0xpulkit0xpulkit
authored
Merge pull request #240 from 0xPolygonID/develop
Sync main from develop
2 parents cd9ece0 + 7bafe7c commit 7e26e4e

File tree

17 files changed

+541
-417
lines changed

17 files changed

+541
-417
lines changed

‎docs/issuer/display-method.md‎

Lines changed: 122 additions & 72 deletions
Original file line numberDiff line numberDiff line change
@@ -1,84 +1,134 @@
11
---
22
id: display-method
3-
title: Display method
4-
sidebar_label: Display method
5-
description: Display method
3+
title: "Creating Custom Display Methods: Enhance Credential Presentation and Branding"
4+
sidebar_label: "Custom Display Methods"
5+
description: "Learn how to create and manage custom display methods in the Privado Issuer Node to enhance the visual presentation of verifiable credentials, maintain consistent branding, and build user trust."
66
keywords:
77
- docs
8-
- polygon id
8+
- privado id
99
- issuer node
10-
- claim
1110
- verifiable credentials
1211
- credential customization
12+
- display methods
13+
- digital credentials
14+
- branding
15+
- ipfs
16+
- layout
17+
- metadata
18+
- credential design
19+
- digital identity
1320
---
1421

15-
import useBaseUrl from '@docusaurus/useBaseUrl';
16-
17-
## Description
18-
19-
To improve credential usage, a client needs to be able to customize the presentation of credentials in user wallets. A standard must be established that will guide the wallet in displaying credential cards. This will improve the user experience and allow issuers to present their own special presentation for credentials.
20-
21-
This tutorial will show you how to create a custom credential representation in a mobile wallet.
22-
23-
## Credential representation configuration
24-
25-
Restrictions:
26-
27-
1. `backgroundImageUrl` and `logo` only support .png and .jpeg formats.
28-
2. Maximum length for `title` is 60 characters.
29-
3. Maximum length for `description` is 120 characters.
30-
31-
To configure the credential representation on the PolygonID wallet, follow the steps below:
32-
33-
1. Upload a background and logo for the credential card to IPFS or an HTTP(s) host.
34-
1. Create a file named metadata.json with the following content:
35-
```json
36-
{
37-
"title": "KYC Country of Residence",
38-
"description": "Know Your Customer Verification",
39-
"issuerName": "PolygonID Issuer",
40-
"titleTextColor": "#f2743a",
41-
"descriptionTextColor": "#f2743a",
42-
"issuerTextColor": "#f2743a",
43-
"backgroundImageUrl": "ipfs://QmecKDMotkM8a6vxw35CB7iHfToBJnzJrPcmA3gHit9jt9",
44-
"logo": {
45-
"uri": "ipfs://QmWkSgmHbKRfhndWqHwVgfVpZSrWNiWZMTHb6k5KxY8ySc",
46-
"alt": "Logo PolygonID Issuer"
47-
}
48-
}
49-
```
50-
<div align="center">
51-
<img src= {useBaseUrl("img/custom-credential-description.png")} align="center" />
52-
</div>
53-
1. Upload the metadata.json file to IPFS or an HTTPS(s) host.
54-
1. Use the API to issue a verifiable credential with information about the display method. You can do this using the issuer-node API:
55-
```bash
56-
POST https://<ISSUER_NODE_ADDRESS>/v1/<ISSUER_DID>/claims
57-
```
58-
Body:
59-
```json
60-
{
61-
"credentialSchema": "https://raw.githubusercontent.com/iden3/claim-schema-vocab/main/schemas/json/KYCAgeCredential-v3.json",
62-
"type": "KYCAgeCredential",
63-
"credentialSubject": {
64-
"id": "<USER_DID>",
65-
"birthday": 19960424,
66-
"documentType": 2
67-
},
68-
"expiration": 1735689600,
69-
"displayMethod": {
70-
"id": "<IPFS_LINK_OR_HTTP_URL_TO_METADATA_FILE>",
71-
"type": "Iden3BasicDisplayMethodV1"
72-
}
73-
}
74-
```
75-
1. Fetch the credential using the PolygonID mobile wallet:
76-
<div align="center">
77-
<img src= {useBaseUrl("img/custom-credential.png")} align="center" />
78-
</div>
79-
80-
Please note that you should replace placeholders like `<ISSUER_NODE_ADDRESS>`, `<ISSUER_DID>`, `<USER_DID>`, `<IPFS_LINK_OR_HTTP_URL_TO_METADATA_FILE>` with actual values as needed for your configuration.
22+
23+
# Custom Display Methods
24+
25+
**What are Custom Display Methods?**
26+
They define how a credential is presented to its holder. For instance, a university may issue digital diplomas in a specific layout (with the university’s logo, official colors, etc.) that is visually appealing. A Custom Display Method ensures consistency and brand adherence across all issued credentials.
27+
28+
---
29+
30+
## Example Use Case
31+
32+
**Scenario**: A company wants to issue secure digital certificates as Verifiable Credentials for its employees' achievements or training. Instead of generic text-based credentials, they want a branded, visually appealing credential that includes:
33+
34+
- Company logo
35+
- Employee photo
36+
- Distinct color scheme
37+
- Signature of the HR manager
38+
39+
By creating a Custom Display Method and referencing it during credential issuance, they ensure each certificate is displayed exactly as intended, maintaining brand identity and professionalism.
40+
41+
---
42+
43+
## Building a Display Method
44+
45+
### Step 1: Fill Out Metadata
46+
1. Open the [Display Method Builder](https://display-method-dev.privado.id/).
47+
2. Enter all required metadata fields (name, description, type, etc.) as guided by the [Display Method Documentation](https://docs.privado.id/docs/issuer/display-method/).
48+
3. Make sure to follow any restrictions or formatting requirements.
49+
50+
![Display Method Builder](../../static/img/display_methods/1.png)
51+
52+
### Step 2: Publish to IPFS
53+
1. After filling out the metadata, click on “**Publish to IPFS**”.
54+
2. The Builder will bundle and publish your Display Method JSON to IPFS.
55+
56+
### Step 3: Obtain the IPFS Link
57+
1. Wait for the publishing response.
58+
2. Copy the IPFS link provided (e.g., `ipfs://...` or `https://ipfs.io/ipfs/...`).
59+
3. This link uniquely references your Display Method and will be used in the Issuer Node.
60+
61+
![Obtain the IPFS Link](../../static/img/display_methods/2.png)
62+
---
63+
64+
## Usage of a Display Method in Issuer Node
65+
66+
### Adding the Display Method to the Issuer Node
67+
1. In your Issuer Node, navigate to the **Display Method** section (go to `/display-methods/create` or click **Create a Display Method**).
68+
2. Fill out the form:
69+
- Provide a **unique name** for the Display Method (e.g., `KYC Age Display Method` or `Employee Achievement Method`).
70+
71+
- Paste the **IPFS URL** from the previous step into the `URL` field.
72+
73+
![Adding the Display Method to the Issuer Node](../../static/img/display_methods/3.png)
74+
75+
3. Save your changes. The Display Method is now registered with your Issuer Node.
76+
77+
### Using a Display Method When Issuing Credentials
78+
1. In the **Issue Credential** flow, enable the **Display Method** checkbox.
79+
2. Select your newly created method from the dropdown list.
80+
3. Once you issue the credential, it will reference your custom Display Method.
81+
82+
![Using a Display Method When Issuing Credentials](../../static/img/display_methods/4.png)
83+
84+
### Setting a Default Display Method for a Schema
85+
1. On the **Schema Details** page in the Issuer Node, find the **Display Method** selector.
86+
2. Choose a default method for that schema.
87+
3. Any credential issued under this schema will automatically use the default Display Method (unless manually overridden).
88+
89+
![Setting a Default Display Method for a Schema](../../static/img/display_methods/5.png)
90+
91+
---
92+
93+
## Editing or Deleting a Display Method
94+
To edit or delete a Display Method, go to:
95+
- The detail page of the Display Method, or
96+
- The list of all Display Methods.
97+
98+
Locate the **edit** or **delete** icons to make changes accordingly.
99+
100+
![Editing or Deleting a Display Method](../../static/img/display_methods/6.png)
101+
102+
---
103+
104+
## API References
105+
106+
Below is a summary of the relevant API endpoints to manage Display Methods and schemas:
107+
108+
### New APIs Added in the Issuer Node
109+
- [**Create Custom Display Method**](https://issuer-node-core-api-testing.privado.id/#post-/v2/identities/-identifier-/display-method)
110+
- [**Delete Display Method**](https://issuer-node-core-api-testing.privado.id/#delete-/v2/identities/-identifier-/display-method/-id-)
111+
- [**Get All Display Methods**](https://issuer-node-core-api-testing.privado.id/#get-/v2/identities/-identifier-/display-method)
112+
- [**Get Display Method**](https://issuer-node-core-api-testing.privado.id/#get-/v2/identities/-identifier-/display-method/-id-)
113+
- [**Update Display Method**](https://issuer-node-core-api-testing.privado.id/#patch-/v2/identities/-identifier-/display-method/-id-)
114+
- [**Update Schema**](https://issuer-node-core-api-testing.privado.id/#patch-/v2/identities/-identifier-/schemas/-id-)
115+
116+
### Updated APIs in the Issuer Node
117+
- [**Get Schemas**](https://issuer-node-core-api-testing.privado.id/#get-/v2/identities/-identifier-/schemas)
118+
- Now returns a `displayMethodID` in the schema response.
119+
- [**Get Schema**](https://issuer-node-core-api-testing.privado.id/#get-/v2/identities/-identifier-/schemas/-id-)
120+
- Now returns a `displayMethodID` in the schema response.
121+
122+
---
81123

82124
## Links
83125

84-
1. [Display method](https://iden3-communication.io/w3c/display-method/overview)
126+
1. [Display Method Info](https://iden3-communication.io/w3c/display-method/overview)
127+
2. [Display Method Builder](https://display-method-dev.privado.id/)
128+
129+
130+
131+
## Conclusion
132+
133+
With these steps, you can create, manage, and apply custom Display Methods to credentials in the Privado Issuer Node. By leveraging custom layouts, organizations, and institutions can ensure consistent branding and meaningful designs for their verifiable credentials. This not only adds professionalism but also improves the user’s trust and recognition of your issued credentials.
134+

‎docs/issuer/issuer-configuration.md‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -95,7 +95,88 @@ then:
9595
* OnChain - `Iden3commRevocationStatusV1.0` and `Iden3OnchainSparseMerkleTreeProof2023` credential status type
9696
* All - All the statuses.
9797

98+
## KMS Configuration
9899

100+
Credentials issued by the issuer node are signed using a private key tied to the identity responsible for issuing them. Each identity can have one or more BabyJubJub (BJJ) type private keys. Additionally, the issuer node supports creating Ethereum-controlled identities, where both a BJJ key and an Ethereum (ETH) key are associated with the identity.
101+
102+
#### Identity Types and State Transitions
103+
- BJJ-Based Identity:
104+
- A BJJ type key is generated for the identity to sign credentials and generate zk-proofs for state transitions.
105+
- A shared ETH type key (imported during setup) is used to publish zk-proofs on-chain.
106+
107+
- ETH-Based Identity:
108+
- Both a BJJ type key and an ETH type key are generated for the identity.
109+
- The BJJ type key is used to signs the credentials.
110+
- Only the ETH type key is involved in state transition.
111+
112+
The issuer node integrates with various key management solutions to create, sign, and store these keys securely. Depending on your setup, here’s an overview of the available options:
113+
114+
| **KMS Service** | **Supported Key Types** | **Purpose** | **Recommended For** |
115+
|------------------------|-------------------------|------------------------------------------|--------------------------|
116+
| HashiCorp Vault | BJJ, ETH | Secure key creation and storage | Production |
117+
| AWS Secrets Manager | BJJ, ETH | Secure key storage | Production |
118+
| AWS KMS | ETH (only) | Secure ETH key creation and signing | Production (ETH only) |
119+
| Localstorage | BJJ, ETH | Local storage for testing | Testing Only |
120+
121+
122+
### HashiCorp Vault
123+
The issuer node integrates with HashiCorp Vault, delegating the creation, signing, and secure storage of both BJJ and ETH keys via a Vault plugin. To configure the issuer node to use Vault as a Key Management Service (KMS), update the .env-issuer file as follows:
124+
125+
```bash
126+
ISSUER_KMS_BJJ_PROVIDER=vault
127+
ISSUER_KMS_ETH_PROVIDER=vault
128+
129+
ISSUER_VAULT_USERPASS_AUTH_ENABLED=true
130+
ISSUER_VAULT_USERPASS_AUTH_PASSWORD=<your-vault-issuernode-password>
131+
ISSUER_KEY_STORE_ADDRESS=<your-vault-url>
132+
```
133+
For detailed steps to configure the Vault plugin, refer to the Docker-based setup in the following repository: [HashiCorp Vault Setup](https://github.com/0xPolygonID/issuer-node/blob/main/infrastructure/local/.vault/scripts/init.sh).
134+
135+
### AWS Secrets Manager
136+
In this configuration, the issuer node handles the creation of private keys, which are securely stored in AWS Secrets Manager.
137+
138+
Update the .env-issuer file as follows:
139+
140+
```bash
141+
ISSUER_KMS_BJJ_PROVIDER=aws-sm
142+
ISSUER_KMS_ETH_PROVIDER=aws-sm
143+
144+
ISSUER_KMS_AWS_ACCESS_KEY=<your-aws-access-key>
145+
ISSUER_KMS_AWS_SECRET_KEY=<your-aws-secret-key>
146+
ISSUER_KMS_AWS_REGION=<your-aws-region>
147+
```
148+
:::note
149+
Ensure the credentials you use have the necessary permissions to access AWS Secrets Manager.
150+
:::
151+
Learn more about AWS Secrets Manager here: [AWS Secrets Manager](https://aws.amazon.com/secrets-manager/.)
152+
153+
### AWS KMS Service (Only for ETH Keys)
154+
Alternatively, AWS KMS can be used exclusively for managing and signing ETH keys, delegating their creation and secure storage to the AWS KMS service.
155+
156+
To configure this setup, update the .env-issuer file as follows:
157+
158+
```bash
159+
ISSUER_KMS_BJJ_PROVIDER=<localstorage | vault | aws-sm>
160+
ISSUER_KMS_ETH_PROVIDER=aws-kms
161+
162+
ISSUER_KMS_AWS_ACCESS_KEY=<your-aws-access-key>
163+
ISSUER_KMS_AWS_SECRET_KEY=<your-aws-secret-key>
164+
ISSUER_KMS_AWS_REGION=<your-aws-region>
165+
```
166+
:::note
167+
Ensure your credentials have the necessary permissions for AWS KMS.
168+
:::
169+
Learn more about AWS KMS service: [AWS KMS](https://aws.amazon.com/kms/?nc1=h_ls)
170+
171+
### Localstorage (For Testing Only)
172+
For testing purposes, both BJJ and ETH keys can be stored locally as flat files. This option is not recommended for production environments due to its lack of security.
173+
174+
To enable this setup, update the .env-issuer file as follows:
175+
176+
```bash
177+
ISSUER_KMS_BJJ_PROVIDER=localstorage
178+
ISSUER_KMS_ETH_PROVIDER=localstorage
179+
```
99180

100181

101182

0 commit comments

Comments
 (0)