BookStack Code Mirror - website/blob - content/docs/admin/saml2-auth.md

   1 +++
   2 title = "SAML 2.0 Authentication"
   3 description = "How to use SAML2 as an authentication option in BookStack"
   4 date = "2020-01-25"
   5 type = "admin-doc"
   6 +++
   7
   8 BookStack can be configured to utilise a SAML 2.0 based authentication provider as a solution for users to log-in, log-out and self-register within BookStack. This replaces the default email & password authentication mechanism within BookStack. When enabled, BookStack will attempt to match the SAML user to an existing BookStack user based on a stored external id attribute otherwise, if not found, BookStack will effectively auto-register that user to provide a seamless access experience.
   9
  10 ### BookStack Configuration
  11
  12 To set up SAML 2.0 based authentication add or modify the following variables in your `.env` file:
  13
  14 ```bash
  15 # Set authentication method to be saml2
  16 AUTH_METHOD=saml2
  17
  18 # Set the display name to be shown on the login button.
  19 # (Login with <name>)
  20 SAML2_NAME=SSO
  21
  22 # Name of the attribute which provides the user's email address
  23 SAML2_EMAIL_ATTRIBUTE=email
  24
  25 # Name of the attribute to use as an ID for the SAML user.
  26 SAML2_EXTERNAL_ID_ATTRIBUTE=uid
  27
  28 # Name of the attribute(s) to use for the user's display name
  29 # Can have mulitple attributes listed, separated with a '|' in which
  30 # case those values will be joined with a space.
  31 # Example: SAML2_DISPLAY_NAME_ATTRIBUTES=firstName|lastName
  32 # Defaults to the ID value if not found.
  33 SAML2_DISPLAY_NAME_ATTRIBUTES=username
  34
  35 # Identity Provider entityID URL
  36 SAML2_IDP_ENTITYID=https://example.com/saml2/idp/metadata.php
  37
  38 # Auto-load metatadata from the IDP
  39 # Setting this to true negates the need to specify the next three options
  40 SAML2_AUTOLOAD_METADATA=false
  41
  42 # Identity Provider single-sign-on service URL
  43 # Not required if using the autoload option above.
  44 SAML2_IDP_SSO=https://example.com/saml2/idp/SSOService.php
  45
  46 # Identity Provider single-logout-service URL
  47 # Not required if using the autoload option above.
  48 # Not required if your identity provider does not support SLS.
  49 SAML2_IDP_SLO=https://example.com/saml2/idp/SingleLogoutService.php
  50
  51 # Identity Provider x509 public certificate data.
  52 # Not required if using the autoload option above.
  53 SAML2_IDP_x509=<cert_data>
  54 ```
  55
  56 A user in BookStack will be linked to a SAML user via the `SAML2_EXTERNAL_ID_ATTRIBUTE`. If the value of this id changes in the identity provider it can be updated in BookStack by an admin by changing the 'External Authentication ID' field on the user's profile.
  57
  58 ### Identity Provider Configuration
  59
  60 You'll likely need to provide some details of your BookStack service-provider to your identity provider. Below are the URL paths you'll likely need. Only the relative paths are shown below so you'll need to append them to your BookStack base URL.
  61
  62 * `/saml2/metadata` - Metadata endpoint *(GET)*
  63 * `/saml2/asc` - Assertion Consumer Service endpoint *(POST)*
  64 * `/saml2/sls` - Single Logout Service endpoint *(GET)*
  65
  66 BookStack uses the following formats/bindings for communication with the IdP:
  67
  68 * NameIDFormat: `urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress`
  69 * ACS/SLO Binding: `urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST`
  70
  71 Here's a minimal example of configuring a BookStack service provider for a SimpleSAMLphp IdP:
  72
  73 ```php
  74 $metadata['http://bookstack.local/saml2/metadata'] = [
  75     'AssertionConsumerService' => 'http://bookstack.local/saml2/acs',
  76     'SingleLogoutService' => 'http://bookstack.local/saml2/sls',
  77     'NameIDFormat' => 'urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress',
  78 ];
  79 ```
  80
  81 ### Debugging
  82
  83 To help when setting up or configuring BookStack to use your SAML system, there are a few additional `.env` options that can help provide more insight:
  84
  85 ```bash
  86 # Enable the BookStack general debug mode, Provides more error insight.
  87 # Note, Can leak sensitive details so only use in private, secure environments.
  88 APP_DEBUG=true
  89
  90 # Option to dump out SAML 2.0 user details as JSON.
  91 # Only for debugging purposes since it will prevent login.
  92 SAML2_DUMP_USER_DETAILS=false
  93
  94 # Option to override settings passed to the underlying onelogin library
  95 # used by BookStack. For development, debugging and testing only.
  96 # Options provided will be recursively merged into other default & dynamic options.
  97 # Defaults found within app/Config/saml2.php, under the 'onelogin' key.
  98 SAML2_ONELOGIN_OVERRIDES=<json_format_data>
  99 ```
 100
 101 ### SAML Group Sync
 102
 103 BookStack has the ability to sync SAML user groups with BookStack roles. By default this will match SAML group names with the BookStack role display names with casing ignored.
 104 This can be overridden by via the 'External Authentication IDs' field which can be seen when editing a role while SAML authentication is enabled. If filled, the names in this field will be used and the role display name will be ignored. You can match on multiple names by separating them with a comma.
 105
 106 When matching SAML groups with role names or 'External Authentication IDs' values, BookStack will standardise the names of SAML groups to be lower-cased and spaces will be replaced with hyphens. For example, to match a SAML group named "United Kingdom" an 'External Authentication IDs' value of "united-kingdom" could be used.
 107
 108 This feature requires the SAML server to be able to provide user groups when queried. You'll need to specify the attribute using the `SAML2_GROUP_ATTRIBUTE` option as shown below. Keep in mind you can use the `SAML2_DUMP_USER_DETAILS` option, as shown in the above [debugging](#debugging) section to dump out the attribute values that BookStack fetches from your IdP.
 109
 110 Here are the settings required to be added to your `.env` file to enable group syncing:
 111
 112 ```bash
 113 # Enable SAML group sync.
 114 SAML2_USER_TO_GROUPS=true
 115
 116 # Set the attribute from which BookStack will read groups names from.
 117 SAML2_GROUP_ATTRIBUTE=groups
 118
 119 # Removed user from roles that don't match SAML groups upon login.
 120 SAML2_REMOVE_FROM_GROUPS=true
 121 ```