UMA + OAuth + Nostr Wallet Connect = UMA Auth
UMA Auth is an extension of UMA which allows users to connect their UMA-enabled wallets to third-party applications. This allows users to
send and receive payments in the currency of their choice from within their favorite apps. It also allows application developers to easily
add payment functionality to their apps without needing to worry about the underlying payment infrastructure.
This is made possible by the Nostr Wallet Connect (NWC) protocol, which was designed to connect Lightning-enabled wallets
to third-party applications via Nostr. UMA auth extends NWC to simplify the UX of connecting a wallet (using OAuth 2.0),
and add cross-currency payments to allow users and applications to transact in any currency they choose.
From a protocol perspective, UMA Auth is a combination of the UMA protocol, OAuth 2.0, and the NWC protocol.
When a user wants to connect their UMA wallet to a third-party application:
- The client app starts a standard OAuth 2.0 flow by redirecting the user to the UMA provider's authorization endpoint.
- The UMA provider authenticates the user and asks for their permission to connect to the client app.
- The UMA provider redirects the user back to the client app with an authorization code as usual in OAuth 2.0.
- The client app exchanges the authorization code for an NWC connection string and refresh token.
- The client app uses the NWC connection string to connect to the user's UMA wallet and start sending and receiving payments.
- The client app uses the refresh token to get a new NWC connection string when the old one expires.
This process utilizes the battle-tested security and familiar UX of OAuth to establish a connection, with the simplicity and
flexibility of Nostr Wallet Connect for sending and receiving payments. Users can configure granular permissions and budgets for each
connected app, and revoke access at any time.
For deeper details on the UMA Auth protocol, see the UMA Auth Protocol Specification.
Nostr (Notes and Other Stuff, Transmitted by Relays) is a decentralized communication protocol built largely by lightning and
bitcoin folks. It is an extremely simple protocol at its core where clients publish signed, timestamped events to relays. Clients
can then subscribe to relays via websockets to receive whatever events they care about. The nostr protocol is open source and
described by a set of “Nostr Improvement Possibilities” (NIPs).
Nostr was originally built for a twitter-style social network, but it has grown far beyond that to describe all sorts of functionality,
from auctions, to wikis, to data vending machines and more. One such
extension is NIP-47: Nostr Wallet Connect. NWC allows users to connect
their lightning wallets to third-party client apps to trigger payments, fetch balance, etc. from within that third-party app.
The NWC spec is very simple:
- The user goes to their wallet or wallet service provider and generates a connection URI with a random secret included. When creating the connection URI, the user can specify permissions, payment budgets, etc. for that URI.
- The user opens the client application and pastes the connection URI to establish a connection.
- The application can use details in the URI to encrypt and deliver requests (via nostr) to the wallet. This connection URI is all that the app needs to trigger transactions or make other requests to the wallet (subject to permissions and budget constraints of the connection).
- The wallet responds via another encrypted nostr event back to the application.
UMA Auth makes steps 1 and 2 here more seamless for users and applications by integrating with OAuth 2.0 to handle the connection
URI generation and exchange. From there, the NWC protocol is used as-is to handle the actual communication between the client app
and the user's wallet.
To make it easier for developers to integrate UMA Auth into their systems, we provide SDKs for both client applications and UMA
providers. We also provide a Docker image that can be used by UMA providers to handle much of the complexity of managing permissions,
budgets, and NWC communication.
See the Client Application Guide for details on how to integrate UMA Auth into your client app.
There are SDKs available for both web and mobile applications. These SDKs help you complete the OAuth flow, make NWC requests,
and handle the complexities of managing refresh tokens.
Implementing UMA Auth without the client SDK is also possible, but it requires you to handle the OAuth flow and NWC communication
yourself. The SDKs are designed to make this process as simple as possible.
See the UMA VASP Guide for details on how to set up your UMA provider to handle UMA Auth.
There are two important tools provided for UMA providers:
- The UMA NWC Docker Image does a ton of the heavy lifting for you. It handles all nostr protocol communication, budget management, connection setup and management UI, etc. It is configurable via environment variables to control UI branding, database storage, supported NWC commands, and more.
- The UMA VASP OpenAPI Schema describes the RESTful API that the NWC image uses to communicate
to the main VASP server. It uses the same sort of functionality that the VASP has already implemented for the UMA standard, so it's
fairly easy to implement once you have UMA built. It simply exposes an API for calls like
pay_invoice
,get_balance
, etc. The model types from this schema are generated and provided as packages in Python, Go, Kotlin/Java, and TypeScript. You can also use the schema to generate your own libraries for whatever framework or language you're using.
While it's not required to use these tools to properly implement the UMA Auth protocol, they can save you a lot of time and effort
by providing a solid foundation to build on.
If you want to try running an example VASP, check out this example implementation
in Python. It's a simple implementation of a VASP that uses the UMA NWC Docker Image to handle all the heavy lifting for Auth. simply
set up the environment config as described in the README.md and then run
docker-compose up --build
to start the the VASP and
NWC servers.You can also use this tester client app to test the VASP implementation. It's a hosted version of the example
react app. You can use it to connect to your
VASP and test the full UMA Auth flow.