Epic: Single Sign On

.env.example

@@ -13,9 +13,13 @@
 # SALESFORCE_CLIENT_ID=3MVG9_ghE
 # SALESFORCE_CLIENT_SECRET=703777B
 
-# Set this up to handle Google OAuth credentials (ex: GoogleSheets)
-# GOOGLE_CLIENT_ID=660274980707
-# GOOGLE_CLIENT_SECRET=GOCSPX-ua
+# Set GITHUB_CLIENT_ID/GITHUB_CLIENT_SECRET to enable GitHub SSO sign-in
+# GITHUB_CLIENT_ID=
+# GITHUB_CLIENT_SECRET=
+
+# Set GOOGLE_CLIENT_ID/GOOGLE_CLIENT_SECRET to enable Google SSO sign-in
+# GOOGLE_CLIENT_ID=
+# GOOGLE_CLIENT_SECRET=
 
 # Choose an admin email address and configure a mailer. If you don't specify
 # mailer details the local test adaptor will be used and mail previews can be

CHANGELOG.md

@@ -17,6 +17,9 @@ and this project adheres to
 
 ### Added
 
+- Single Sign-On (SSO) sign-in with GitHub and Google, including account
+  [#4621](https://github.com/OpenFn/lightning/issues/4621)
+
 ### Changed
 
 ### Fixed

DEPLOYMENT.md

@@ -360,8 +360,51 @@ been marked as recovered.
 Once all files have either been recovered or discarded, the triggers can be
 enabled once more.
 
+### Single Sign-On (SSO)
+
+Lightning supports SSO **sign-in** with GitHub and Google, letting users
+authenticate with an external identity provider instead of an email/password.
+
+> SSO sign-in is distinct from two other, similarly-named features. Don't mix up
+> their environment variables:
+>
+> - **GitHub App** (`GITHUB_APP_ID`, `GITHUB_APP_CLIENT_ID`,
+>   `GITHUB_APP_CLIENT_SECRET`, `GITHUB_CERT`) — used for project **version
+>   control / repo sync**, with callback `/oauth/github/callback`. See
+>   [GitHub](#github) above. This is **not** sign-in.
+> - **Credential OAuth** — clients that **jobs** use to connect to external
+>   systems (e.g. Google Sheets, Salesforce). These are configured per-project
+>   in the UI, not via these environment variables.
+
+Enable a provider by setting its client ID and secret. Each provider has its own
+callback (redirect) URL that you must register in the provider's OAuth app
+settings. The redirect URL is derived automatically from your configured
+host/scheme/port — you only need to register the matching URL below.
+
+| Provider | Variables                                  | Redirect / Callback URL                                  |
+| -------- | ------------------------------------------ | -------------------------------------------------------- |
+| GitHub   | `GITHUB_CLIENT_ID`, `GITHUB_CLIENT_SECRET` | `https://<ENDPOINT DOMAIN>/authenticate/github/callback` |
+| Google   | `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET` | `https://<ENDPOINT DOMAIN>/authenticate/google/callback` |
+
+For **GitHub**, create an **OAuth App** (Settings → Developer settings → OAuth
+Apps — _not_ a GitHub App) and request the `read:user` and `user:email` scopes.
+GitHub's userinfo endpoint omits the email for users without a public profile
+email, so Lightning resolves the primary, verified address via the granted
+`user:email` scope.
+
+> ⚠️ **Upgrading from the older Google login?** The new Google SSO provider
+> reuses the same `GOOGLE_CLIENT_ID` / `GOOGLE_CLIENT_SECRET` as the
+> [Google Oauth2](#google-oauth2) setup below, but expects the callback
+> `/authenticate/google/callback` (not `/authenticate/callback`). Add the new
+> callback URL to your Google OAuth client's authorized redirect URIs.
+
 ### Google Oauth2
 
+> These `GOOGLE_CLIENT_ID` / `GOOGLE_CLIENT_SECRET` variables are also used by
+> [Single Sign-On (SSO)](#single-sign-on-sso) above, which expects a different
+> callback URL (`/authenticate/google/callback`). If you use Google for SSO
+> sign-in, register both callback URLs on the same OAuth client.
+
 Using your Google Cloud account, provision a new OAuth 2.0 Client with the 'Web
 application' type.
 

lib/lightning/accounts.ex

@@ -14,6 +14,7 @@ defmodule Lightning.Accounts do
   alias Lightning.Accounts.Events
   alias Lightning.Accounts.User
   alias Lightning.Accounts.UserBackupCode
+  alias Lightning.Accounts.UserIdentity
   alias Lightning.Accounts.UserNotifier
   alias Lightning.Accounts.UserToken
   alias Lightning.Accounts.UserTOTP
@@ -172,7 +173,151 @@ defmodule Lightning.Accounts do
   def get_user_by_email_and_password(email, password)
       when is_binary(email) and is_binary(password) do
     user = Repo.get_by(User, email: email)
-    if User.valid_password?(user, password), do: user
+
+    cond do
+      is_nil(user) ->
+        User.valid_password?(user, password)
+        nil
+
+      is_nil(user.hashed_password) ->
+        User.valid_password?(user, password)
+        {:error, :sso_account}
+
+      User.valid_password?(user, password) ->
+        user
+
+      true ->
+        nil
+    end
+  end
+
+  @doc """
+  Looks up a user by their SSO provider identity.
+
+  Returns the `%User{}` if found, otherwise `nil`.
+  """
+  def get_user_by_identity(provider, uid) do
+    from(u in User,
+      join: i in UserIdentity,
+      on: i.user_id == u.id,
+      where: i.provider == ^provider and i.uid == ^uid
+    )
+    |> Repo.one()
+  end
+
+  @doc """
+  Links an SSO provider identity to a user.
+
+  Idempotent if already linked to the same user. Returns
+  `{:error, :identity_already_linked}` if the identity is claimed by another
+  user, and `{:error, :provider_already_linked}` if the user already has a
+  different identity for this provider (at most one identity per provider).
+  """
+  def link_user_identity(%User{id: user_id} = user, provider, uid) do
+    case get_identity(provider, uid) do
+      %UserIdentity{user_id: ^user_id} = identity ->
+        {:ok, identity}
+
+      %UserIdentity{} ->
+        {:error, :identity_already_linked}
+
+      nil ->
+        if provider_linked?(user, provider) do
+          {:error, :provider_already_linked}
+        else
+          %UserIdentity{}
+          |> UserIdentity.changeset(%{
+            user_id: user_id,
+            provider: provider,
+            uid: uid
+          })
+          |> Repo.insert()
+        end
+    end
+  end
+
+  defp get_identity(provider, uid) do
+    Repo.get_by(UserIdentity, provider: provider, uid: uid)
+  end
+
+  defp provider_linked?(%User{id: user_id}, provider) do
+    Repo.exists?(
+      from(i in UserIdentity,
+        where: i.user_id == ^user_id and i.provider == ^provider
+      )
+    )
+  end
+
+  @doc """
+  Returns the SSO identities linked to a user, ordered by provider name.
+  """
+  def list_user_identities(%User{id: user_id}) do
+    from(i in UserIdentity,
+      where: i.user_id == ^user_id,
+      order_by: [asc: i.provider]
+    )
+    |> Repo.all()
+  end
+
+  @doc """
+  Removes a linked SSO identity, addressed by its id and scoped to `user`.
+
+  Refuses to remove the last identity for an SSO-only user (no password set),
+  since that would lock them out. Such users can set a password by going
+  through the password reset flow first.
+
+  Returns:
+    * `{:ok, identity}` when the identity is removed
+    * `{:error, :not_linked}` when no such identity belongs to the user
+    * `{:error, :would_lock_out}` when removing would leave an SSO-only user
+      with no way to log in
+  """
+  def unlink_user_identity(%User{} = user, identity_id) do
+    with {:ok, identity_id} <- Ecto.UUID.cast(identity_id),
+         %UserIdentity{} = identity <-
+           Repo.get_by(UserIdentity, id: identity_id, user_id: user.id) do
+      if can_remove_identity?(user, identity) do
+        Repo.delete(identity)
+      else
+        {:error, :would_lock_out}
+      end
+    else
+      _ -> {:error, :not_linked}
+    end
+  end
+
+  defp can_remove_identity?(%User{hashed_password: hp}, _identity)
+       when is_binary(hp),
+       do: true
+
+  defp can_remove_identity?(%User{} = user, %UserIdentity{id: identity_id}) do
+    other_count =
+      from(i in UserIdentity,
+        where: i.user_id == ^user.id and i.id != ^identity_id,
+        select: count(i.id)
+      )
+      |> Repo.one()
+
+    other_count > 0
+  end
+
+  @doc """
+  Registers a brand-new user via SSO.
+
+  The user is created without a password and confirmed immediately.
+  A `user_registered` event is broadcast on success.
+  """
+  def register_user_from_sso(attrs, provider, uid) do
+    attrs = Map.put(attrs, :sso_identity, %{provider: provider, uid: uid})
+
+    Repo.transact(fn ->
+      AccountHook.handle_register_user(attrs)
+    end)
+    |> tap(fn result ->
+      with {:ok, user} <- result do
+        Events.user_registered(user)
+      end
+    end)
   end
 
   @doc """

lib/lightning/accounts/user.ex

@@ -50,6 +50,8 @@ defmodule Lightning.Accounts.User do
     has_many :backup_codes, Lightning.Accounts.UserBackupCode,
       on_replace: :delete
 
+    has_many :user_identities, Lightning.Accounts.UserIdentity
+
     timestamps()
   end
 
@@ -337,6 +339,22 @@ defmodule Lightning.Accounts.User do
     change(user, confirmed_at: now)
   end
 
+  @doc """
+  A changeset for registering a user via SSO. No password is required;
+  the account is confirmed immediately at registration time.
+  """
+  def sso_registration_changeset(user, attrs) do
+    user
+    |> cast(attrs, [:first_name, :last_name, :email])
+    |> validate_required([:first_name, :last_name, :email])
+    |> validate_email_format()
+    |> validate_email_exists()
+    |> put_change(
+      :confirmed_at,
+      DateTime.utc_now() |> DateTime.truncate(:second)
+    )
+  end
+
   @spec remove_github_token_changeset(t()) :: Ecto.Changeset.t()
   def remove_github_token_changeset(user) do
     change(user, github_oauth_token: nil)

lib/lightning/accounts/user_identity.ex

@@ -0,0 +1,28 @@
+defmodule Lightning.Accounts.UserIdentity do
+  @moduledoc """
+  Schema for tracking SSO provider identities linked to user accounts.
+
+  A user has at most one identity per provider, and the combination of provider
+  and uid is globally unique (an identity can't be claimed by two users).
+  """
+  use Lightning.Schema
+
+  alias Lightning.Accounts.User
+
+  schema "user_identities" do
+    field :provider, :string
+    field :uid, :string
+    belongs_to :user, User
+    timestamps()
+  end
+
+  def changeset(identity, attrs) do
+    identity
+    |> cast(attrs, [:provider, :uid, :user_id])
+    |> validate_required([:provider, :uid, :user_id])
+    |> unique_constraint([:provider, :uid])
+    |> unique_constraint([:user_id, :provider],
+      message: "is already linked to a different account for this provider"
+    )
+  end
+end

lib/lightning/auth_providers.ex

@@ -10,6 +10,15 @@ defmodule Lightning.AuthProviders do
   alias Lightning.AuthProviders.WellKnown
   alias Lightning.Repo
 
+  @doc """
+  Returns a human-friendly name for a provider, e.g. `"github"` -> `"GitHub"`.
+  """
+  @spec display_name(provider :: String.t()) :: String.t()
+  # Explicit clauses needed for providers whose correct name has mid-word
+  # capitalisation that String.capitalize/1 can't produce.
+  def display_name("github"), do: "GitHub"
+  def display_name(provider), do: String.capitalize(provider)
+
   @spec get_existing() :: AuthConfig.t() | nil
   def get_existing do
     from(ap in AuthConfig) |> Repo.one()
@@ -88,21 +97,6 @@ defmodule Lightning.AuthProviders do
     Handler.new(name, opts)
   end
 
-  @doc """
-  Retrieve the authorization url for a given handler or handler name.
-  """
-  @spec get_authorize_url(String.t() | Handler.t()) :: String.t() | nil
-  def get_authorize_url(name) when is_binary(name) do
-    case get_handler(name) do
-      {:ok, handler} -> get_authorize_url(handler)
-      {:error, :not_found} -> nil
-    end
-  end
-
-  def get_authorize_url(%Handler{} = handler) do
-    Handler.authorize_url(handler)
-  end
-
   defp find_and_build(name) do
     get_existing(name)
     |> Handler.from_model()