Social login: Google and Facebook

HiLMS signs students in with Google or Facebook through Socialite. The buttons appear on the login and registration pages only when the provider’s client id is configured, so a fresh installation shows none of them until this page has been followed. Each provider takes about ten minutes in the provider’s console; the values then go into .env.

What happens on a sign-in: a known identity signs the user in; otherwise an account with the same e-mail is linked to it; otherwise a new, verified student is created. When self-registration is closed in the panel, existing accounts still sign in and link, and new ones are refused.

The callback the provider must be told about is always https://<host>/auth/google/callback or https://<host>/auth/facebook/callback, with the installation’s public hostname; the redirect is built from APP_URL, so that value has to be right first.

Both providers also ask for a privacy policy and a terms of service URL before an app may leave its testing mode. Every installation has them at https://<host>/privacy-policy and https://<host>/terms-of-service; hilms:install creates both pages as templates. Fill them in under Pages in the panel before you give the addresses to Google or Meta — what they publish is whatever those pages say.

Google

In the Google Cloud console:

1. Create a project, or pick the customer’s existing one.
2. APIs & Services → OAuth consent screen: user type External. App name (the installation’s name), support e-mail, the customer’s domain under authorised domains, a developer contact, and the two links above under the application’s privacy policy and terms of service. Scopes stay at the defaults (e-mail, profile, openid), which need no verification by Google. An app in the “Testing” state lets only listed test users sign in; press Publish app when everyone should be able to.
3. Credentials → Create credentials → OAuth client ID, type Web application:
   • Authorised JavaScript origin: https://<host>
   • Authorised redirect URI: https://<host>/auth/google/callback
   • For local development, a second redirect URI https://hilms.lndo.site/auth/google/callback on the same client is enough.
4. Copy the Client ID and the Client secret.

Facebook

In Meta for Developers:

1. Create app, use case “Authenticate and request data from users with Facebook Login” (type Consumer), named after the installation.
2. Add the Facebook Login product; under its Settings, set Valid OAuth Redirect URIs to https://<host>/auth/facebook/callback.
3. App settings → Basic: copy the App ID and the App secret; fill in the privacy policy URL (https://<host>/privacy-policy), the terms of service URL (https://<host>/terms-of-service) and the app icon, which Meta requires before the app can leave Development mode.
4. Switch App mode to Live when everyone should be able to sign in; in Development mode only people with a role on the app can.

Facebook returns an e-mail address only when the account has one and the user grants it; a sign-in without an e-mail is refused with a message, because HiLMS identifies people by e-mail.

Where the values go

Four keys in the installation’s .env:

GOOGLE_CLIENT_ID=...
GOOGLE_CLIENT_SECRET=...
FACEBOOK_CLIENT_ID=...
FACEBOOK_CLIENT_SECRET=...

A provider that stays empty simply shows no button. Then apply the change:

• Docker: docker compose up -d in the stack directory. Compose hands .env to a container when it creates it, so restart is not enough; up -d recreates the containers whose environment changed.
• Manual installation: php artisan optimize, which re-caches the configuration.

Secrets travel to the server the way every other secret does: typed or pasted on the server, or carried in a file with 0600 permissions; never through a chat, a ticket or a commit.

Verify

1. The login page shows the button for each configured provider.
2. Sign in with an account that HiLMS has never seen: it lands on the dashboard as a verified student, and appears in the panel under Users with the student role.
3. Sign in with a provider whose e-mail matches an existing account: the identity is attached to that account (the panel shows nothing new; the user sees their own courses).
4. Close self-registration in the panel (Settings → Sign-up) and try a brand-new provider account: the login page reports that registration is closed, while the accounts from steps 2 and 3 still sign in.

A denial on the provider’s side, a wrong redirect URI or an app still in Testing/Development mode all come back to the login page with a message rather than an error page; the provider’s console says which one it was.