Introduction

What does bridgekeeper do?

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

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 in domains column in realm table. 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 column in realm table. 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 saved in sessions table in bridgekeeper database
      • JWT token string consists of three parts - header-info.user-details.secret-signature
    • Validation: User creation, session creation (login), session's count, logout, kick all other sessions
      • Validate call internally verifies the presence of session in the table and signature using passport library
    • Integration: (with applications like metype, accesstype)
      • Accepts a qt-auth (used by frontend) or x-qt-auth (used by mobile) in the request to be send 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 for their own purpose (for eg. checking associated subscriptions or checking comments)
      • This jwt-token is not present in sessions table
    • In development: OTP validation and password resetting

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 endpoint accepts username/email and password in the request body with additional params:
      • 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