6.4 KiB

Raw Blame History

layout	description	permalink
learn	Blockstack developer documentation	/:collection/:path.html

Add Auth to your DApp

{:.no_toc}

The way you can add Blockstack Auth to your DApp depends on whether your app is a modern decentralized Blockstack App where code runs client-side without trusted servers or a legacy client-server app where a server is trusted.

TOC {:toc}

Authentication in Client-side apps

This method is appropriate for decentralized client-side apps where the user's zone of trust — the parts of the app that the user is trusting — begins and ends with the code running on their own computer. In apps like these, any code the app interacts with that's not on their own computer such as external servers does not need to know who they are.

Blockstack.js provides API methods that help you to implement Blockstack Authentication in your client-side app.

Default flow

The preferred way to implement authentication in these apps is to use the default flow. This flow encapsulates authentication behind a few function calls and makes it very fast to get up and running.

The default process use these four functions:

When your app wants to start the sign in process, typically when the user clicks a Sign in with Blockstack button, your app will call the UserSession.redirectToSignIn. This creates an ephemeral transit key, stores it in the web browser's localStorage. Then, the function is used to create an authentication request token. The Blockstack Browser redirects the user to the Blockstack Browser to approve the sign in request.

When a user approves a sign in request, the Blockstack Browser returns a signed authResponse token to the redirectURI specified in UserSession.redirectToSignIn.

To check for the presence of this token, your app should call UserSession.isSignInPending. If this returns true, the app should then call UserSession.handlePendingSignIn. This decodes the token, returns the signed-in-user's data, and simultaneously storing it to localStorage so that it can be retrieved later with loadUserData.

import * as blockstack from 'blockstack'

var userSession = new UserSession()
if (userSession.isSignInPending()) {
    userSession.handlePendingSignIn()
    .then(userData => {
        const profile = userData.profile
    })
}

By default, these method use the store_write scope which allows the DApp to read the user profile and read/write user data for the DApp. To specify a different scope, use a AppConfig object.

Custom flows

Alternatively, you can generate your own transit private key and/or authentication request token using the UserSession.makeAuthRequest function. This function gives you more control over the authentication experience. For example, you can change the sign in experience so that it prompts users who have not yet created a Blockstack identity, to choose a hub URL.

The makeAuthRequest() method takes the following parameters:

transitPrivateKey(String = generateAndStoreTransitKey()): A HEX encoded transit private key.
redirectURI(String = `${window.location.origin}/`): Location to redirect the user to after sign in approval.
manifestURI(String = `${window.location.origin}/manifest.json`): Location of this app's manifest file.
scopes (Array = DEFAULT_SCOPE): The permissions this app is requesting.
appDomain(String = window.location.origin): The origin of this app.
expiresAt(Number = nextHour().getTime()): The time at which this request is no longer valid.
extraParams(Object = {}): Any extra parameters to pass to the authenticator. Use this to pass options that aren't part of the Blockstack authentication specification, but might be supported by special authenticators.

For example, you could use the following code to generate an authentication request on https://alice.example.com or https://bob.example.com for an app running on origin https://example.com.


const transitPrivateKey = generateAndStoreTransitKey()
const redirectURI = 'https://example.com/authLandingPage'
const manifestURI = 'https://example.com/manifest.json'
const scopes = ['scope_write', 'publish_data']
const appDomain = 'https://example.com'

const authRequest = makeAuthRequest(transitPrivateKey, redirectURI, manifestURI, scopes, appDomain)

redirectToSignInWithAuthRequest(authRequest)

Authentication in client-server apps

{% include note.html content="Client-server authentication requires using a library written in the language of your server app. There are private methods in blockstack.js that can be accomplish this on node.js server apps, but they are not currently part of our public, supported API." %}

Using Blockstack Authentication in client-server apps is very similar to client-side apps. You generate the authentication request using the same code in the client as described above.

The main difference is that you need to verify the authentication response token on the server after the user approves sign in to your app.

For an example of how verification can be done server side, take a look at the blockstack-ruby library.