End users sign in with an email address and a password, or with Google or GitHub. Whichever method they use, the account belongs to your application's sign-in gate, and the first sign-up creates the buyer organization the account works in.
Methods
| Method | Where it is offered | What you set up |
|---|---|---|
| Email and password | The hosted pages, the React components SignInForm and SignUpForm, and the Public API | Nothing; it is always on |
| The hosted pages only | A Google OAuth client, entered as a provider of the gate | |
| GitHub | The hosted pages only | A GitHub OAuth app, entered as a provider of the gate |
The React components do not include the social buttons. If your own sign-in page needs Google or GitHub, link to the hosted sign-in page for them; Hosted pages, components or your own compares the options.
Before a session is issued, the end user confirms their email address with a code that ShipRev emails to it, unless the address is already confirmed: by Google or GitHub, by the invitation email they signed up from, or by an earlier code. The hosted pages include this step. SignInForm and SignUpForm in @shiprev/react 0.1.0-beta.0, the version published on npm, do not: such a sign-up or sign-in is refused with EMAIL_VERIFICATION_REQUIRED and the form cannot continue it. Until a version with this step is published, send end users who sign up with a password to the hosted pages.
Passwords
A password needs at least 8 characters, with at least one letter and one digit. The same rule applies when a password is reset. End users who forget their password reset it on the hosted pages: they request a link by email and set a new password from it, which also signs them out of every session they had.
Google and GitHub
In the application's operator console, under Settings, Project, Identity Providers, add the provider with the client ID and client secret from Google or GitHub, and enable it. The secret is stored encrypted and is not shown again.
When you create the OAuth client at Google or GitHub, register this callback address on each brand domain your end users sign in on:
https://<your brand domain>/auth/oauth/google/callback
https://<your brand domain>/auth/oauth/github/callbackThe region accepts a social sign-in only when it returns to a verified brand domain of the gate, so the provider's callback list and your verified brand domains must match.
A social sign-in finds its account in this order:
- An account already linked to that Google or GitHub identity signs in.
- Otherwise, an account of the gate with the same email address is linked and signs in, provided the email is verified on both sides. If it is not, the sign-in is refused with
ACCOUNT_LINKING_VERIFICATION_REQUIRED, and the end user signs in with their password instead. - Otherwise, a new account is created, as described below.
ShipRev takes the email address from the provider: from Google, the account's address and whether Google has verified it; from GitHub, the primary email address and whether GitHub has verified it.
What a new account creates
| How the end user arrives | What is created |
|---|---|
| Signs up with a password, without an invitation | The account, a new buyer organization named by the end user, and the account's membership in it as owner, in one step. The end user is signed in once their email address is confirmed |
| Signs in with Google or GitHub for the first time, without an invitation | The account, a new buyer organization named after the end user's display name (for example "Ada Lovelace's Organization"), and the owner membership |
| Signs up from an invitation, with a password or with Google or GitHub | The account and its membership in the inviting organization, with the role the invitation names. No organization of their own is created |
End users cannot create further organizations themselves. They join others by invitation; see Buyer organizations.
Who may create an account
Each gate has a sign-up policy, Allow self sign-up, under Settings, Project, Customer sign-in. It is off until you turn it on.
| Allow self sign-up | Effect |
|---|---|
| Off | No new account can be created on this gate, with or without an invitation, by password or by Google or GitHub. Existing accounts sign in as usual |
| On | Anyone who reaches your sign-in can create an account. An invitation decides which organization the new account joins |
Turn it on before your first end users arrive, including when you only plan to invite them. Only owners and admins of your organization can change it.