Skip to main content

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

icon.pngicon.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 (May have to wait a short while for it to be created).
    3. In ‘API and Services’ go to the ‘OAuth consent screen’ section and enter a product name (‘BookStack’ or your custom set name) along with any other required details until you can save your consent screen.
    4. Now in the ‘API and Services’ > ‘Credentials’ section click ‘Create Credentials’ > ‘OAuth client ID’.
    5. Choose an application type of ‘Web application’ and enter the following urls under ‘Authorized redirect URIs’, changing https://example.com to your own domain where BookStack is hosted:
      • https://example.com/login/service/google/callback
      • https://example.com/register/service/google/callback
    6. Hit ‘Create’ then take note of the ‘Client ID’ and ‘Client secret’ which you’ll use in the next step.
    7. Add or set the following items in your .env file like so:
      # Replace the '{client_id}' and '{client_secret}' below with your Google Client ID and Client secret
GOOGLE_APP_ID={client_id}
GOOGLE_APP_SECRET={client_secret}
      All done! Users should now be able to link their social accounts in their account profile pages and also register/login using their Google accounts.

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