Introduction

What does bridgekeeper do?

• Lets you create users
• Authenticates and validates users
• Session Limiting
• Single Sign on
• Two Factor Authentication

Note

All Bridgekeeper APIs are prefixed with /api/auth/v{API version}. The prefix has been dropped from all APIs referred below, refer to Swagger API docs for API usage.

How to create users using bridgekeeper?

• Realm creation

  • Bridgekeeper has a concept of realm, as opposed to publisher in sketches a realm can have multiple domains belonging to one. It's an array of domain hosts stored against the realm. For example: Domains of prothomalo such as en.prothomalo.com, kishoralo.com, bs.prothomalo.com and so on, will be part of the same realm. A user created on any domain would be able to login to all other domains which belong to the realm
  • In order to create a realm in bridgekeeper, we have internal API (details of which you can find in swagger docs for bridgekeeper) or new publisher creation task also supports creation of the realms (editor as well as frontend website)
  • We create different realms for editor and frontend
  • One domain can not belong to more than one realm

• User creation

  • To sign-up a user bridgekeeper provides /signup API
  • A user can have a form account or a social account or both
  • In order for the user to be signed up using social accounts, we store details (essentially, client-id and client-secret) of social apps in oauth_credentials against the realm. It currently supports - google, facebook and linkedin (find more details in read.me for bridgekeeper)
  • An additional flag called dont-login could be sent as true if login is not required after successful sign-up. If dont-login is not sent as part of request body, then default value (false) will be assumed and in response you get a cookie called qt-auth (session cookie or jwt token) which means that the user is logged in

How authentication of users works in bridgekeeper?

• What is JWT-Token and how is it used?

  • Generation: JWT-Token is generated when a user signs up or logs in, this token is used to identify the user's session in bridgekeeper. Refer to the Swagger API docs for all login related APIs.
    • JWT token string consists of three parts - header-info.user-details.secret-signature
  • Validation: Session validation occurs when any Bridgekeeper API calls are made that expect a valid session - get user profile data, session's count, logout, kick all other sessions.
    • Validate call internally verifies the presence of session in the table and signature using passport library
    • In a web application, the qt-auth cookie is set against the domain as a http-only and secure cookie so that it is not accessible by the browser javascript and is sent over https for any URL calls made to the domain. For example, a user logs into https://www.quintype.com, will have a qt-auth cookie set for the domain. Any calls from browser to https://www.quintype.com/* will include the qt-auth cookie. When making a server to server call, manually include the qt-auth cookie header in the API call.
    • Frontend web applications can make a call to /users/me to determine if a user is logged in and accordingly show the login UI. This API validates the session and returns the user profile data if a valid qt-auth exists else returns a 403 - Forbidden http error indicating that no valid session exists.
  • Integration: (with applications like metype, accesstype)
    • Using API /access-token/integrations/:integrationId accepts a qt-auth (used by frontend) or x-qt-auth (used by mobile) in the request to be sent as query param or header respectively, and returns x-integration-token which is also a JWT token (not session cookie) which these apps can utilise as a cross-app authentication token for the given user (for eg. checking associated subscriptions or checking comments)
    • This jwt-token is not present in sessions table

Session Limiting

• Things you need to know

  • Each user can have multiple logged in sessions (on different devices, different browsers) and each unique session is tracked in sessions table
  • In order to limit the number of logged in sessions per user, bridgekeeper provides /kick endpoint, which resets all other sessions of the user except the current session
  • /sessions endpoint provides the number of active sessions per user, this information is also returned in the /login call response
  • Limiting needs to be implemented in the frontend using sessions endpoint (bloombergquint is currently using this feature)

Single Sign on

• SSO signup and login:

  • auth domain
    • This domain is an intermediary where login and signup pages are hosted as per the current workflow
    • As user attempts to sign-up or login, a qt-auth cookie is set on the auth domain
    • Both sso-login and sso-signup calls are made from auth-domain
    • This domain needs to be added to the list of domains for the realm in bridgekeeper realm table
  • /sso-signup endpoint takes request body with additional query params as below:
    • callback-url: Domain where the user wants to be logged in
    • redirect-url: After successful sign-up if user needs to be redirected to some custom page for eg. otp-verification or some welcome page
  • /sso-login [Deprecated] endpoint accepts username/email and password in the request body with additional params. Use /login instead.
    • callback-url: Domain where the user wants to be logged in
    • redirect-url: After successful sign-up if user needs to be redirected to some custom page
  • validate session
    • API endpoint: /sessions/access-token/validate?redirect-url=&access-token=&redirect=
    • Access token is generated and saved in the sessions table, suffixed with expiry time of the token (currently set in bridgekeeper black-knight config as 5mins)
    • It says what it does - validates session that right qt-auth is set for the intended user
    • Redirect query param: This ensures that user gets redirected to the redirect-url after validation, if no value is sent for this, response gives back a redirect-url
  • authenticate
    • Once the user is logged in on the auth domain and qt-auth is set on the callback url, if user wants to be logged in to another domain of the same realm, /authenticate call is made as user attempts to load the new website in the same browser session
    • Endpoint: /authenticate?callback-url=&redirect-url=&auth-page=
    • auth-page parameter:
      • auth-page param is required when user attempts to register/login and there is some failure in the process (for eg. invalid data passed or email already exists), then the user is redirected to this path to reattempt to register/login
      • Auto SSO: When qt-auth is set on one of the domains in the browser and user attempts to open any other domain, authenticate call without auth-page param sets qt-auth on current domain and redirects to the redirect-url

Two Factor Authentication

Authentication for user log in into bridgekeeper. Setup Details.