How to configure a Custom domain

Custom domains represent your known and trusted brand, and can assist in instilling trust with your end-users when they interact with your MATTR VII tenant.

Prerequisites

You must have an existing web domain.
You must have control over this web domain DNS records.
You must have a web service that runs on your web domain and can redirect or proxy requests.

Overview

Configuring a custom domain for your MATTR VII tenant comprises the following steps:

Create custom domain configuration.
Insert verification token into custom domain TXT record.
Verify custom domain.
Create redirects for required assets.
Create a new did:web to identify the custom domain.

Create a custom domain configuration

This step can be performed either using either using the MATTR Portal or by making an API request.

Expand the Platform Management menu in the navigation panel on the left-hand side.
Select Custom domain.
Enter a meaningful name in the Name textbox (e.g. "My Custom Domain").
Insert a suitable URL in the Logo URL textbox (e.g. https://my-custom.site/logo.png):
- URL must be publicly available.
- Must be a square image.
- png and jpg files are supported.
- Recommended size is 64x64 px.
- Recommended maximum size is 15 KB.
Insert your full custom domain in the Domain textbox, leaving out the protocol (e.g. my-custom.site).
Select Create.
Your Custom domain record is created and you must now verify it.
Copy the DNS entry TXT record value from the displayed record. You will need it in the next step.

Make a request of the following structure to configure your custom domain:

Request

POST /v1/config/domain

Request body

{
  "name": "Custom Site",
  "logoUrl": "https://my-custom.site/logo-social.png",
  "domain": "my-custom.site"
}

name : Insert a name for the custom domain that will be displayed to digital wallet holders when they receive credential offers or verification requests from your MATTR VII tenant.
logoUrl : Insert a URL for a logo that will be displayed to digital wallet holders when they receive credential offers or verification requests from your MATTR VII tenant:
- URL must be publicly available.
- Must be a square image.
- png and jpg files are supported.
- Recommended size is 64x64 px.
- Recommended maximum size is 15 KB.
domain : Insert the full custom domain, leaving out the protocol (e.g. https://).

Response

Response body

{
  "name": "Custom Site",
  "logoUrl": "https://my-custom.site/logo.png",
  "domain": "my-custom.site",
  "verificationToken": "a45ba33b-6c47-4349-7d49-a516c4d38406", 
  "isVerified": false
}

verificationToken : This value must be added to your domain DNS entry TXT record in step 2.
isVerified : This will indicate false until the domain has been verified as described in step 3. MATTR VII will only use the custom domain after it has been verified and this field indicates true.

Once the configuration is created, it is added to your tenant's manifest.json file. This is one of the files you will need to create redirects to.

Insert verification token into custom domain TXT record

Insert the DNS entry TXT record (verificationToken) obtained in step 1 into a TXT record in your custom domain DNS entry.

This TXT record must exist on the domain indefinitely while using the MATTR VII platform.

The exact steps to perform this will vary depending on your DNS service providers:

Troubleshooting

If you can't set a TXT record for your custom domain because it already has a CNAME record, you can workaround this issue by performing the following:

Remove the CNAME record.
Add a TXT record with the correct verificationToken.
Verify your custom domain.
Remove the TXT record.
Return the CNAME record.

Verify custom domain

Once your DNS provider has registered your TXT value and the change has been propagated, MATTR VII must reach out to the public DNS record and confirm the value matches the one set up on your tenant.

This step can also be performed either using either using the MATTR Portal or by making an API request.

Expand the Platform Management menu in the navigation panel on the left-hand side.
Select Custom domain.
Select the Verify button in the Verification status panel.
MATTR VII will attempt to verify your custom domain by checking the TXT record you created in step 2. Upon successful verification, the displayed status should change from Not verified to Verified.

Make a request of the following structure to verify your custom domain:

Request

POST /v1/config/domain/verify

Response

204 : (with no body): Verification successful! Your custom domain is now active!
400 : Something has gone wrong with the DNS setup. It could be that you need to wait longer to ensure your TXT record has propagated or repeat the process to verify domain ownership.
404 : No custom domain configured on the tenant. Return to step 1 and configure a custom domain.

Create redirects for required assets

For your custom domain to function properly, you will need to setup redirects to assets that are hosted on your MATTR VII tenant. Different redirect are required based on features used as part of your implementation:

Asset path	Description	Required
`/manifest.json`	This file is required to provide digital wallet clients with information about your custom domain, such as its name and logo.	Always
`/.well-known/did.json`	This is the `did:web` document associated with your domain. It must be available for your `did:web` to be resolvable.	Only when issuing CWT and/or JSON credentials
`/.well-known/did-configuration`	This file is used to establish trust in the DID to domain linkage. This will ensure any digital wallet clients can resolve DIDs from your custom domain and verify the DID-to-domain linkage.	Only when issuing CWT and/or JSON credentials
`/.well-known/openid-credential-issuer`	This file includes details required for interacting with your tenant as part of an OID4VCI workflow.	Only when issuing credentials using the OID4VCI workflow
`/.well-known/oauth-client`	This file includes details required for interacting with your tenant as an Oauth client as part of an mDocs online verification workflow.	Only when verifying mDocs remotely

For example, if we were to set up example.com as a custom domain for the Learn MATTR VII tenant, we would need to create the following redirect for /manifest.json :

Origin	Redirect target
`https://example.com/manifest.json`	`https://learn.vii.au01.mattr.global/manifest.json`

Once this redirect is setup, users attempting to interact with the custom domain will be served the asset from the Learn MATTR VII tenant.

If any of the redirect paths are already used by your main website, you may need to create a separate subdomain for your MATTR VII custom domain.

Create a new did:web to identify the custom domain (Optional)

This step is only required if you are using your MATTR VII tenant to issue CWT or JSON credentials.

When using your MATTR VII tenant to issue CWT or JSON Credentials, you must have a publicly available and resolvable did:web that identifies this tenant as an issuer.

When configuring a custom domain, you must create a new did:web that references the URL of your custom domain instead of your actual MATTR VII tenant. This means that when holders attempt to claim credentials issued by your MATTR VII tenant, they will see your custom domain as the issuer's identifier.

Create a did:web and use your custom domain as the url in the request body.

MATTR VII will automatically host the generated DID document on your tenant, and make it available for any relying party attempting to resolve this did:web.