Identity Attributes

[aterga]

Summary

We propose a design that allows sharing attributes associated with an Internet Identity (II) with the app a user is signing into, upon their agreement. This enables the development of II-powered apps that offer richer features with fewer distractions, such as sending email notifications without requiring most users to confirm their email addresses. Furthermore, II will evolve into a central control panel where users can specify their preferences for sharing identity attributes and with whom.

Implications for Developers

The underlying API closely resembles the one provided by the authClient. Developers who already integrate with id.ai can request attributes such as usernames and emails. The returned attributes will be certified by id.ai, enabling convenient and secure verification against the user’s principal.

Implications for End Users

There will be two distinct attribute-sharing flows:

1. Regular Flow: This begins when the user taps the “Sign in with Internet Identity” button in the app. After a successful sign-in, id.ai will request explicit confirmation for each attribute requested by the app before sharing it.
2. 1-Click Flow: This starts when the user taps, for example, “Sign in with Google (powered by id.ai)”. Upon successful sign-in, id.ai will automatically share basic attributes associated with the corresponding user account without requiring additional explicit confirmation. Note that in this case, implicit consent is a UX optimization, not a removal of user control.

Problem

As you may already know, id.ai now supports users signing in via OpenID using their existing Google, Apple, or Microsoft accounts. To safeguard user privacy, Internet Identity keeps all OpenID data confidential, never sharing it with the apps users interact with. However, when apps require additional user attributes, such as names, to deliver useful services, users often must re-enter the same information across multiple apps. Attributes like emails also necessitate confirmation, creating significant distractions from users’ primary objectives within the app.

Let’s examine why apps need these user attributes to begin with. When users are offline (or not signed into a specific app), they may still want email notifications for relevant events, such as an airdrop arriving in their wallet. Building custom email confirmation flows demands substantial extra effort from app developers. Meanwhile, users signing in with Google, for instance, have already verified a compatible email address through Internet Identity; requiring reconfirmation for the app introduces unnecessary redundancy. Ultimately, this friction hinders seamless onboarding.

Approach

To address this issue, we propose a solution that operates as follows:

• Simple API: Internet Identity introduces a new API enabling apps to request OpenID attributes. This API mirrors the existing mechanism for II-powered apps to request certified principals for user identification. For instance, an app might request an attribute like openid:google:email.
• User Consent: Internet Identity secures user consent for each requested attribute. For example: “The app requests your email address associated with Google; please confirm sharing.”
• Certification: II delivers certified attributes to the app, allowing verification that these attributes belong to the user with a specific principal.
• 1-Click Flow: From the user’s perspective, the 1-click flow initiates by tapping, e.g., “Sign in with Google (powered by id.ai),” which redirects to accounts.google.com (in principle, this could extend to any OpenID provider supported by id.ai, but initially, we prioritize Google as the most popular option). After signing in with the desired account, the user is seamlessly redirected back to the app. In this flow, id.ai can share basic identity attributes (such as email and name) without additional consent, given the clear user intent.

Regular Flow

Let’s explore how identity attributes work in the regular flow based on a concrete example. A user named Bob wants to sign into an app. The app’s business logic relies on the email and the name of the user.

When id.ai processes the ii_attributes request, it proceeds as follows:

1. Bob taps the Sing in button in the app, which requests email and name attributes from id.ai.
2. id.ai directs Bob through the regular sign in flow.
3. Once Bob is signed into id.ai, it informs Bob about the requested attributes, providing previously used values, when available. For each attribute, Bob can either consent to sharing a previously used value, modify the value to be shared, or deny sharing it with the app at this time.
4. Bob consents to share the previous email, but modifies the value of the name attribute to be shared.
5. [not shown on the diagram] II needs to verify the new name, e.g., by comparing it against the user’s OpenID credentials linked to this account. If automatic verification is not possible, II falls back to explicit verification (e.g., “please verify that you have this email”).
6. II forwards the allowed attributes to the app.
7. The app greets Bob by his preferred name and is also able to send emails to Bob’s (verified) email address.

This way, II serves as the control panel for users to specify their intent about how their identity attributes are shared, and with whom.

1-Click Flow

A cornerstone of the design discussed above is that Internet Identity (II) always requires user consent before sharing identity attributes. Typically, this consent is obtained by explicitly prompting the user, as illustrated in the sequence diagram above.

However, in the special case of the 1-click flow, an opportunity arises to further enhance the user experience, as illustrated in the following scenario:

1. A user is onboarding an II-powered app for the first time and selects "Sign in with Google (powered by id.ai).”
2. On the accounts.google.com sign in screen, the user chooses a Google account.
3. Google requests consent to share the email associated with that account with id.ai.
4. id.ai can securely forward that email to the app, without additional explicit consent from the user, since they initiated the 1-click flow with Google, indicating their intent to link one of their Google accounts to the app.

Let’s explore how identity attributes work in the 1-click flow based on a concrete example. Once again, Bob wants to sign into an app that relies on the email and the name of the user. But this time the app provides a dedicated "Sign in with Google (powered by id.ai)” button.

1. Bob taps the Sign in with Google button in the app, which requests email and name attributes (associated with Bob’s Google account) from id.ai.
2. id.ai directs Bob through the Google sign in flow.
3. Upon successful authentication on accounts.google.com, II forwards the requested attributes to the app.

Attribute scopes

Identity attributes that an app can request should maintain consistent values regardless of the user’s chosen sign-in method. For instance, we aim to prevent scenarios where a different user email is selected based on whether they sign in via Google, Microsoft, or passkey. To eliminate ambiguity, attributes may include scopes that specify two elements:

• The attribute’s source (and its semantics; e.g., a Google email differs from a Microsoft email).
• The type of consent the user provides before II can share the attribute.

For now, the only two attributes requestable in the 1-click flow with implicit consent are:

• openid:https://accounts.google.com:email
• openid:https://accounts.google.com:name

Both attributes share the scope openid:https://accounts.google.com, signifying that they pertain specifically to the email address and name associated with the user’s Google account.

Note that for the time being, all other attributes require explicit consent, and scopes from other OpenID issuers generally available in II (Microsoft, Apple) are not covered yet. However, adding other issuers in the future is conceptually simple, at which point one could imagine a streightforward extension of this design in which implicit consent applies if the scope of the requested attributes matches openid:{issuer} for the same issuer that is used in the 1-click flow.

Discussion

Currently, users of II-powered apps must provide similar data across each ICP app they use, often involving redundant actions like email verification. Above, we outlined a vision for how id.ai could implement identity attribute sharing in a privacy-preserving manner, subject to user consent. We welcome community feedback on this design proposal.

As a first step towards implementing this design, we have proposed this feature (proposal/140313) as a pilot for caffeine.ai to gain experience and refine the API, before incorporating feedback and making it available to all II-powered apps. Please let us know if you are developing an app that would like to be an early adopter of identity attributes or the 1-click flow.