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, 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 is the person: name, main e-mail, main phone, MFA settings. One per human.
• A sign-in identity 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. An identity is USER_UNCONFIRMED until the person clicks the confirmation link, then USER_CONFIRMED. An unclicked link is the single most common reason a new person “cannot sign in” — the password is right and the identity was never confirmed.
• A social link ties a Google, Facebook, Apple or Microsoft identity to a sign-in identity. It is created the first time the person signs in through that provider, never by an administrator.

All of this is held by the platform, not by your tenant; your tenant keeps a copy of the people who belong to it, refreshed when the platform’s record changes. Change a person’s sign-in details through the platform’s own screens, not in your tenant’s copy.

Four social providers are listed — Apple, Facebook, Google and, on newer tenants, Microsoft; the sign-in screen says which of them a person can actually use.

    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 declared in the database; dashed arrows are columns that carry the same value with no constraint behind them.

How a password sign-in is checked

When you sign in with a password, BigLedger finds your login by its e-mail address or mobile number and checks the password against the one stored for you. 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:

• Passwords are held by BigLedger itself. BigLedger checks the password and issues its own sign-in token; there is no separate AWS Cognito account behind it any more. If someone tells you to “reset it in Cognito”, they are several versions out of date.
• Make sure every person you invite finishes registering and sets a password promptly, and keep your own list of the invitations you have sent. No screen lists sent invitations or withdraws one, so if a person does not take theirs up, ask BigLedger support to withdraw it. An invited login that has never set a password should not be left waiting.

Every login carries a start and an end date, which look as though they are meant for temporary users such as auditors or interns. Do not rely on the end date to close a person’s access. If an auditor’s access should stop in April, remove them from the tenant in April. After you remove anyone, reopen the Tenant Users listing and confirm they are no longer on it. If they are still there, ask BigLedger support the same day.

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:

• Nothing switches it on for anybody but themselves. There is no administrator screen that enforces MFA across your staff: each person turns it on from their own profile, so “we are putting the six journal-posters on MFA” is six separate conversations, not one setting.
• MFA protects signing in to the web app. It does not cover access through the API, so control API access separately — who holds API credentials, and what they can reach.

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 → Catalogue → the catalogue the person will work in → User tab → Add

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

Before you type the address: the most common failure is an invitation 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 that is not linked to your tenant. Send the invite to the address they will type on the sign-in page.

You are onboarding the new supervisor for GS-JB-02. The Tenant Users listing has no Add button; people are added from a catalogue’s User tab. Type their work e-mail and click Verify User. For somebody new the reply is not found, and Send Invitation appears; send it. The other three replies, and what each lets you do, are on Tenant Admin › Catalogue › User › Add. 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.

An invitation only brings the person into the tenant, at the lowest rank, GUEST, and not into the catalogue you sent it from. Once they have registered, come back to the same User tab, click Verify User again (it now says they are a registered user) and add them at the rank the job needs. Until you do, they sign in to an applet list with nothing useful on it.

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.

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) and on the applets installed for them; both are set in Tenant Admin, and the Tenant Admin Applet 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. For back-office accounts (finance, anyone who can post), prefer the password path and MFA over a social button.

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 › Add and Send Invitation, ranks, Tenant Admins.
• CP Commerce Admin — the storefront’s own social sign-in, configured per website.
• Teams and permissions — the next job once the person can sign in: what they may see, edit and export, with their document permissions scoped to their branch.
• Core Module — the master-data applets every other module reads.