Sign-in Options

You are the person who brings new staff into BigLedger — or you are the new member of staff, looking at the sign-in page for the first time and wondering which of the buttons on it are for you. By the end of this page you will know what each option on that screen actually does, which ones are checked on the server and which are decoration for most tenants, how an invitation turns into a working sign-in, and what multi-factor authentication adds. Setting one person up takes about five minutes plus however long they take to open their e-mail.

Meet GadgetSphere

GadgetSphere Sdn Bhd runs 22 retail branches, an online arm and a distribution company on one BigLedger tenant. About 140 people sign in: branch supervisors on shared tills, the finance team, buyers, the e-commerce team and a handful of accountants from the audit firm each March. Most use an e-mail address and a password. A few of the younger branch staff registered with a mobile number and never gave an e-mail. Three of the directors sign in with Google because it is what they use for everything else. Nobody at GadgetSphere uses multi-factor authentication yet, and the finance manager has been asked to change that for the six people who can post journals.

What the sign-in screen offers

The screen is the same for every tenant. It has one text field, one password field and, below a line reading OR, up to three provider buttons.

Two things the table does not show. The three provider buttons are hidden altogether when the visitor’s location resolves to mainland China. And the buttons appear only after the login page has fetched the provider client IDs — a slow connection shows the password form first and the buttons a moment later, which is normal.

One person, several ways in

BigLedger separates who you are from how you prove it. The developers’ own note on the table says it: a login subject “can be a person, an organization, a virtual user, a cloud resource” and “principal defines how that person can login”.

• A login subject (app_login_subject) is the person: name, main e-mail, main phone, MFA settings. One row per human. In practice every one of the 48,000 subject rows across the 90 tenants is a person; the organisation and cloud-resource kinds the comment describes were never used.
• A principal (app_login_principal) is one way that person can sign in. There are three kinds in use: an e-mail username, a mobile-number username, and an access key for programs (see Authentication). One person can hold all three. A principal is USER_UNCONFIRMED until the person clicks the confirmation link, then USER_CONFIRMED; across the platform about 1,800 principals are still unconfirmed, which is the single most common reason a new person “cannot sign in”.
• A social link (app_principal_provider_app_link_hdr) ties a Google, Facebook, Apple or Microsoft identity to a principal. It is created the first time the person signs in through that provider, never by an administrator.

All of this lives in the platform’s master database, which is what the sign-in page talks to. Each tenant then holds a copy of the subjects who belong to it, refreshed by a background job when the master changes. That is why you will see app_login_subject in every tenant database and why editing it there changes nothing.

The four provider rows a tenant holds (app_login_provider_hdr: Apple, Facebook, Google, and Microsoft SAML on the 34 tenants created after it was added) are a copy of the master list, made once when the tenant was created. Nothing reads them on the tenant side. The comment on the table promises “Facebook, WeChat, Google, LinkedIn, Twitter, Github” — of those, only Facebook and Google ever became rows, and only Facebook and Google have a sign-in endpoint. WeChat has a constant and no code path. LinkedIn, Twitter and GitHub exist nowhere but the comment.

    flowchart LR
  S[app_login_subject<br/>the person]
  P[app_login_principal<br/>e-mail · mobile · access key]
  PW[app_login_password<br/>password hashes]
  X[app_login_subject_ext<br/>name, photo, terms acceptance]
  L[app_principal_provider_app_link_hdr<br/>a Google / Apple / Facebook / SAML identity]
  H[app_login_provider_hdr<br/>APPLE · FACEBOOK · GOOGLE · MICROSOFT_SSO_SAML]
  AH[app_login_provider_app_hdr<br/>client id per provider]
  P -->|subject_guid| S
  X -->|login_subject_guid| S
  PW -.->|subject_guid, no FK| S
  L -->|provider_hdr| H
  AH -->|provider_code| H
  L -.->|login_principal, no FK| P
  L -.->|provider_app_hdr, no FK| AH
  

Solid arrows are foreign keys in kb/schema/foreign-keys.tsv; dashed arrows are columns that carry the same value with no constraint behind them.

How a password sign-in is checked

The password form posts to one endpoint (POST core2/platform/dm/identity/login). BigLedger finds the principal, reads the last stored password hash for the subject and compares. A match returns a signed token that lasts 30 days; a mismatch returns Invalid attempt, and the screen shows the same words whether the address or the password was wrong.

Two facts about this that you would not guess from the screen:

• There is no AWS Cognito behind it any more. Every Cognito call in the sign-in, registration and password services is commented out. The password hash lives in BigLedger’s own table (app_login_password), and BigLedger issues its own token. If someone tells you “reset it in Cognito”, they are ten versions out of date.
• A subject that has never had a password stored accepts the first password it is offered — on the e-mail path only. When no hash exists, the e-mail sign-in stores whatever password was typed and lets the person in; the mobile-number sign-in correctly refuses. This is filed as a defect (LB8-P01). Until it is fixed, the practical consequence is that a confirmed e-mail principal with no password set is not protected by anything, so make sure every invited person completes registration and sets a password promptly.

The comment on valid_date_start / valid_date_end says the two dates exist “for creating temporary users, e.g. for auditors or interns”. Every principal gets both dates (the end defaults to the year 9000), and about a fifth of all principals on the platform have an end date already in the past — yet the password sign-in never looks at the end date. Only access keys are checked (EXPIRED_ACCESS_ID). If you want an auditor’s access to stop in April, remove them from the tenant in April; the date will not do it for you (LB8-P03).

What multi-factor authentication does

MFA in BigLedger is a time-based one-time code from Google Authenticator (or any TOTP app). It is set up by the person, not by the administrator, from My Profile → MFA → Set Up Multi-Factor Authentication: install the app, scan the QR code, type the first code. That sets mfa_enforced on the subject and moves mfa_status from CONFIGURATION_IN_PROGRESS to ACTIVE. From then on the sign-in page, after the password, shows Verify OTP — open Google Authenticator and get the OTP, with a Reset MFA link that e-mails a reset link and sets the status to RESET_REQUESTED.

Two limits to know before you rely on it:

• Adoption is tiny. Twenty-five subjects across 23 tenants have it enforced; the registration table has rows in one tenant. Expect to be the first on your tenant.
• The check is in the browser, not the server. The sign-in endpoint issues a valid token before asking for the code; the login page then reads mfa_enforced and shows the OTP screen. A person using the API directly with their e-mail and password is never asked for a code. Treat MFA as protection against a shoulder-surfed password on the web app, not as a hard gate (LB8-P02).

Codes, links and the SMS rule

Every “we’ve sent you a code” flow — forgot password, register, change e-mail, change mobile number, sign in with OTP — uses the same machinery:

That last row is the one to remember. GadgetSphere’s two directors based in Singapore must register and reset with an e-mail address; a +65 number will never receive anything.

Step 1: Invite the person

Tenant Admin → Tenant Users → Add (or Catalogue → User → Send Invite)

The outcome: an invitation e-mail in the new supervisor’s inbox and a pending registration row waiting for them.

You are onboarding the new supervisor for GS-JB-02. Type their work e-mail and click Verify. Three replies are possible: the address already has a BigLedger login (add them straight away, choosing a rank), it is already in this tenant (nothing to do), or user not found — then Send Invite appears. Send it. BigLedger creates a registration row with a verification code and e-mails a link; the person is added to your tenant automatically when they complete registration through that link.

Invitations go by e-mail. A mobile number cannot be invited from this screen, and given the SMS rule above, e-mail is the right choice anyway.

The most common failure: the invitation is sent to a personal address the person later does not use to sign in. The link ties the registration to that address; if they register separately with another one, they will have a login and no tenant. Send the invite to the address they will type on the sign-in page.

Step 2: They register and confirm

The link in the invitation → Register

The outcome: a confirmed e-mail principal with a password.

The registration page asks for first name, last name, and whether to register with e-mail or mobile number — for an invited person the e-mail is already the one you sent to. They set a password and receive a confirmation link. The link is good for 48 hours. Until they click it the principal is USER_UNCONFIRMED and the sign-in page will say Invalid attempt, which looks exactly like a wrong password. If the 48 hours pass, Resend Verification on the sign-in page issues a fresh one.

Step 3: First sign-in

The sign-in page → Email or Mobile Number, Password → Sign In

The outcome: the supervisor lands in the applet list for GadgetSphere.

They type the address and password and land on the applet list. What they can open from there depends on the rank on their tenant link (OWNER, ADMIN, MEMBER or GUEST — across the platform most links carry GUEST) and on the applets installed for them; both are set in Tenant Admin, and that page explains which rank unlocks what.

If instead they press the Google button with the same address, BigLedger looks for an existing principal with that e-mail, links the Google identity to it, and signs them in — no password needed from then on. The link is made on the e-mail address alone; BigLedger does not check whether the provider marked the address as verified. For the back-office accounts that matters (finance, anyone who can post), prefer the password path and MFA over a social button (LB8-P04).

Step 4: Turn on MFA for the six who post journals

My Profile → MFA → Set Up Multi-Factor Authentication

The outcome: those six people are asked for a six-digit code after their password on the web app.

Each person does this themselves: install Google Authenticator, scan the QR code, type the code it shows. There is no administrator switch that enforces MFA for a group and no listing of who has it; what you can do is ask, and have each person confirm from their own MFA tab that set-up completed. Remind them that the reset path is an e-mail link to their main address — if that address is stale, they will be locked out of resetting.

What success looks like

The new supervisor signs out and back in from a fresh browser with the address you invited and the password they chose, lands on the GadgetSphere applet list, and opens the POS applet for GS-JB-02. If you asked for MFA, they were prompted for a code between the password and the applet list. Thirty seconds, and it proves the principal is confirmed, the tenant link exists and the rank is enough.

Common mistakes

Related documentation

• Authentication — access keys, the user token and its 30-day life, the tenantCode header, error codes.
• Tenant Admin Applet — Tenant Users, Catalogue › User › Send Invite, ranks, Tenant Admins.
• CP Commerce Admin — the storefront’s own social sign-in, configured per website.
• Core Module — the master-data applets every other module reads.