Blockstack Auth provides single sign on and authentication without third parties or remote servers. On this page, you'll get an overview of authentication from an developer and user perspective.
## User experience flow
Blockstack Auth is a bearer token-based authentication system. From an application user's perspective, Blockstack authentication is similar to legacy third-party authentication techniques that they're familiar with. Applications present users with a **Sign in with Blockstack** button.
Assume a user, Alice, clicks the **Sign in with Blockstack** button on an app. She is
redirected to her copy of the Blockstack Browser. If the user has
signed into the DApp previously. The actual Blockstack sign-in dialog depends on
whether the user already has an existing session in the Blockstack Browser.
<imgsrc="images/kingdom_notin.png"alt="">
Alice can choose to authenticate as one of her Blockstack IDs by selecting the
ID and clicking the **Approve** button. The Blockstack Browser shows Alice an approval dialog with information about your app including:
* The origin your app was served from
* Your app's name
* Your app's logo
* The types of permissions and data your app is requesting
Signing in with an identity is the means by which the user grants the DApp access. Access depends on the scope requested by the DApp. The default `store_write` scope allows the DApp to read the user profile and read/write user data for the DApp. Data is encrypted at a unique URL on a Gaia storage hub.
When she clicks approve, Alice is redirected back to the DApp where she is logged in.
## Application-authentication workflow
For an application developer, the application flow is different from the typical client-server flow used by centralized sign in services (e.g., OAuth). Rather, with Blockstack, the authentication flow happens entirely client-side.
A decentralized application (DApp) and the Blockstack Browser communicate during the authentication flow by passing back and forth two tokens. The requesting application sends the Blockstack Browser an `authRequest` token. Once a user approves a sign-in, the Blockstack Browser responds to the application with an `authResponse` token. These tokens are <ahref="https://jwt.io/"target="\_blank">JSON Web Tokens</a>, and they are passed via URL query strings.
When a user chooses to **Sign in with Blockstack** on a DApp, calls the `redirectToSignIn()` method which sends the user to the Blockstack Browser. When Blockstack Browser is provided an ID, it generates an The browser responds with an authentication token and an _app private key_.
The app private key is application-specific. It is generated from the user's identity address private key using the `appDomain` as input. The key is ephemeral, it is generated for each execution of a key establishment process. This key is just used for the particular instance of the application, in this case to sign a sign-in request.
This app private key is also deterministic, meaning that for a given Blockstack ID and domain name, the same private key is generated each time. The app private key is securely shared with the app on each authentication and encrypted by the Blockstack Browser. The key serves three functions, it:
* is used to create the credentials that give an app access to the Gaia hub storage bucket for that specific app
* is used in the end-to-end encryption of files stored for the app on the user's Gaia hub
* serves as a cryptographic secret that apps can use to perform other cryptographic functions
A Blockstack Core node also generates a public key token which is sent to the
browser as an `authRequest` from the browser to the core node. The signed
authentication request is sent to Blockstack through a JSON Web Token (JWT).
Blocktack passes the token in via a URL query string in the `authRequest`
When the Blockstack node receives the `authRequest`, it generates a session token
and returns an authentication response (`authResponse`) to the application. Similar to the `authRequest`, the `authResponse` token includes a private key
intended only for the application. This allows the application to encrypt data
on user's personal Blockstack storage.
{% include note.html content="The Blockstack JWT implementation is different from other implementations because of the underlying cryptography we employ. There are libraries in <ahref='https://github.com/blockstack/jsontokens-js'>Javascript</a> and <ahref='https://github.com/blockstack/ruby-jwt-blockstack'>Ruby</a> available on the Blockstack Github to allow you to work with these tokens." %}
## Manifest file
Blockstack apps have a manifest file. This file is based on the [W3C web app manifest specification](https://w3c.github.io/manifest/). The following is an example manifest file.
The Blockstack Browser retrieves the manifest file from the app during the
authentication process and displays some of the information in it such as the
app name and icon to the user. The location of the app manifest file is specific
in the authentication request token and **must** be on the same origin as the app
requesting authentication.
The manifest file **must** have [Cross-origin resource sharing (CORS) headers](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing) that allow the manifest file to be fetched from any arbitrary source. This usually means returning a header like this:
```
Access-Control-Allow-Origin: *
```
How you implement cors depends in part on which platform/service you use to serve your application. For example, Netlify and Firebase have two different ways of configuring CORS. Consult your vendor documentation for more information.
## Key pairs
Blockstack Auth makes extensive use of public key cryptography. Blockstack uses ECDSA with the `secp256k1` curve. The following sections describe the various public-private key pairs used in the authentication process including:
* how they're generated,
* where they're used
* to whom the private key is disclosed.
{% include note.html content="The Blockstack JWT implementation is different from other implementations because of the underlying cryptography we employ. There are libraries in <ahref='https://github.com/blockstack/jsontokens-js'>Javascript</a> and <ahref='https://github.com/blockstack/ruby-jwt-blockstack'>Ruby</a> available on the Blockstack Github to allow you to work with these tokens." %}
### Transit private key
The transit private is an ephemeral key that is used to encrypt secrets that
need to be passed from the Blockstack Browser to the app during the
authentication process. It is randomly generated by the app at the beginning of
the authentication response.
The public key that corresponds to the transit private key is stored in a single
element array in the `public_keys` key of the authentication request token. The
Blockstack Browser encrypts secret data such as the app private key using this
public key and sends it back to the app when the user signs in to the app. The
transit private key signs the app authentication request.
### Blockstack ID Identity address private key
The identity address private key is derived from the user's keychain phrase and
is the private key of the Blockstack ID that the user chooses to use to sign in
to the app. It is a secret owned by the user and never leaves the user's
When a user approves a sign in request, the Blockstack Browser will return the signed authentication response token to the `redirectURI` specified in `redirectToSignIn`.
To check for the presence of this token, your app should call `isSignInPending`. If this returns `true`, the app should then call `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`.
