Back

Turnkey

Turnkey

passkey-smart-wallet.png
turnkey-passkey.svg
authentication-screenshot.png

Overview

Security Overview: Using Passkeys with AA Wallets with Turnkey

Two Main Methods:

1. Direct On-chain Verification: Here, AA wallets check passkey signatures right on the blockchain.

  • Pros: Users can sign transactions with passkeys directly. No middlemen involved.
  • Cons: This method uses a lot of gas (around 300k gas per transaction). It's too expensive for many. An update like EIP-7212 could make it more affordable.

2. Signing Service Authentication: This is Openfort's current method. Instead of using the passkey to sign transactions directly, it's used to verify with an external service called Turnkey, which then signs the transaction.

  • Pros: Compatible with current wallet systems and uses less gas.
  • Cons: It depends on Turnkey, a centralized service.

Deep Dive: Turnkey's Role

  • What's Turnkey?: It's a third-party service that offers signing infrastructure.
  • How does it work?: Turnkey’s signing infrastructure is deployed in secure enclaves. Each request to sign a transaction using Turnkey must be stamped by an authorized user. Importantly, only your user can authorize Turnkey to process a signature request, by using their passkey. Nobody, including Turnkey, can ever access a raw private key.
  • Main Point: With Openfort, passkeys don’t sign transactions. They authorize requests to sign transactions using private keys held by Turnkey, where the signing occurs within secure enclaves. This setup works well with existing wallet systems and saves gas.

Why Trust This System?

  1. Security: Even Turnkey can't access private keys without the user's passkey. To read more about Turnkey's trust and security model, click here.
  2. Reliability: Turnkey runs on AWS, ensuring great uptime and backup, and their team has built massively scaled private key infrastructure at places like Coinbase and BitGo.
  3. Flexibility: If you're using an AA wallet like Openfort, you can switch from Turnkey to another signer if you prefer a different security method.

In conclusion, while the term "centralized" might worry some, the combination of Turnkey's infrastructure and Openfort's AA wallet can offer a secure and efficient solution for many users.

How it works

This application has two components:

  • the frontend (in frontend is a NextJS app running in browsers. Responsibilities are: serve the UI, make calls to the backend component, and execute passkey interactions (assertions or attestations). Passkey interactions are abstracted through Turnkey JS SDK. This is deployed through Vercel.
  • the backend (main file: index.ts) is an Express application handling requests made by the frontend. It uses the Turnkey JS SDK to interact with the Turnkey API and Openfort Node SDK to interact with the smart wallet. For deployment we use Railway.

Requests and responses use JSON-over-HTTP. Now let's talk about the different flows implemented, one-by-one.

Registration

The frontend uses a whoami endpoint to know whether a user has a current valid session. If not, the user needs to authenticate with a passkey. Let's pretend our user has never registered before: no previous session, no registered passkey!

When authentication happens, the email address entered in the authentication form is used to lookup users on the backend. Because the user is not found, the frontend performs a Webauthn registration ceremony with Turnkey SDK's getWebAuthnAttestation method:

landing workflow

The collected credentials are used as parameters to the Turnkey API to create a new Turnkey Sub-Organization. Each user registering their passkey has their own Turnkey Sub-Organization under the hood. The parent organization has read-only access to each sub-organization, but cannot modify their content or sign crypto transactions with any private keys held within Sub-Organizations.

Signing In

Assuming a user is registered already, they will see a different prompt in their browser's native UI. Here's the authentication prompt in Chrome:

register workflow

Once again, the frontend doesn't have to know anything about webauthn: it uses the Turnkey SDK method getWebAuthnAssertion to collect a signature from the user for a Turnkey "whoami" request for their sub-organization.

The backend then forwards this signed request to Turnkey. If the request is successful, then it means the user is indeed the owner of this sub-organization, and the backend grants a session as a result. The user is logged in!

Mint NFT

For a signed-in user, the dashboard shows functionality to mint an NFT. The amount and destination parameters are POSTed to the backend, the backend requests Openfort to construct an unsigned sponsored payload using gas policies, and the frontend uses this to construct a Turnkey Sign Transaction request. This request is signed via a webauthn assertion (remember, end-users are the only ones able to perform any action in their respective sub-organization!), and forwarded to backend. The backend then grabs the signature and forwards it back to Openfort who puts it on-chain.

Integration workflow

Get started

Get started on an integration here! You can create a Turnkey Organization for free at app.turnkey.com.

For a limited time, Openfort customers can receive discounted volume pricing from Turnkey by sending an email to welcome+openfort@turnkey.com

Details

DocumentationLearn
Live demoExplore

Get started with Turnkey and Openfort.