This documentation aims to provide a basic understanding of the PRISM Onboard and Authenticate features. These features essentially revolve around the processes of user registration (Onboarding) and proving the identity of a returning user (Authentication), utilizing Decentralized Identifiers (DIDs).

Onboarding

In a traditional website registration process, a user creates an account by providing a unique username and password combination, which the website then stores in its database. When the user returns, they provide the same combination to prove their identity. The website confirms this is the same user who registered previously.

However, the onboarding process with a DID is different. Instead of supplying a username/password combination during registration, the user provides a DID, which the website stores in its database.

This process is facilitated through the PRISM onboarding service. When a user intends to onboard (or is invited to do so), a request is sent to the PRISM onboarding service. This service generates an Onboarding-Request, which is displayed in the user's wallet. If the user agrees to the request, they fulfil it by sending a DID to the PRISM service. This DID is then stored in the PRISM service's database, completing the onboarding process from its perspective.

The DID used in this process could theoretically be a PRISM DID or a PeerDID. However, the current implementation only supports PeerDIDs. Consequently, once the user agrees to onboard, a new PeerDID is generated and stored in the wallet (under contacts).

Additionally, the website may request further information during the onboarding process, such as the user's name or agreement to the terms of service, which it can store in the user's profile.

Authentication

Authentication is the process of demonstrating control over information previously provided to the website. In the case of a DID, you initially left your public keys with the website. Merely showing these keys again is insufficient proof of identity. Therefore, the PRISM authenticate service facilitates a multi-step process to verify your identity.

When the user clicks on the 'Sign In' button, a request is sent to the PRISM authenticate service to generate a Challenge-Request. This request appears in the user's wallet, consisting of a random string of characters which the wallet must sign using the same DID that was used during onboarding. The wallet must then recall which PeerDID was used for which website and automatically display that for signing.

Once signed, the PeerDID, the initial challenge, and the newly created signature are returned to the PRISM service. This service checks if the DID was previously onboarded. If it was, the service fetches the public signing keys from the DID-Document and verifies the signature of the random string. If the signature is valid, the PRISM service considers the user as signed in.

The confirmation of successful sign-in is then relayed back to the website. The website can proceed with additional steps such as issuing a cookie or token. This ensures the user remains signed in while navigating through different pages of the site.

The main value proposition of the PRISM Onboard and Authenticate service lies in its signature checking feature. This alleviates the need for the implementer to delve into the technicalities of SSI, DIDs, and signatures, as the PRISM service manages these aspects. However, implementers must still manage their own user databases and handle the maintenance of user sessions across subsequent requests.

Developers looking to further understand these processes and to integrate their websites with the Blocktrust identity wallet and PRISM Onboard and Authenticate features are encouraged to refer to our detailed documentation.

Try it out!

1. Download the Wallet: Navigate to the "Download and Installation" section on this page and follow the instructions provided. Additionally, make sure to review the "First Setup" guide to ensure a smooth initial setup of your wallet.
   
2. Initiate Registration: Visit the website where you want to register with your DID. Typically, you will find a "Register" button at the top right of the page. Click on it to start the registration process. You can also try it on this site.
   
3. Open Wallet: At this point, the Blocktrust Identity Wallet should automatically open in a pop-up window. This pop-up initiates the PRISM Onboarding process.
4. Check Wallet Requests: In your wallet pop-up, click on menu "Wallet Requests". Here, you'll see various pending requests.
   
5. Select 'Onboard' Request: Among the requests, locate the "Onboard" request. If there are multiple "Onboard" requests (which could happen if you've clicked elsewhere before), cancel all but the most recent request.
6. Register: Review the information provided in the "Onboard" request, and if it all looks correct, click on "Onboard". This action triggers the creation of a new PeerDID, which the wallet will send to the PRISM Onboard service. Please note that this process may take a few seconds to complete.
   
7. Complete Registration: After successfully sending the PeerDID, you'll be redirected to the website's own registration page.
8. Enter Details: Follow the website's registration process, which might involve entering your name and accepting the Terms of Service. With these steps, the onboarding process is complete, but you are not signed in yet.
   
9. Sign In: Now, navigate to the top right of the website and click on "Sign In". The Wallet should pop-up again.
   
10. Select 'Authenticate' Request: In your wallet, this time select the "Authenticate" request.
11. Authenticate: Review the information provided, and then click on "Sign In" within the wallet.
    
12. Access Your Profile: Post successful authentication, you will be automatically signed in and redirected to the website. If you look at the top right of the page, you should now see options to edit your profile or sign out.
    

Troubleshooting

1. Prerequisite for Sign In: If you encounter an orange warning message in your wallet when attempting to sign in, this might be due to not having completed the onboarding process yet. Please ensure that you have successfully onboarded before trying to sign in, as it's a prerequisite in the current design.
2. Sign In Timeout: The current implementation of the "Authenticate" service on our website imposes a time limit on the sign in process. Once you've loaded or refreshed the page with the "Sign In" button, you have a 2-minute window to complete the sign in. If this time limit is exceeded, the sign in process will timeout and you'll have to start over. We are aware of this limitation and are planning to release an alternative implementation in the near future to address it.

Limitations

1. Single Onboarding per Website: At present, our wallet does not support onboarding multiple times on a single page using different DIDs. This means that once you've onboarded to a website, you can't onboard again with a different DID. We recognize this limitation and have added support for multiple onboarding per site to our future feature list.
2. Account Deletion Unavailable: Currently, our website does not offer the option to delete an account. This is a limitation not just on our website, but also on the wallet and the PRISM agent. We are working towards providing this option in future iterations.
3. No Messaging Between Wallet and Website: Although the PRISM onboard and authenticate service uses PeerDIDs, DIDComm itself is not employed as a channel for subsequent messages. This means that there are currently no messages sent between the wallet and the website or vice versa. We are considering the possibilities of introducing this feature in future updates.