Domain linkage
Domain linkage is how an organization proves to UniMe's user that the identity signing a request and the website the user already knows belong to the same party. A verified website is the first thing a user sees about a new connection, so it is the cheapest trust an organization can earn. UniMe, Impierce's open-source European Identity Wallet, checks it from the device, against what the organization publishes, every time the organization connects.
What does domain linkage prove?
Domain linkage proves that the same party controls both a website and a decentralized identifier (DID). The two point at each other: the website hosts a credential signed with the DID's key that names the DID, and the DID document names the website. Anyone can resolve the DID and fetch the website, so anyone can check the link.
The website vouches for the DID and the DID vouches for the website, so only a party that controls both can set it up.
For the user this turns an abstract identifier into something they can judge. They may never have heard of a DID, but they know whether university.example is their university. The standard underneath is the DIF Well Known DID Configuration specification.
What does the user see?
The accept-connection screen shows the organization's website with one of three labels, and the share screen repeats the label before the user hands over credentials.
| Label | Meaning | What UniMe found |
|---|---|---|
| Verified Domain | The organization controls both the website and the DID | A valid DID configuration on the website, signed with the DID |
| Unverified Domain | UniMe could not check | No DID configuration on the website, the website was unreachable, or the DID could not be resolved |
| Untrusted Domain | The check failed | A DID configuration exists but does not hold up, for example the signature or the origin does not match |
The user decides in all three cases. Domain linkage is one way for an organization to earn trust, next to the public credentials it holds and the ecosystems it belongs to, and UniMe never blocks a connection because a website is unverified. See Connections & Trust for the other evidence.
How does UniMe check domain linkage?
UniMe takes the website from the request itself and the DID from the organization's identity, then checks that the website vouches for that DID. It runs the check from the device, so neither the organization nor Impierce learns that a user looked.
- Find the website. For a verifier, UniMe takes the origin of the URL the presentation is sent to. For an issuer, it takes the origin of the credential issuer URL in the credential offer. Paths and query parameters are dropped, so
https://issuer.example/tenants/abecomeshttps://issuer.example. - Find the DID. A verifier's request carries its DID. An issuer is found through the DID document it publishes at
/.well-known/did.json. - Fetch the DID configuration from
/.well-known/did-configuration.jsonat the website's root. If the fetch fails, the label is "Unverified Domain". - Resolve the DID to its DID document, which holds the public keys. If this fails, the label is "Unverified Domain".
- Validate the credential. The configuration must hold a credential of type
DomainLinkageCredentialwhose issuer and subject are both the DID, whose origin is the website, whose signature verifies against a key in the DID document, and which has not expired. One valid credential is enough. If none holds up, the label is "Untrusted Domain".
UniMe also reads the other direction when it checks the issuers of an organization's public credentials: it takes the websites from the LinkedDomains service in the issuer's DID document and validates each of them the same way. An issuer of public credentials needs at least one verified website for its credentials to be shown.
UniCore and UniTrust publish both documents for an organization. See Domain Linkage for UniCore and DNS Setup for a hosted UniTrust.
FAQ
Is domain linkage required to connect with UniMe?
No. A connection goes through with any of the three labels, and the user decides. The organization's DID is required, because UniMe needs it to recognize the organization and to run the checks at all, but the website label is evidence, not a gate.
Does UniMe need a DNS record?
No. UniMe looks at nothing in DNS: it fetches two files from the website over HTTPS, and no registration with Impierce is involved. A hosted UniTrust does need a DNS record on your side, so that your own domain serves those files, see DNS Setup.
Can one DID be linked to several websites?
Yes. The DID configuration can hold one credential per origin, and the LinkedDomains service can list several origins. UniMe checks the origin that the request came from.
Why is the check repeated on every connection?
Because the organization can change its keys, its website or its credential at any time, and the user should see the current state. UniMe stores the last result with the connection and refreshes it on every exchange.
Next steps
Read Connections & Trust for the other evidence UniMe shows, or set up domain linkage with UniCore.