GitHub Login

Let clients into your client area with the GitHub account they already use, matched only to email addresses GitHub has verified.

What it does

Another password is one more thing standing between a client and paying their bill. GitHub Login adds a "Login with GitHub" button to your existing client login page, so a client can sign straight in with the GitHub account they already have. Blesta matches the GitHub account to a client by email address - using only addresses GitHub itself has verified - logs the matching client in, and records it exactly like a normal login. Nothing is asked of GitHub beyond the client's email addresses: no repository access, no code access, nothing that can be changed on their behalf.

Key features

• Sign In With an Account They Already Have: Clients reach your client area with an account they already use elsewhere, on your existing login page with no template edits.
• Verified Email Addresses Only: Only email addresses GitHub itself has verified are used to identify the client, so an unverified address someone added to their own GitHub account can never be used to reach another person's client account.
• Signs In the Matching Client Account: The verified GitHub address is matched to the client account that already uses it and that client is logged straight in. Only client accounts are signed in this way - a staff login can never be created from the client area.
• Two-Factor Accounts Stay Protected: A client with two-factor authentication switched on is never waved past it by the GitHub button - they're asked to sign in with their email address and password instead.
• Single-Use Sign-In Links: Each GitHub sign-in is tied to the browser that started it and works only once, so a link copied out of an address bar, browser history or a log file can't be replayed to get into someone's account.
• Never Locks Anyone Out: If no client account matches, or GitHub can't complete the sign-in, the visitor is returned to the normal login page with a plain-language explanation and can still log in with their email address and password.
• Straightforward GitHub App Setup: Enter your GitHub application's client ID and client secret, and the exact authorization callback URL to paste back into GitHub is shown for you on the settings page.
• Try It Without a GitHub Application: A Mock API mode runs the whole sign-in flow from bundled sample data, so you can see exactly how it behaves before setting up a real GitHub application.

Enhance your client login experience with GitHub Login by Blesta.Club.

Installing GitHub Login

Before you start

• If you are on the leased (subscription) licence, the Blesta Club Subscription Manager must be installed and your subscription active. The owned and owned-source licences have no such requirement.
• You'll want a GitHub OAuth application (for its Client ID and Client Secret) from the GitHub Developer Portal. You can install and try the plugin first with its Mock API mode if you'd rather set the GitHub application up afterward.

1. Upload the files

Upload the extension folder into your Blesta installation so it lands under your Blesta directory at:

plugins/github_login/

For example, on a typical install: /var/www/html/blesta/plugins/github_login/

2. Install it in Blesta

1. Log in to your Blesta admin area with a staff account that has access to Settings > Company > Plugins.
2. Go to Settings > Company > Plugins and click the Available tab.
3. Find GitHub Login in the list and click Install.

3. Configure it

1. Click Manage next to GitHub Login on the Plugins page.
2. Copy the Authorization Callback URL shown on the settings page into your GitHub OAuth application's own "Authorization callback URL" field - the two must match exactly.
3. Enter that GitHub application's Client ID and Client Secret, then save. Or tick Mock API to try the whole sign-in flow from bundled sample data with no GitHub application at all.

You're ready to go - see the usage guide for a walkthrough of day-to-day use.

Updating GitHub Login

Upgrading works just like installing: upload the new files over the old ones, then run the upgrade from the same page you installed it on.

1. Back up your current extension files first - good practice before any upgrade.
2. Upload the new version over the existing folder, replacing the old files.
3. Log in to your Blesta admin area and go to Settings > Company > Plugins.
4. Find GitHub Login and click Update to run the upgrade.

Version-specific notes

• v2.0.0: Adds a Mock API mode for testing without a real GitHub application, refuses to sign in a client who has two-factor authentication enabled (they're asked for their email address and password instead), and makes each sign-in link single-use and tied to the browser that started it. This version also fixes several issues: the "Login with GitHub" button failing on every attempt including a first click in a fresh browser, an email GitHub had not verified being accepted as proof of identity, a failed sign-in dropping the visitor back on the client area with no explanation, the button appearing before a GitHub application had been configured, a staff member's GitHub email producing a session the client area couldn't display, blank error messages on the settings page, and a blank settings page when the license check failed. Your existing Client ID and Client Secret carry over unchanged - no reconfiguration is needed.

Using GitHub Login

For your staff

The settings screen (Settings > Company > Plugins > Manage)

• Client ID / Client Secret: The credentials from your GitHub OAuth application.
• Authorization Callback URL: A read-only field showing the exact URL to paste into your GitHub application's own settings - keep the two in sync if you ever recreate the GitHub application.
• Mock API: Runs the whole sign-in flow from bundled sample data instead of a real GitHub application - useful for seeing exactly how it behaves before you've set one up.

There is nothing else to manage day to day - once saved, the "Login with GitHub" button appears on your client login page automatically.

For your clients

Signing in with GitHub

On the normal client-area login page, clients see a Login with GitHub button alongside the usual email and password fields. Clicking it sends them to GitHub to approve access to their email addresses only - nothing about their repositories or code is requested. Once they approve, they're brought back to Blesta and, if their verified GitHub email address matches an existing client account, logged straight in.

If GitHub can't complete the sign-in, or no client account matches, they're returned to the login page with a plain-language explanation and can sign in with their email address and password as usual instead.

Good to know

• Only a GitHub-verified email address is used to find the matching client - an address GitHub has not verified is never used to identify anyone, even if it's the one listed as primary.
• A client with two-factor authentication enabled is never signed in through GitHub - they're asked for their email address and password instead, so the second factor is never bypassed.
• Each sign-in link works once, and only in the browser that started it - a copied or reused link can't sign anyone in a second time or from a different browser.
• Connecting this plugin doesn't change any account, contact or password data - it only checks an existing verified email address against an existing client account each time someone signs in.