Nomo-ID is a flexible protocol for web3-based authentication, without any passwords. There exist websites that allow a login via Nomo-ID, but Nomo-ID can do much more than logins.
Nomo-ID can be used for linking non-WebOn-websites to a Nomo wallet. As such, Nomo-ID helps to close the gap between the WebOn-world and the world of traditional websites. Following the spirit of Nomo, Nomo-ID is a fully decentralized opensource protocol.
⚠️ If you develop a pure WebOn, then we recommend the Nomo-Auth protocol instead of the Nomo-ID protocol.
- Authenticate on supported websites via QRCodes or deeplinks
- Highly customizable authentication screen; including customized text with markdown rendering
- Support of websockets for an immediate UX-feedback after scanning QRCodes
- Automated sharing of wallet addresses
- Device fingerprinting capabilities
- Support for multiple types of signatures (see details below)
Typically, a Nomo-ID-backend will need to store addresses and verify associated signatures. Nomo-ID offers three different types of address/signature-pairs:
- auth_adr + auth_sig
- xauth_adr + xauth_sig
- ETH-address + eth_sig
To secure a backend, at least one of those address/signature-pairs must be verified (see details below).
auth_adr is a special address that is derived from the user's wallet and the domain of your Nomo-ID-backend.
auth_sig is an “Eurocoin-message-signature" that can be verified with packages like bitcoinjs-message.
See the function verifyMsg as an example for verifying an auth_sig.
⚠️ auth_adrwill change whenever the domain of your Nomo-ID-backend changes! If you rely onauth_adrin a database, then you must never ever change the domain of your backend.
Similar to auth_adr, xauth_adr is also an address that depends on the user's wallet and the domain of your Nomo-ID-backend.
However, xauth_adr can be reused accross different backend-domains in certain situations.
Please study the advanced docs if you plan to use xauth_adr.
eth_sig is an "Ethereum-message-signature" that can be verified with packages like ethers.js or web3.js.
This verification works with the regular ETH-address of the Nomo-user.
See the ethSigDemo as an example for verifying an eth_sig.
⚠️ In order to useeth_sig, your deeplink must include the URL-parameter?tETH=1or similar. This means that the Nomo App will transmit both aneth_sigand an ETH-address to a Nomo-ID-backend.
The sample app showcases a possible workflow for integrating the Nomo App into a web-application. The sample app consists of two parts:
- Server
- Client
The server creates a client nonce and sends it to the frontend. The QR-Code is generated by the frontend and contains the client nonce.
The QR-Code contains a certain URL scheme called Request-URL. The mobile app (client) will be asked to sign requested information within the Request-URL. After signing, the mobile app sends back the requested information to the server via a HTTP request.
The Request-URL contains all the information needed by the mobile app. This includes:
- Back-End location
- Loading Endpoint
- Execute Endpoint
- Parameters
Back-End location: The server address where the back-end is hosted. The backend needs to provide endpoints for the mobile app. The mobile app sends the signed data to the provided endpoints
Scan Endpoint: This endpoint shall be used and implemented by the developer to inform the user about the data to be signed. This information will be displayed to the user before signing the requested data. The Execution Endpoint will be called when the user accepts the signing request
Execution Endpoint: The mobile app is sending the signed data to this endpoint. The signed data can be used by the developer for further implementation
Parameters: The data that can be retrieved from the mobile app:
- Wallet address
- ETH address
- BTC address
- Device hashes
- and more ...
Note: The mobile app is constantly updating. More options will become available for developers.
The following graphic shows a possible workflow for integrating the Nomo app into your application. We will explain the following workflow with a real use case. Assume you want a user to log into your website using the Nomo app. You can read more about Web3 authentication here.
To achieve this, you will need to map a users wallet address to his account data. For this, a QR-Code should be provided where a user can link his device. To link a device a user must first scan a provided QR-Code (contains Request-URL) and sign the requested data. This can be seen as the first step in the figure.
The developer is responsible for creating the valid Request-URL in the front-end. The QR-Code will be displayed in the front-end and must be scanned with the Nomo app.
The next step is to inform the user about the data to be signed. The implementation will be within the qrScanDefault. The library provides the required and optional fields that can be used.
When a user signs the requested data, the qrExecuteDefault will be called. The requested data is available for further implementation. In our use case, the implementation for the device linking needs to be implemented here. The qrScanDefault shall update the mobile app about the success or failure. The library provides the required and optional fields that can be used. In our scenario, the last step shows the update on the mobile app as well as the front-end about the status.
The subfolder nomo-id contains an npm packages that is intended for Nomo-ID-backends.
The package supports developer setting up the described workflow. The library provides interfaces for the qrExecute as well as the qrScan and the required return types.
The core of the library is the authorize() method. This method performs security checks on the implemented qrExecute and qrScan methods and returns the two methods able to be invoked within the back-end endpoints. Additionaly the library provides a mapping for sockets (if used) and the nonce parameter from the Request-URL.
Note: The library will be further implemented in the future!
There exists a Nomo-ID Protocol Testing Page as an interactive showcase. When scanning the provided QRCodes, the page will show the properties that are sent by the Nomo App.