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 [A video guide for setting up SAML2 can be found here](https://foss.video/w/jJGmXS8sK244YFgogAz8LP).
  11
  12 ### BookStack Configuration
  13
  14 To set up SAML 2.0 based authentication add or modify the following variables in your `.env` file:
  15
  16 ```bash
  17 # Set authentication method to be saml2
  18 AUTH_METHOD=saml2
  19
  20 # Control if BookStack automatically initiates login via your SAML system if it's the only authentication method.
  21 # Prevents the need for the user to click the "Login with x" button on the login page.
  22 # Setting this to true enables auto-initiation.
  23 AUTH_AUTO_INITIATE=false
  24
  25 # Set the display name to be shown on the login button.
  26 # (Login with <name>)
  27 SAML2_NAME=SSO
  28
  29 # Name of the attribute which provides the user's email address
  30 SAML2_EMAIL_ATTRIBUTE=email
  31
  32 # Name of the attribute to use as an ID for the SAML user.
  33 SAML2_EXTERNAL_ID_ATTRIBUTE=uid
  34
  35 # Name of the attribute(s) to use for the user's display name
  36 # Can have multiple attributes listed, separated with a '|' in which
  37 # case those values will be joined with a space.
  38 # Example: SAML2_DISPLAY_NAME_ATTRIBUTES=firstName|lastName
  39 # Defaults to the ID value if not found.
  40 SAML2_DISPLAY_NAME_ATTRIBUTES=username
  41
  42 # Identity Provider entityID URL
  43 SAML2_IDP_ENTITYID=https://example.com/saml2/idp/metadata.php
  44
  45 # Auto-load metadata from the IDP
  46 # Setting this to true negates the need to specify the next three options
  47 SAML2_AUTOLOAD_METADATA=false
  48
  49 # Identity Provider single-sign-on service URL
  50 # Not required if using the autoload option above.
  51 SAML2_IDP_SSO=https://example.com/saml2/idp/SSOService.php
  52
  53 # Identity Provider single-logout-service URL
  54 # Not required if using the autoload option above.
  55 # Not required if your identity provider does not support SLS.
  56 SAML2_IDP_SLO=https://example.com/saml2/idp/SingleLogoutService.php
  57
  58 # Identity Provider x509 public certificate data.
  59 # Not required if using the autoload option above.
  60 SAML2_IDP_x509=<cert_data>
  61
  62 # Identity Provider AuthnContext
  63 # Setting this to true (The default) and exact AuthnContext of
  64 # 'urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport' will be used.
  65 # Setting this to false will provide no AuthnContext to the IDP.
  66 # Alternatively you can set this to a space separated list of values. For example:
  67 # SAML2_IDP_AUTHNCONTEXT="urn:oasis:names:tc:SAML:2.0:ac:classes:Password urn:federation:authentication:windows"
  68 SAML2_IDP_AUTHNCONTEXT=true
  69
  70 # Service Provider Certificate & Key (Optional)
  71 # Providing these will provide key data within BookStack's metadata endpoint
  72 # while implicitly enabling signing on Authn and Logout requests.
  73 # This is often required to support Single Logout Service in an ADFS environment.
  74 SAML2_SP_x509=<cert_data>
  75 SAML2_SP_x509_KEY=<key_data>
  76 ```
  77
  78 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.
  79
  80 ### Identity Provider Configuration
  81
  82 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.
  83
  84 * `/saml2/metadata` - Metadata endpoint *(GET)*
  85 * `/saml2/acs` - Assertion Consumer Service endpoint *(POST)*
  86 * `/saml2/sls` - Single Logout Service endpoint *(GET)*
  87
  88 BookStack uses the following formats/bindings for communication with the IdP:
  89
  90 * NameIDFormat: `urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress`
  91 * Login/ACS Binding: `urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST`
  92 * Logout/SLO Binding: `urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect`
  93
  94 Here's a minimal example of configuring a BookStack service provider for a SimpleSAMLphp IdP:
  95
  96 ```php
  97 $metadata['http://bookstack.local/saml2/metadata'] = [
  98     'AssertionConsumerService' => 'http://bookstack.local/saml2/acs',
  99     'SingleLogoutService' => 'http://bookstack.local/saml2/sls',
 100     'NameIDFormat' => 'urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress',
 101 ];
 102 ```
 103
 104 ### Debugging
 105
 106 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:
 107
 108 ```bash
 109 # Enable the BookStack general debug mode, Provides more error insight.
 110 # Note, Can leak sensitive details so only use in private, secure environments.
 111 APP_DEBUG=true
 112
 113 # Option to dump out SAML 2.0 user details as JSON.
 114 # Only for debugging purposes since it will prevent login.
 115 SAML2_DUMP_USER_DETAILS=false
 116
 117 # Option to override settings passed to the underlying onelogin library
 118 # used by BookStack. For development, debugging and testing only.
 119 # Options provided will be recursively merged into other default & dynamic options.
 120 # Defaults found within app/Config/saml2.php, under the 'onelogin' key.
 121 SAML2_ONELOGIN_OVERRIDES=<json_format_data>
 122 ```
 123
 124 ### SAML Group Sync
 125
 126 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.
 127 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. Commas can be escaped with a backslash (`\,`) if you need to map using a literal comma character.
 128
 129 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.
 130
 131 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.
 132
 133 Here are the settings required to be added to your `.env` file to enable group syncing:
 134
 135 ```bash
 136 # Enable SAML group sync.
 137 SAML2_USER_TO_GROUPS=true
 138
 139 # Set the attribute from which BookStack will read groups names from.
 140 SAML2_GROUP_ATTRIBUTE=groups
 141
 142 # Remove the user from roles that don't match SAML groups upon login.
 143 # Note: While this is enabled the "Default Registration Role", editable within the
 144 # BookStack settings view, will be considered a matched role and assigned to the user.
 145 SAML2_REMOVE_FROM_GROUPS=true
 146 ```