Custom domain
You can configure a custom domain for your MATTR VII tenant to represent your brand and instil trust
with your end-users. For example, end-users might not feel comfortable claiming a credential issued
from your MATTR VII tenant URL (e.g. https://learn.vii.au01.mattr.global), as they don’t know who
or what MATTR is. Using your own domain might be a better approach.
Custom domains don’t change how you interact with your tenant for administration functions and don’t prevent the existing tenant domain from being accessed.
Since MATTR VII tenants are not exposed to end-users directly, the custom domains model we have implemented does not require full DNS mapping of a custom domain to a tenant (i.e. CNAME or A record). Instead, we allow setting a custom domain and then proving ownership using a TXT record on the DNS record.
Requirements
- Any MATTR VII tenant can only be linked to one custom domain.
- You must be on a MATTR VII paid plan.
- 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.
Process overview
Setting up a custom domain for your MATTR VII tenant comprises the following steps:
- Configure a custom domain.
- Verify domain ownership.
- Verify your custom domain.
- Create required redirects.
Configure a custom domain
The first step is to make an API request to create a custom domain configuration on your MATTR VII tenant. This configuration defines the following:
- Custom domain name (this is displayed to holders as they interact with your tenant).
- Custom domain logo (this is displayed to holders as they interact with your tenant).
- The domain the custom domain is hosted on. You may choose to create a separate subdomain from your main web presence to expose to end-users as part of managing their digital identities, or you may choose to run from your existing main website. The choice may come down to practical implementation details as you will need to setup redirects to certain paths. If these paths are already or likely to be used by your main website, you may want to consider using them under a subdomain.
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.
Verify domain ownership
After configuring your custom domain on MATTR VII, you must provide proof of ownership over the configured domain. To do this you must insert the verificationToken (obtained from the configuration response) into a TXT record in your custom domain DNS entry.
This TXT record will need to exist on the domain indefinitely while using the MATTR VII platform.
Verify your 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.
Create required redirects
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 a 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.