Skip to main content

Add 3rd Party Authentication (Google, Twitch etc.)

icon.png

BookStack supports third-party authentication, allowing users to log in with services like Google, GitHub, Twitter, and others. By default, these services are disabled, but you can enable them by configuring the necessary credentials from each external service.

This guide will walk you through setting up third-party authentication, focusing on the most popular services: Google, GitHub, Twitter, Facebook, Slack, AzureAD, Okta, GitLab, Twitch, and Discord.

Step 1: Enable Automatic Registration (Optional)

If you want to auto-register users when they log in via a third-party service, add the following option to your .env file or to your docker-compose.yaml:

{SERVICE}_AUTO_REGISTER=true

For example, if you're setting up Google authentication:

GOOGLE_AUTO_REGISTER=true

This will allow users to register through third-party login services even if general registration is disabled.

Step 2: Enable Automatic Email Confirmation (Optional)

You can also enable automatic email confirmation, skipping the confirmation step for trusted third-party login services:

{SERVICE}_AUTO_CONFIRM_EMAIL=true

For example, for Google:

GOOGLE_AUTO_CONFIRM_EMAIL=true

Step 3: Configure Individual Third-Party Services

Google Authentication

  1. Open the Google Developers Console.

  2. Create a new project and go to the OAuth consent screen to configure the app.

  3. In API and Services > Credentials, click Create Credentials > OAuth client ID.

  4. Set the application type to Web application and enter the following redirect URIs (replace https://example.com with your BookStack domain):

    https://example.com/login/service/google/callback
https://example.com/register/service/google/callback

  5. After creating the app, note the Client ID and Client Secret.

  6. Add the following to your .env file or docker-compose.yaml:

    GOOGLE_APP_ID={client_id}
GOOGLE_APP_SECRET={client_secret}

Users can now register and log in using their Google accounts.

GitHub Authentication

  1. Go to your GitHub Developer Applications and click Register new application.

  2. Enter an application name and add your BookStack instance URL under Homepage URL and Authorization callback URL.

  3. Save the Client ID and Client Secret.

  4. Add the following to your .env file or docker-compose.yaml:

    GITHUB_APP_ID={client_id}
GITHUB_APP_SECRET={client_secret}

Users can now log in with their GitHub accounts.

Twitter Authentication

  1. Sign up at the Twitter Developer Portal and get approved for API access.

  2. Create a new app, then add the following callback URLs (replace https://example.com with your domain):

    https://example.com/login/service/twitter/callback
https://example.com/register/service/twitter/callback
  3. Add the API key and API secret key to your .env file or docker-compose.yaml:
    TWITTER_APP_ID={api_key}
TWITTER_APP_SECRET={api_secret}

Users can now log in with their Twitter accounts.

Facebook Authentication

  1. Go to the Facebook Developers Portal and create a new app.

  2. In the Facebook login settings, add the following redirect URIs:

    https://example.com/login/service/facebook/callback
https://example.com/register/service/facebook/callback
  3. Add the App ID and App Secret to your .env file or docker-compose.yaml:
    FACEBOOK_APP_ID={app_id}
FACEBOOK_APP_SECRET={app_secret}

Users can now log in with their Facebook accounts.

Slack Authentication

  1. Go to the Slack Apps page and create a new app.

  2. In OAuth & Permissions, add your BookStack URL to the Redirect URLs.

  3. Add the Client ID and Client Secret to your .env file or docker-compose.yaml:

    SLACK_APP_ID={client_id}
SLACK_APP_SECRET={client_secret}

Users can now log in with their Slack accounts.

AzureAD (Microsoft) Authentication

  1. In the Azure Portal, go to Azure Active Directory > App registrations and create a new registration.

  2. Add the following redirect URIs:

    https://example.com/login/service/azure/callback
  3. Add the App ID, App Secret, and Tenant ID to your .env file or docker-compose.yaml:
    AZURE_APP_ID={app_id}
AZURE_APP_SECRET={app_secret}
AZURE_TENANT={tenant_id}

Users can now log in with their AzureAD accounts.

Okta Authentication

  1. In the Okta Admin Panel, create a new app with Web platform and OpenID Connect method.

  2. Add the following callback URLs:

    https://example.com/login/service/okta/callback
https://example.com/register/service/okta/callback
  3. Add the Client ID, Client Secret, and Base URL to your .env file or docker-compose.yaml:
    OKTA_APP_ID={client_id}
OKTA_APP_SECRET={client_secret}
OKTA_BASE_URL={base_url}

Users can now log in with their Okta accounts.

Twitch Authentication

  1. In the Twitch Developer Dashboard, create a new application.

  2. Add the following redirect URIs:

    https://example.com/login/service/twitch/callback
  3. Add the Client ID and Client Secret to your .env file or docker-compose.yaml:
    TWITCH_APP_ID={client_id}
TWITCH_APP_SECRET={client_secret}

Users can now log in with their Twitch accounts.

Discord Authentication

  1. In the Discord Developer Portal, create a new application.

  2. Add the following redirect URIs:

    https://example.com/login/service/discord/callback
  3. Add the Client ID and Client Secret to your .env file or docker-compose.yaml:
    DISCORD_APP_ID={client_id}
DISCORD_APP_SECRET={client_secret}

Users can now log in with their Discord accounts.

Back to top