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 (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. While

    Gologged toin, open up your GitHub Developerdeveloper Applicationsapplications.

    2. and
  2. Click click ‘Register new applicationapplication’.

  3. Enter an application name (‘BookStack’ or your custom set name) and adda link to your app instance under ‘Homepage URL’. The ‘Authorization callback URL’ can be the root (homepage) URL for your BookStack instanceinstance. URLOnce underthose Homepagedetails URLare set, select ‘Register application’.

  4. A ‘Client ID’ and Authorizationa callback URL.

  5. Save the ‘Client IDSecret’ andvalue Clientwill Secret.

    be
    6. shown.
  6. Add

    Addor set the following toitems in your BookStack .env file orlike docker-compose.yaml:so:

    # Replace the '{client_id}' and '{client_secret}' below with your GitHub Client ID and Client secret
GITHUB_APP_ID={client_id}
GITHUB_APP_SECRET={client_secret}

Users can now log in with their GitHub accounts.

Twitter Authentication

Before creating a Twitter application for signing in, you will need to have signed up and be approved on the Twitter Developer site. Part of this will require describing your use of the API.

  1. Go

    Signto up at theyour Twitter Developer Portal, after being approved by twitter as described above. Navigate to ‘Projects and getApps’ approved> ‘Overview’ and under ‘Standalone Apps’ click ‘Create App’.

  2. Enter an application name and save/continue to the next step.
  3. You’ll now be shown some keys and tokens. Copy out the shown ‘API key’ and ‘API secret key’ values for APIthe access.

    next step.
  4. Within

    Createyour aBookStack .env file add in extra options for your token and secret like so:

    # Replace the below '{api_key}' and '{api_secret}' with your Twitter API key and API secret
TWITTER_APP_ID={api_key}
TWITTER_APP_SECRET={api_secret}
    Back within the Twitter developer dashboard, find your new app,standalone app and click on ‘App Settings’ then addclick on edit within the ‘Authentication settings’ section.
  1. Enable the ‘3-legged OAuth’ and ‘Request email address from users’ options.
  2. Enter the following callback URLs (replaceunder ‘Callback URLs’, changing https://example.com withto your domain):

    own 
    domain where BookStack is hosted:

      

    • https://example.com/login/service/twitter/callback
      • 

    • https://example.com/register/service/twitter/callback
  3. AddFill thein APIany keyremaining andrequired APIURLs secretthen keyclick to your .env file or docker-compose.yaml:
    TWITTER_APP_ID={api_key}
TWITTER_APP_SECRET={api_secret}
    save.

Users can now log in with their Twitter accounts.

Facebook Authentication

  1. GoNavigate to the Facebook Developersdevelopers Portalpage then go ‘My Apps’ -> ‘Add a New App’.

  2. Enter an app name (‘BookStack login’ or something custom) and createcontact email then continue.
  3. In your new app select ‘Add Product’ on the left sidebar then choose ‘Facebook Login’ by clicking the ‘Get Started’ button. Select the ‘Web’ option if asked to choose a new app.

    platform.

  4. InEnter the your base BookStack url into the ‘Site URL’ box and save.

  5. On the left sidebar again go to ‘Facebook loginLogin’ settings,-> add‘Settings’.
  6. Enter the following redirectURLs URIs:

    under 
    ‘Valid OAuth Redirect URIs’, changing https://example.com to your own domain where BookStack is hosted:

      

    • https://example.com/login/service/facebook/callback
      • 

    • https://example.com/register/service/facebook/callback
  7. AddNavigate back to the Appapp ID‘Dashboard’ in the sidebar to find your app id and Appsecret. SecretAdd or set these to your .env file orlike docker-compose.yaml:so:
    # Replace the below '{app_id}' and '{app_secret}' with your Facebook app ID and secret
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 Appsapps page and createselect a‘Create An App’, then ‘From scratch’ when prompted.

  2. Enter an app name (‘BookStack login’ or something custom) and your workspace then select “Create App”.
  3. Within an “App Credentials” section, you should find your client ID and secret. Copy these details and add them as new app.

    variables

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

  5. Add the Client ID and Client Secret toin your .env file orlike docker-compose.yaml:so:

    # Replace the below '{client_id}' and '{client_secret}' with your Slack client ID and secret
SLACK_APP_ID={client_id}
SLACK_APP_SECRET={client_secret}
  6. In your slack app go to ‘OAuth & Permissions’, find the ‘Redirect URLs’ section then ‘Add New Redirect URL’. Enter your BookStack base URL then ‘Add’ before pressing ‘Save URLs’.

Users can now log in with their Slack accounts.

AzureAD (Microsoft) Authentication

Note: If you intend all users to access your instance via Azure, then using an alternative primary authentication option like OIDC or SAML 2.0 will provide a better user experience while having more features like auto-login and group sync. A video guide for setting up OIDC with AzureAD can be found here.

  1. Login

    Into your your azure portal and navigate to the ‘Azure Portal,Activity goDirectory’ area.

  2. Under ‘Manage > App registrations’ select ‘New application registration’.
  3. Enter a name (‘BookStack’). Set the ‘Redirect URI’ to Azurethe Active“Web” Directoryplatform > App registrations and create a new registration.

  4. Addwith the followingvalue redirectset URIs:

    to 
    the following, replacing ‘https://example.com/' with your base BookStack url:

      

    • https://example.com/login/service/azure/callback
  5. AddOnce created, View the Appapplication ID,‘Overview’ App Secret,page and Tenantnote IDthe ‘Application (client) ID’ and ‘Directory (tenant) ID’ values. These are the APP_ID and TENANT values for step 9.
  6. Within your application in azure, Navigate to ‘Certificates & secrets’ then choose ‘New client secret’.
  7. Enter any description you want and set an expiry duration. Then click ‘Save’.
  8. Copy the string of characters under ‘Value’. This is the APP_SECRET value for step 9 and is only shown once.
  9. Navigate to ‘API permissions’ for your app. You should already have a “Microsoft Graph” > “User.Read” permission assigned. If not choose ‘Add a permission’. Find the ‘Microsoft Graph’ option within this, then select ‘Delegated permissions’ then find & select the ‘User.Read’ permission. Then select ‘Add permissions’ at the bottom of the page.
  10. Copy these details and add them as new variables in your .env file orlike docker-compose.yaml:so:
    # Replace the below '{APP_ID}', '{APP_SECRET}' and '{TENANT}' values with your Azure APP_ID and APP_SECRET and TENANT
AZURE_APP_ID={app_id}APP_ID}
AZURE_APP_SECRET={app_secret}APP_SECRET}
AZURE_TENANT={tenant_id}TENANT}

Users can now log in with their AzureAD accounts.

Okta Authentication

Note: If you intend all users to access your instance via Okta, then using an alternative primary authentication option like OIDC or SAML 2.0 will provide a better user experience while having more features like auto-login and group sync.

  1. Login

    Into Okta and, once logged in, Note the Oktacurrent URL. This is used for the ‘base_url’ in step 6.

  2. Navigate to the Admin Panel,panel createthen ‘Applications’ then select ‘Add Application’. Then select ‘Create New App’ on the left.
  3. For the ‘Platform’ choose ‘Web’. For the ‘Sign on method’ choose ‘OpenID Connect’ then click ‘Create’.
  4. Give the app a newname appsuch withas Web‘BookStack’ platformor and‘Our OpenIDdocumentation’. Connect method.

  5. AddUnder the following‘Login callbackredirect URLs:

    URIs’ 
    option add both of the below URLs, Changing https://example.com to the base URL of your BookStack instance:

      

    • https://example.com/login/service/okta/callback
      • 

    • https://example.com/register/service/okta/callback
  6. AddSave and scroll down to the ‘Client ID,Credentials’ area. Copy the ‘Client Secret,ID’ and Base‘Client URLsecret’ tovalues for the next step.
  7. Copy these details and add them as new variables in your .env file orlike docker-compose.yaml:so:
    # Replace the below '{client_id}' and '{client_Secret}' with your Okta client ID and secret
OKTA_APP_ID={client_id}
OKTA_APP_SECRET={client_secret}
# Replace the '{base_url}' below with the URL from step 1
# but with everything after the domain (okta.com) removed.
OKTA_BASE_URL={base_url}

Users can now log in with their Okta accounts.

Twitch Authentication

To allow Twitch sign-in you’ll first need to create an application from the Twitch developer site. Here’s the process:

  1. Login

    Ininto the Twitch Developerdeveloper Dashboardwebsite,.

    2. create
  2. Navigate to your ‘Dashboard’ then ‘Apps’ and select ‘Register Your Application’.
  3. Set a newname application.

    to

  4. Addidentify the followingapplication, redirectsuch URIs:

    as 
    ‘BookStack Authentication’, and in the ‘OAuth Redirect URI’ input add the below URL, Changing https://example.com to the base URL of your BookStack instance:

      

    • https://example.com/login/service/twitch/callback
  5. AddUnder the Client‘Application IDCategory’ option select ‘Website Integration’ then hit ‘Register’.
  6. Click the ‘New Secret’ button and accept the prompt that appears. You should now see both a ‘Client SecretID’ toand ‘Client Secret’ value which you’ll use in the next step.
  7. Copy the below details and add them as new variables in your .env file orlike docker-compose.yaml:so:
    # Replace the below '{client_id}' and '{client_secret}' with your Twitch client ID and secret values.
TWITCH_APP_ID={client_id}
TWITCH_APP_SECRET={client_secret}

Users can now log in with their Twitch accounts.

Discord Authentication

To allow Discord sign-in you’ll first need to create an application on the Discord developer site. Here’s the process:

  1. Login

    Ininto the Discord Developerdeveloper Portalwebsite,.

    2. create
  2. Select ‘Create an application’.
  3. Set a newname application.

    to identify the application, such as ‘BookStack Authentication’, and save.

  4. AddIn the followingsidebar, redirectOpen URIs:

    the 
    OAuth2 settings for your application and add a redirect. Input the below URL, Changing https://example.com to be the base URL of your BookStack instance then save:

      

    • https://example.com/login/service/discord/callback
  5. AddBack in the ‘General Information’ section find the ‘Client IDID’ and ‘Client SecretSecret’ tovalues which you’ll use in the next step.
  6. Copy the below details and add them as new variables in your .env file orlike docker-compose.yaml:so:
    # Replace the below '{client_id}' and '{client_secret}' with your Discord client ID and secret values.
DISCORD_APP_ID={client_id}
DISCORD_APP_SECRET={client_secret}

Users can now log in with their Discord accounts.

Back to top