samuelgoto
commented
1 year ago That’s a great question, and one that deserves some active exploration.
I think it is very important to acknowledge that is still an open question. There are many ways to go about this that we noted in this Alternatives Considered section. Most notably, introducing new Credential Manager Credentials, like an MDocCredential and a VerifiableCredential, or a WalletCredential to unify the two but keep them separate from IdentityCredential.
But, just to give you a sense of the intuition, here some of the common user journeys that I think are compelling:
- I’m a student at Purdue University. I have my student login with the university’s system as well as my Student ID card in my Apple Wallet. When I need to do my research, I access https://nature.com to read papers, which require me to prove my affiliation to Purdue before giving me access to the content. Some students carry their Digital ID in their wallet, some do not. https://nature.com/ should have a way to degrade gracefully to their federated system when they don’t.
- I’m an employee at Good Corp. I have my Good Corp corporate login as well as my digital badge in my Samsung Wallet. I use figma.com to design UX mocks, which requires me to prove my employment status before giving me access to confidential Good Corp corporate files in figma.
- I’m an American citizen accessing my taxes on https://irs.gov. Last year, I created an account on https://id.me, but I forgot my password. Recently, I uploaded my mobile driver’s license to my Samsung Wallet, which I’d like to use to access my taxes.
- I’m a 18+ yo college student who wants to use tiktok.com. I don’t drive yet, so I don’t have a driver’s license in my wallet, but I do have a social media account, which I’d like to use to access tiktok.com.
I think some of the common technical characteristics of providers of identity credentials share are:
- Selective Disclosure: The ability to specify what’s being requested by the website (e.g. the user’s age bracket, the user’s name, the user’s profile picture, etc)
- The ability to specify the supported response type / format of the credential in the holder (e.g. mdoc, idtoken, vc)
- The ability to specify how to invoke the holder (e.g. retrieve from the device or fetch it from the cloud)
- The ability to pass arbitrary opaque parameters to the holder (e.g. nonces, retention, etc)
There are many architectural components that I think is similar between federation and wallets:
- Every provider registers with a platform registry a summary / representation of their credentials
- The representation of the credential is normalized / common across all provider types. It contains common and interchangeable attributes like:
- An interchangeable Visual representation, for example field like “title”, “subtitle”, “description” and “icon” that can be used to create a uniform selector across identity credential types
- An interchangeable Filtering/Matching representation to be queried against
- The platform is responsible for credential selection, but gets out of the way after that, delegating to the holder by passing the request to the holder. The platform allows the holder to pass a response back (which the platform does not introspect).
So, for example, in the Student Affiliation user flow, here is how a website would be able to gather either an idtoken from a federated provided or a local credential in a wallet on the device:
// An example of requesting a federated identity or an mdoc
const student = await navigator.credentails.get({
identity: {
// The selector field tells the providers that is being asked.
// It also tells the platform how to filter the registered credentials
// and construct the identity selector.
selector: {
fields: ["name", "email", "photo"],
}
providers: [{
responseType: "saml",
configURL: "https://pudue.edu/fedcm.json",
cliendID: "nature.com",
request: {
// These are opaque fields that are passed to the
// holder after selection.
nonce: "1234",
}
}, {
responseType: "mdoc",
request: {
// These are opaque fields that are passed to the
// holder after selection.
readerPublicKey: "ftl+VEHPB17r2 ... Nioc9QZ7X/6w...",
desiredStorageDuration: {
days: 7,
},
}
}]
}
});Another use case that comes up often is to be able to exchange age brackets. Here is how this could be accomplished on a website that accepts age assertions from high-assurance governments as well as low-assurance social networks.
// An example of requesting a federated identity or an mdoc
const idtoken = await navigator.credentails.get({
identity: {
selector: {
fields: ["age_over_18"],
},
request: {
nonce: "1234",
}
providers: [{
responseType: "idtoken",
configURL: "https://facebook.com/fedcm.json",
cliendID: "tiktok-2343",
}, {
responseType: "idtoken",
configURL: "https://google.com/fedcm.json",
cliendID: "tiktok-10902",
}, {
responseType: "mdoc",
request: {
readerPublicKey: "ftl+VEHPB17r2 ... Nioc9QZ7X/6w...",
desiredStorageDuration: {
days: 7,
},
}
}]
}
});There are many occasions, clearly, that credentials are going to unique available in certain formats, so it is key to make sure that it is possible to ask them in isolation. For example:
// An example of a government-issued drivers license requested in isolation.
const mdl = await navigator.credentails.get({
identity: {
providers: [{
// I'd like to get back an mDoc
responseType: "mdoc",
selector: {
documentType: "org.iso.18013.5.1.mDL",
namespace: "org.iso.18013.5.1",
fields: [
"document_number",
"portrait",
"driving_privileges",
".aamva.organ_donor",
".aamva.hazmat_endorsement_expiration_date",
],
},
request: {
readerPublicKey: "ftl+VEHPB17r2 ... Nioc9QZ7X/6w...",
nonce: "1234",
desiredStorageDuration: {
days: 7,
},
}
}]
}
});Alternatively, there are also many situations when you’d only want to get things from federated providers, so here is what that could look like:
// An example of a federeated identity requested in isolation.
const idtoken = await navigator.credentails.get({
identity: {
providers: [{
// I'd like to get a JWT
responseType: "idtoken",
// Here is what I need
selector: {
fields: ["name", "email" "photo"],
},
configURL: "https://idp.com/fedcm.json",
cliendID: "567",
request: {
// These are opaque parameters that the platform passes to the IdP
opaque: "parameter",
foo: "bar",
nonce: "1234",
}
}]
}
});This is just a draft, but here is an idea of what would look like from a WebIDL perspective:
// IdentityCredential WebIDL
enum ResponseType {};
typedef (
USVString or
IdentityCredentialStructuredSelector
) IdentityCredentialSelector;
// https://fedidcg.github.io/FedCM/#dictdef-identitycredentialrequestoptions
dictionary IdentityCredentialRequestOptions {
// A querying language that allows an RP to ask what it wants from the providers.
IdentityCredentialSelector selector;
required sequence<IdentityProviderConfig> providers;
};
dictionary IdentityProviderConfig {
IdentityCredentialSelector selector;
sequence<ResponseType> responseType;
// maybe the following should be in params
// sequence<USVString> scope;
// USVString nonce;
record<USVString, USVString> request;
};
typedef (
USVString or
IdentityStructuredAttribute;
) IdentitySCope;
dictionary IdentityCredentialStructuredSelector {
optional USVString documentType;
optional USVString namespace;
optional sequence<IdentityScope> scope;
}
dictionary IdentityScope {
optional USVString namespace;
SVString name;
SVString value;
bool optional = false;
}Much like in the Credential Manager spec, APIs are expected to extend the Identity Credential spec.
For example, here is what the FedCM could look like:
// ======= separate and independent spec =======
// FedCM API
// ==========================================
// This is an extension of ResponseType.
// Unfortunately, WebIDL does not support partial enums (yet).
partial enum ResponseType {
"idtoken",
}
partial dictionary IdentityProviderConfig {
// URL for the Identity Provider Configuration.
required USVString configURL;
required USVString clientId;
}
partial dictionary IdentityCredentialSelector {
DOMString loginHint;
DOMString hostedDomain;
}In the same way, a mobile document request could also extend the IdentityCredential spec in the following way:
// ======= separate and independ spec =======
// mDocs API
// ==========================================
// This is an extension of ResponseType.
// Unfortunately, WebIDL does not support partial enums (yet).
partial enum ResponseType {
"mdoc",
}
partial dictionary IdentityCredentialSelector {
// mdocs-specific selection language
}And, similarly, extensions for verifiable credentials could be introduced independently:
// ======= separate and independ spec =======
// VC API
// ==========================================
// This is an extension of ResponseType.
// Unfortunately, WebIDL does not support partial enums (yet).
partial enum ResponseType {
"vc",
}
dwaite
OR13
dlongley
One piece of feedback we've heard is that it seems premature to unify different credential types into
IdentityCredentialif all they're really sharing is anonceandresponseand if theIdentityCredentialRequestOptionsis simply a list of unrelated queries.On the one hand, the main reason we want to unify is so that we can enable credential-picker UIs which list different types of identity credentials all together. This doesn't actually require any unification beyond a common API call (or some other way to group multiple calls into a single UI transaction).
On the other hand, there are actually things we expect to be in common, so perhaps it's worth trying to sketch that out in more detail. In particular, is it useful to think of different layers in the identity-verifying application stack and ask if abstraction can help simplify the design of some components (including the browser itself). Eg. if we add abstraction across selective disclosure, filtering and/or UI presentment of disparate credentials, does that provide sufficient concrete benefit to justify the abstraction?