Last updated
Last updated
Sign-in with Ethereum is a great way to enable your users to authenticate using their Ethereum wallet. However, adding it you your application requires adding logic and endpoints for managing sessions, connecting to the Ethereum network, issuing nonces, and verifying signatures. Adding or extending functionality around sign-in (such as signing in on behalf of a Gnosis Safe) can also be tricky to figure out.
This is where SSX comes in! SSX is a library that makes it easy to add SIWE to your application. It handles all the logic and endpoints for you and allows you to easily extend it to add additional functionality such as signing in on behalf of a Gnosis Safe, resolving ENS names, and more.
This guide demonstrates how to add SSX to an application that is already using the SIWE library.
ssx-notepad is a simple example dapp with a simple express backend that stores a note for an authenticated Ethereum user. It is based on the original .
The completed version of the dapp with the modifications can be found here:
To modify ssx-notepad to use SSX instead of SIWE the following files were changed:
src/providers.ts - this file holds the frontend code including the wallet connection logic.
src/index.ts - this file handles the backend logic including the endpoints for signing in and storing the note.
Update/verify your API calls work with the session cookie.
Remove the SIWE library and unused functions/endpoints.
First, you'll need to install SSX and add it you your project:
In src/providers.tsadd the following:
Replace the wallet connection and signing logic with the ssx library (making sure to note the location by using the provided comments):
Check that your application still works as expected. You will have two SIWE calls, the new one from SSX and the existing one.
We will come back to the frontend to connect it and clean up after we add ssx-server.
Now, we'll add install and SSX to the backend server. First, install ssx-server via your terminal.
In src/index.tsadd the following (making sure to note the location by using the provided comments):
Once SSX is live on the server, you can add it to your frontend by adding the providers.server.host field.
Once this is done, you should be able to sign in and get a session cookie from the server using SIWE:
Now that SSX is installed, you can use it to protect express routes instead of req.session.siwe:
Once you've done the above steps, SSX is now installed for your dapp! After this you can do the following:
Remove logic from the frontend that uses the old authentication. Verify that the session cookie is sent with your requests to the server. Test the dapp!
Remove or deprecate old endpoints and logic using the previous SIWE method on your backend.
Remove the siwe dependency.
If following along with siwe-notepad, remove this old code to get user data:
And replace this code to login with only ssx
Adding a flag for ENS resolution will also provide an ENS domain and name if one is set for the account:
The migration from SIWE to SSX is fairly straightforward. The changes can be seen in which was forked from the example. The are:
Add the ssx library to your frontend ().
Replace the wallet connection and signing logic with the ssx library ().
Add the ssx-server library to your backend ().
Create and instantiate an SSX object and middleware ().
Point the frontend SSX client to your SSX backend ().
Use SSX for session authentication ().
You can follow along by forking or cloning and applying them yourself. If cloning siwe-notepad, be sure to add file with an SSX Signing Key.
If you are following by editing siwe-notepad, be sure to remove duplicate variables address and ens, as seen
If following the siwe-notepad example, about required secrets.
SSX has a few great features like signing in on behalf of a Safe, resolving ENS on login, or accessing metrics. To learn more about enabling these features, check out the