---
title: "Configure Social Sign-In in HitKeep | HitKeep"
description: "Configure Google, GitHub, and Microsoft social sign-in in HitKeep with exact callback URLs, Docker Compose variables, account rules, and troubleshooting."
canonical: "https://hitkeep.com/guides/security/social-sign-in/"
---

# Configure Social Sign-In in HitKeep

HitKeep social sign-in lets people use Google, GitHub, or Microsoft on the normal sign-in, signup, invitation, and account-security screens. Self-hosted operators enable each provider with an OAuth client ID and secret. HitKeep Cloud supplies its own provider configuration.

Social sign-in is instance-wide. It is separate from [team OIDC single sign-on](https://hitkeep.com/guides/security/single-sign-on/), which routes a team through its own identity provider and allowed email domains.

![HitKeep sign-in form with Google, GitHub, Microsoft, passkey, SSO, email, and password options](https://hitkeep.com/_astro/social-sign-in-providers.srhdVOI0_ZObDH5.webp)

Only providers with a complete client ID and client secret appear. Password, passkey, and team SSO remain available.

Availability

Google, GitHub, and Microsoft login are available in HitKeep Cloud and self-hosted HitKeep. Public social signup is a managed-cloud control. A self-hosted instance can use social providers for existing accounts, invitations, and account linking, but it does not gain open public signup from `HITKEEP_SOCIAL_SIGNUP_ENABLED`.

## Before you configure a provider

You need:

- HitKeep 2.13.0 or later;
- an externally reachable [`HITKEEP_PUBLIC_URL`](https://hitkeep.com/reference/configuration/#core);
- permission to create a confidential web or OAuth application at the provider;
- a separate client ID and client secret for each provider you enable;
- HTTPS for production callbacks;
- working outbound mail if Microsoft users may need HitKeep email confirmation.

Store client secrets in an environment file or secret manager. Do not commit them to `compose.yml`, screenshots, support tickets, or source control.

Set the public URL first

HitKeep derives every social callback from `HITKEEP_PUBLIC_URL`. A change to the scheme, host, port, or path prefix changes the callback. Update the provider registration before restarting production traffic.

## Register the exact callback URLs

For a root deployment at `https://analytics.example.com`, register these three callbacks:

| Provider | Callback URL |
| --- | --- |
| Google | https://analytics.example.com/api/auth/social/google/callback |
| GitHub | https://analytics.example.com/api/auth/social/github/callback |
| Microsoft | https://analytics.example.com/api/auth/social/microsoft/callback |

If `HITKEEP_PUBLIC_URL` contains a path prefix, the prefix stays in the callback. For example:

```
https://www.example.net/hitkeep/api/auth/social/google/callback
https://www.example.net/hitkeep/api/auth/social/github/callback
https://www.example.net/hitkeep/api/auth/social/microsoft/callback
```

HitKeep Cloud uses region-specific callbacks:

- EU Cloud
- US Cloud

```
https://cloud.hitkeep.eu/api/auth/social/google/callback
https://cloud.hitkeep.eu/api/auth/social/github/callback
https://cloud.hitkeep.eu/api/auth/social/microsoft/callback
```

```
https://cloud.hitkeep.com/api/auth/social/google/callback
https://cloud.hitkeep.com/api/auth/social/github/callback
https://cloud.hitkeep.com/api/auth/social/microsoft/callback
```

The callback must match the provider registration exactly. Treat the scheme, host, port, path prefix, provider name, and trailing slash as significant.

## Configure Google, GitHub, or Microsoft

Provider consoles change over time. The steps below name the current settings that matter to HitKeep, and each tab links to the provider’s primary documentation.

- Google
- GitHub
- Microsoft

1. Open **Google Cloud Console → Google Auth Platform → Clients**.
2. Select or create a project. Complete the app branding, audience, and consent-screen information required for the accounts that will use HitKeep.
3. Select **Create client**, then choose **Web application**.
4. Add the exact Google callback from the previous section under **Authorized redirect URIs**.
5. Create the client, then copy its client ID and client secret.
6. Set both HitKeep variables:

```
HITKEEP_SOCIAL_GOOGLE_CLIENT_ID=your-google-client-id
HITKEEP_SOCIAL_GOOGLE_CLIENT_SECRET=your-google-client-secret
```

HitKeep requests the standard `openid` and `email` scopes. The returned ID token must contain an immutable subject, an email address, and boolean `email_verified: true`. A Google identity without a verified email is rejected.

Google requires the callback in the authorization request to match an authorized redirect URI. See [Google’s web-server OAuth setup](https://developers.google.com/identity/protocols/oauth2/web-server) and [OAuth policy requirements](https://developers.google.com/identity/protocols/oauth2/policies).

1. In GitHub, open **Settings → Developer settings → OAuth Apps**.
2. Select **New OAuth App** or **Register a new application**.
3. Enter a public application name.
4. Set **Homepage URL** to the public HitKeep URL.
5. Set **Authorization callback URL** to the exact GitHub callback from the previous section.
6. Register the application, generate a client secret, and copy the secret value.
7. Set both HitKeep variables:

```
HITKEEP_SOCIAL_GITHUB_CLIENT_ID=your-github-client-id
HITKEEP_SOCIAL_GITHUB_CLIENT_SECRET=your-github-client-secret
```

HitKeep requests only `read:user` and `user:email`. It uses the immutable GitHub user ID as the provider identity and requires a primary, verified GitHub email. Repository access is not requested.

A GitHub OAuth App accepts one callback URL. Use a separate OAuth App for production, staging, and local development when those environments have different callbacks. See [Create a GitHub OAuth App](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/creating-an-oauth-app) and [GitHub OAuth redirect rules](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps#redirect-urls).

1. In the Microsoft Entra admin center, open **Entra ID → App registrations** and select **New registration**.
2. Choose the supported account type that matches the tenant selector you will give HitKeep.
3. Open **Authentication**, add the **Web** platform, and register the exact Microsoft callback from the previous section.
4. Open **Certificates & secrets**, create a client secret, and copy its **Value** before leaving the page.
5. Copy the **Application (client) ID** from the app overview.
6. Set the client pair and tenant selector:

```
HITKEEP_SOCIAL_MICROSOFT_CLIENT_ID=your-application-client-id
HITKEEP_SOCIAL_MICROSOFT_CLIENT_SECRET=your-client-secret-value
HITKEEP_SOCIAL_MICROSOFT_TENANT=common
```

Choose the tenant selector deliberately:

| HitKeep value | Accounts accepted | Matching Entra registration |
| --- | --- | --- |
| common | Work, school, and personal Microsoft accounts | Any organizational directory and personal Microsoft accounts |
| organizations | Work and school accounts from any Entra directory | Any organizational directory |
| consumers | Personal Microsoft accounts | Personal Microsoft accounts |
| Tenant UUID | Accounts from one Entra tenant | Accounts in this organizational directory only |

HitKeep requests `openid email profile`. It keys the identity by Microsoft tenant ID plus object ID, not by an editable email address. Microsoft email claims are not treated as provider-verified, so some first-use flows require HitKeep email confirmation.

See [Microsoft app registration](https://learn.microsoft.com/en-us/entra/identity-platform/howto-create-service-principal-portal), [supported account types](https://learn.microsoft.com/en-us/entra/identity-platform/supported-accounts-validation), and [web app sign-in setup](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-web-app-sign-in).

## Add the variables to Docker Compose

Add every provider variable to the HitKeep service, even if unused values remain empty:

```
environment:
  HITKEEP_PUBLIC_URL: ${HITKEEP_PUBLIC_URL:?set HITKEEP_PUBLIC_URL in .env}
  HITKEEP_SOCIAL_GOOGLE_CLIENT_ID: ${HITKEEP_SOCIAL_GOOGLE_CLIENT_ID:-}
  HITKEEP_SOCIAL_GOOGLE_CLIENT_SECRET: ${HITKEEP_SOCIAL_GOOGLE_CLIENT_SECRET:-}
  HITKEEP_SOCIAL_GITHUB_CLIENT_ID: ${HITKEEP_SOCIAL_GITHUB_CLIENT_ID:-}
  HITKEEP_SOCIAL_GITHUB_CLIENT_SECRET: ${HITKEEP_SOCIAL_GITHUB_CLIENT_SECRET:-}
  HITKEEP_SOCIAL_MICROSOFT_CLIENT_ID: ${HITKEEP_SOCIAL_MICROSOFT_CLIENT_ID:-}
  HITKEEP_SOCIAL_MICROSOFT_CLIENT_SECRET: ${HITKEEP_SOCIAL_MICROSOFT_CLIENT_SECRET:-}
  HITKEEP_SOCIAL_MICROSOFT_TENANT: ${HITKEEP_SOCIAL_MICROSOFT_TENANT:-common}
```

Place the real values in `.env`:

```
HITKEEP_SOCIAL_GOOGLE_CLIENT_ID=
HITKEEP_SOCIAL_GOOGLE_CLIENT_SECRET=
HITKEEP_SOCIAL_GITHUB_CLIENT_ID=
HITKEEP_SOCIAL_GITHUB_CLIENT_SECRET=
HITKEEP_SOCIAL_MICROSOFT_CLIENT_ID=
HITKEEP_SOCIAL_MICROSOFT_CLIENT_SECRET=
HITKEEP_SOCIAL_MICROSOFT_TENANT=common
```

Recreate the container so Compose applies the new environment:

```
docker compose up -d
docker compose logs --tail=100 hitkeep
```

A provider appears only when both its client ID and secret are non-empty. Microsoft also needs a valid tenant selector. A partial pair stays hidden instead of showing a button that cannot complete.

The full examples in [Docker Compose installation](https://hitkeep.com/guides/installation/docker-compose/) include the same variables. The generated [configuration reference](https://hitkeep.com/reference/configuration/#social-sign-in) remains the source of truth for variable names, flags, defaults, and secret redaction.

## Verify the rollout

1. Open a private browser window at the HitKeep sign-in page.
2. Confirm that only the intended provider buttons appear.
3. Complete one login with each enabled provider.
4. Test an existing account, an invitation, and a user with MFA enabled.
5. From **Settings → Security**, link a second provider, sign out, and use it to sign back in.
6. Add a passkey or confirm password login before testing unlink protection.
7. Review the authentication events in the team activity log.

You can also inspect the public availability response:

```
curl -fsS https://analytics.example.com/api/auth/social/providers
```

The response contains display names for completely configured providers. It does not expose client IDs, secrets, provider subjects, or configured account details.

## How accounts, invitations, and MFA behave

### Verified-email rules

| Provider | Identity key | Email rule |
| --- | --- | --- |
| Google | OIDC sub | The ID token must contain a normalized email and boolean email_verified: true |
| GitHub | Numeric GitHub user ID | HitKeep selects the primary GitHub email and requires verified: true |
| Microsoft | Entra tenant ID plus object ID | Email is metadata and is not treated as provider-verified |

HitKeep stores the immutable provider identity after linking. It does not use an editable email address as the long-term identity key, and it discards provider access, ID, and refresh tokens after the exchange.

### Existing accounts and invitations

- A Google or GitHub identity with a verified email can link automatically to the existing HitKeep account with the same normalized email.
- A pending invitation stays bound to its invited email and requested role. HitKeep consumes it only after the provider flow proves the expected account boundary.
- An invitation can prove the target account for a Microsoft first link, so the invite flow does not need a second email confirmation.
- Disabling open social signup does not disable provider login, invitation acceptance, or account linking.

### Microsoft confirmation

Microsoft does not provide the same verified-email guarantee used by the Google and GitHub flows. When an unauthenticated Microsoft login or cloud signup would attach or create an account without an invitation, HitKeep sends a 30-minute confirmation link to the target HitKeep email address.

An authenticated user linking Microsoft from **Settings → Security** has already proved the HitKeep session, so that link does not need the extra email round trip. A matching live invitation also proves the target account.

Outbound mail must work before these confirmation-dependent flows can finish. Configure and test [`HITKEEP_MAIL_*`](https://hitkeep.com/reference/configuration/#email) values first.

### MFA handoff

Social sign-in does not bypass HitKeep MFA. If the resolved account has TOTP, passkey, recovery-code, or email-link factors enabled, HitKeep returns the normal MFA challenge before issuing the browser session. The chosen social provider and remember-me preference stay attached to that challenge for session and audit handling.

Team OIDC SSO behaves differently: the team’s identity provider owns its MFA and conditional-access policy. See [OIDC Single Sign-On](https://hitkeep.com/guides/security/single-sign-on/) when the requirement is centralized workforce authentication.

## Link and unlink providers

An authenticated user manages linked identities under **Settings → Security**.

- **Link:** choose an unlinked configured provider and complete its provider flow.
- **Unlink:** choose a linked provider. If password is the only alternative login method, enter the current password so HitKeep can verify that it still works.
- **Protection:** unlinking is refused when it would remove the last usable primary login method.

Another linked social provider or a registered passkey counts as an alternative method. Team OIDC access and MFA recovery factors do not replace the primary-method guard. Add and test a password, passkey, or second social provider before removing the only working social identity.

## Troubleshooting

| Symptom | What to check |
| --- | --- |
| Provider button is missing | Set both the provider client ID and secret, recreate the container, and check the Microsoft tenant selector when relevant. HitKeep hides partial configurations. |
| Provider reports a redirect URI mismatch | Compare the provider callback with HITKEEP_PUBLIC_URL, including HTTPS, host, port, path prefix, provider name, and trailing slash. |
| social_provider_unavailable | Check the client secret, provider application status, outbound DNS and HTTPS, and Google or Microsoft discovery access. |
| social_email_unverified | Google must return boolean email_verified: true. GitHub must expose a primary verified email through user:email. |
| Microsoft says verification was sent | This is expected for an unproved first login or signup. Check SMTP delivery and use the newest confirmation link within 30 minutes. |
| social_state_invalid | Start again from the HitKeep button in one browser tab. Old, replayed, cross-browser, or expired state cannot be reused. |
| social_identity_conflict | Sign in through an existing method and inspect linked providers. One provider identity cannot belong to two HitKeep users, and one user cannot link two identities from the same provider. |
| MFA appears after provider login | Complete the account’s existing HitKeep MFA challenge. Social sign-in proves the primary identity but does not remove local MFA. |
| Invitation fails | Confirm that the invitation is live and that the provider account matches the invited email. Start the provider flow from the invitation page. |
| Unlink is refused | Add and test another social provider or passkey. When password is the remaining alternative, enter the current password before unlinking. |

## Related

- [Docker Compose installation](https://hitkeep.com/guides/installation/docker-compose/)
- [Social sign-in configuration variables](https://hitkeep.com/reference/configuration/#social-sign-in)
- [HitKeep security model](https://hitkeep.com/reference/security/)
- [Authentication facts and limits](https://hitkeep.com/reference/facts-and-limits/#social-sign-in-facts)
- [Two-factor authentication](https://hitkeep.com/guides/security/two-factor-authentication/)
- [Team OIDC single sign-on](https://hitkeep.com/guides/security/single-sign-on/)
- [Roles and invitations](https://hitkeep.com/guides/admin/permissions/)

[Previous AI model configuration](https://hitkeep.com/guides/admin/ai-model-configuration/)[Next Single sign-on (OIDC)](https://hitkeep.com/guides/security/single-sign-on/)