Documentation and Usage Guide for Internet Identity


Provide descriptions of the protocols involved and developer guidelines for usage and implementation of the Internet Identity blockchain authentication system.


What you can do to help:

  • Ask questions
  • Propose ideas

Key people involved

Maria Dubovitskaya, @kritzcreek @bjoern


I definitely think this is a good priority for giving guidelines from a User Experience perspective. I think a lot of new users might be really confused by the internet identity when they first see it on a site, especially on desktop if they don’t have a bio-metric installed or have a key. Because of this, there should be some guidelines on how to introduce new users to Internet Identity.

I for one had no idea what I was doing when I first signed on. I actually had to order a physical key and wait just to go on a site, because the sign up page made me assume there weren’t other options. Flip side, now I have like 3 different ways in and I love using it!


Hey, I am @bjoern, cryptography researcher at DFINITY and one of the designers behind Internet Identity.

Thank you for your feedback, @Trevor! Dealing with devices that do not support web authentication directly is indeed one of the difficult issues for us (although it became a bit less pressing with the addition of support for Windows Hello). Properly managing cryptographic keys is difficult, and we think that web authentication is generally a great leap forward: the keys are stored in secure chips within devices, and as long as the users take care of managing their devices, there is a very low risk of exposing the keys. We are hesitant to introduce schemes that are more difficult to use.

We are pondering with multiple ideas on how to best deal with the case you described (a desktop computer that does not have built-in web authentication support), since not all users will want to buy an external security key. Possible solutions involve authenticating the sessions via, e.g., the user’s phone, if that supports web authentication, or software solutions such as Krypton, which however does not work with the IC at the moment.

But you’re right that we should have a better explanation of Internet Identity and the requirements it has on the devices – and also where those requirements come from.


On thing that I’ve seen people struggling with is the word identity. People are fine with trusting Google with all their personal information like SSN and bank accounts yet an identity is a stumbling block. Even when it’s made clear that it’s merely a wallet of sorts connected to a device, they aren’t so sure. :man_shrugging:
Not trying to negate any of the awesome work you’ve done just giving honest feedback.

Do I understand correctly that you see the problem in the naming, Internet Identity? Since after all, at least the current version of II is really just a super-charged authentication method for canisters running on the IC (and possibly other services in the future).

It would be great if Internet Identity is opened up for use by any web application outside of IC, which can be great marketing for IC. Plugins, documentation, etc can be developed to make integration easy for web devopers. I asked a question on r/dfinity about this and I got a promising response, only that this needs to be added in the roadmap somewhere:
u/bjoern_DFN :
" There is no inherent technical reason why Internet Identity could not be used by existing web applications – Internet Identity does not block that in any way. That said, the formats we use are pretty specific to the Internet Computer, so this certainly needs a bit of custom work on the side of the relying party/consuming service:

  • The assertion issued by Internet Identity is a canister signature (as defined in this section of the IC interface specification). Validating that assertion requires verifying a BLS signature and checking some paths in a Merkle tree, as described in the interface specification section on canister signatures. That’s all not rocket science, but it’s also not standard functionality available in everyday crypto libraries.
  • The assertion binds to a public key – in first approximation you may think about it as the Internet Identity canister issuing a certificate on a public key provided by the front-end application. This public key is then used for the actual authentication toward the IC – or potentially some server. In the case of the IC, that means signing ingress messages. For other web applications, this may mean signing a challenge provided by the server with that public key.

If there is a community effort to support Internet Identity as an authentication method in traditional web applications, we will happily provide more detailed descriptions, pointers to code in our implementation, etc."

Also, looking at the document internet-identity/internet-identity-spec.adoc at main · dfinity/internet-identity · GitHub

I see “Frontend application can be served by canisters or by websites that are not hosted on the Internet Computer.”

For the various steps detailed out in the document under the section “Client authentication protocol”, is there sample code that shows how this is implemented on a frontend application that websites that are not hosted on the Internet Computer?

1 Like