Authentication

John Light edited this page Aug 6, 2015 · 15 revisions

Auth UX Overview

  1. Alice views a login form on a site or app and types in her username
  2. Alice clicks "log in"
  3. Alice gets a login request outside of the site or app (according to her preferences)
  4. Alice approves the login request
  5. Alice is logged in

Auth Request Types

OAuth-style Redirects

Alice is redirected to her auth provider (which she specified in her profile information) then approves the request, then is redirected back to the app and logged in.

Deep-linking On Mobile

Alice is deep-link redirected to her auth app. She then approves the request on her app and gets deep-link redirected back to the original app and logged in.

Push Notifications

Alice receives a push notification on the auth app on her device. It is routed through her auth provider which powers the push notifications for her auth app. She reviews the auth request, approves it, and is logged in.

Desktop Login w/ Browser Extension

If the app requires no data, Alice is simply logged in. Otherwise, Alice is shown a view where she approves the request and is logged in.

Manual Signatures

Alice is presented with a challenge message to sign. She signs it in her bitcoin wallet and then pastes it in the field and clicks enter.

Note: this is included mainly to demonstrate that the auth request handling could be done manually, in a similar fashion to http://bitid.bitcoin.blue/login.

Auth Mechanics

  1. the app with a login view (the protected app) loads a library that generates the login form
  2. the user types the username into the form and clicks submit
  3. the protected app issues a call to the blockchain for the user's preferred auth type and auth details
  4. the protected app routes the auth request to the user
  5. the user reviews the auth request (the authentication app) and confirms or denies the request, signing an appropriate message to indicate the action chosen
  6. the user's authentication app delivers the response to the protected app's request
  7. the protected app receives the response to the auth request
  8. the protected app analyzes the auth response, then if the response includes a valid affirmation message, the user is logged in; otherwise, the user is denied entry

Verifying Auth Requests

  1. the signing app reviews the signed auth request and determines the public key of the protected app
  2. the signing app looks up the public key in the blockchain and determines the identity of the app that corresponds to that public key
  3. the signing app shows the user the profile information associated with the public key (including the name of the app and the app's image) in order to give user confidence in the app that it's about to log into

Verifying Auth Responses

  1. the protected app reviews the signed auth response and determines the public key of the signer
  2. the protected app looks up the username of the original user that attempted to log in and checks to make sure that the public key of the signing keypair is one of the user's authorized keys
  3. the protected app briefly displays the user's blockchain ID to demonstrate to the user that he/she was properly authenticated and the app knows who he/she is
  4. the protected app logs the user in

Auth Request Format

The protected app produces and signs an auth request message, then dispatches it to the signing app.

Auth request required info:
  • host name (app domain)
  • response URI
  • user blockchain ID
  • signature

Note: The user blockchain ID is included to communicate the app's intent/request to login a particular user. Keep in mind that some auth apps may have multiple identities.

Auth request optional info:
  • app name
  • app image URI
Example
blockchainID://?hostname=&responseURI=&userBlockchainID=&appName=&appImageURI=&signature=
Alternative request format

Instead of providing an hostname, response URI, app name and app image URI, an app can provide an app blockchain ID, which the client can then use to lookup information about the app in the blockchain. This ensures that a given app has a consistent identity and doesn't try to send different information to different users. It also allows apps to verify domains, Twitter accounts, and Facebook accounts to provide additional trust.

Example
blockchainID://?appBlockchainID=&userBlockchainID=&signature=

Auth Response Format

Auth response required info:
  • signature
Auth response optional info:
  • requested user info

Response Routing

Browser auth extension to desktop web protected app

The protected app is required to have either an API endpoint or a form to submit

Auth website to desktop web protected app

The protected app is required to have either a redirect endpoint to receive the response (in query parameters or POST data parameters) or an API endpoint to receive the response outside of a normal redirect.

Mobile auth app to mobile web protected app

The protected app is required to have either a redirect endpoint to receive the response (in query parameters or POST data parameters) or an API endpoint to receive the response outside of a normal redirect.

Mobile auth app to desktop web protected app

The protected desktop app is required to have an API endpoint to receive the auth response.

Mobile auth app to mobile protected app

The protected app is required to have either an API endpoint or a deep-linking handler in the SDK.

SDK Details

The front-end SDK should be connected to the auth API endpoint via web sockets.

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.