]> BookStack Code Mirror - website/blob - content/docs/admin/oidc-auth.md
Updated hacks
[website] / content / docs / admin / oidc-auth.md
1 +++
2 title = "OpenID Connect Authentication"
3 description = "How to use an OpenID Connect identity provider as your primary way to access BookStack"
4 date = "2021-10-21"
5 type = "admin-doc"
6 +++
7
8 OpenID Connect (OIDC) can be used within BookStack as a primary method of authentication.
9 This replaces the default email & password authentication mechanism.
10 BookStack supports a simple level of auto-discovery to ease endpoint and key management.
11
12 When used, BookStack will attempt to match the OIDC user to an existing BookStack user
13 based on the "External Authentication ID" value stored against the Bookstack user. 
14 If this match cannot be made, BookStack will effectively auto-register that user to 
15 provide a seamless access experience. They will be given the default role set under the
16 "Default user role after registration" option in the application settings.
17
18 {{<toc>}}
19
20 ### Video Guides
21
22 We have a range of videos available that can help show, for a range of identity platforms, the exact steps required to set-up a BookStack OpenID Connect authentication integration:
23
24 - [General setup guide (Using Okta as an example)](https://foss.video/w/1b6sc98un7ugGv98v9UaRC)
25 - [Azure Active Directory OIDC Guide](https://foss.video/w/n67qNijhf8BdTRQys8SDYf)
26 - [Authentik BookStack OIDC Guide](https://foss.video/w/a744K8GxFF1LqBFSadAsuV)
27
28 ### Requirements & Limitations
29
30 Listed below are some considerations to keep in mind in regard to BookStack's OIDC implementation:
31
32 - Only RS256 is currently supported as a token signing algorithm, Token encryption is not supported. This applies to both ID tokens and userinfo responses.
33 - Discovery covers fetching the auth & token endpoints, in addition to parsing any keys at the JWKS URI,
34   from the `<issuer>/.well-known/openid-configuration` endpoint.
35   - Issuer discovery is not supported.
36 - RP-initiated logout is supported if enabled, but any other logout mechanisms are not supported.
37
38 ### BookStack Configuration
39
40 To set up OIDC based authentication add or modify the following variables in your `.env` file:
41
42 ```bash
43 # Set OIDC to be the authentication method
44 AUTH_METHOD=oidc
45
46 # Control if BookStack automatically initiates login via your OIDC system 
47 # if it's the only authentication method. Prevents the need for the
48 # user to click the "Login with x" button on the login page.
49 # Setting this to true enables auto-initiation.
50 AUTH_AUTO_INITIATE=false
51
52 # Set the display name to be shown on the login button.
53 # (Login with <name>)
54 OIDC_NAME=SSO
55
56 # Name of the claims(s) to use for the user's display name.
57 # Can have multiple attributes listed, separated with a '|' in which 
58 # case those values will be joined with a space.
59 # Example: OIDC_DISPLAY_NAME_CLAIMS=given_name|family_name
60 OIDC_DISPLAY_NAME_CLAIMS=name
61
62 # OAuth Client ID to access the identity provider
63 OIDC_CLIENT_ID=abc123
64
65 # OAuth Client Secret to access the identity provider
66 OIDC_CLIENT_SECRET=def456
67
68 # Issuer URL
69 # Must start with 'https://'
70 OIDC_ISSUER=https://instance.authsystem.example.com
71
72 # The "end session" (RP-initiated logout) URL to call during BookStack logout.
73 # By default this is false which disables RP-initiated logout.
74 # Setting to "true" will enable logout if found as supported by auto-discovery.
75 # Otherwise, this can be set as a specific URL endpoint.
76 OIDC_END_SESSION_ENDPOINT=false
77
78 # Enable fetching of the user's avatar from the 'picture' claim on login.
79 # Will only be fetched if the user doesn't already have an avatar image assigned.
80 # By default this is false which disables avatar fetching. Set to 'true' to enable.
81 # WARNING: This can be a security risk due to performing server-side fetching 
82 # (with up to 3 redirects) of data from external URLs. Only enable if you
83 # trust the OIDC auth provider to provide safe URLs for user images.
84 OIDC_FETCH_AVATAR=false
85
86 # Enable auto-discovery of endpoints and token keys.
87 # As per the standard, expects the service to serve a 
88 # `<issuer>/.well-known/openid-configuration` endpoint.
89 OIDC_ISSUER_DISCOVER=true
90
91 ############################################################
92 ## NOTE: The below are only needed if not using the above ##
93 ##       auto-discovery option.                           ##
94 ############################################################
95
96 # Path to identity provider token signing public RSA key
97 OIDC_PUBLIC_KEY=file:///keys/idp-public-key.pem
98
99 # Full URL to the OIDC authorize endpoint
100 OIDC_AUTH_ENDPOINT=https://instance.authsystem.example.com/v1/authorize
101
102 # Full URL to the OIDC token endpoint
103 OIDC_TOKEN_ENDPOINT=https://instance.authsystem.example.com/v1/token
104
105 # Full URL to the OIDC userinfo endpoint
106 # Won't be used if all required claims are provided in the ID token.
107 OIDC_USERINFO_ENDPOINT=https://instance.authsystem.example.com/v1/userinfo
108 ```
109
110 A user in BookStack will be linked to an OIDC provided account via the `sub` claim.
111 If the value of this ID changes in the identity provider it can be updated in BookStack, 
112 by an admin, by changing the "External Authentication ID" field on the user's profile.
113
114 ### Authentication System Configuration
115
116 With OIDC you don't often need to configure much specifically for BookStack.
117 Most often, you'll just need to ensure any callback/redirect URIs are set as below:
118
119 - **Login Callback/Redirect URI:** `https://example.com/oidc/callback`
120 - **Logout Callback/Redirect URIs:**
121   - `https://example.com`
122   - `https://example.com/login`
123   - `https://example.com/login?prevent_auto_init=true`
124   - *Only one URL will actually be used but it depends upon specific configuration set. Some systems will allow you to instead use a wildcard like `https://example.com/*`.*
125
126 Change `https://example.com` to be the base URL of your BookStack instance.
127
128 Since v24.02 BookStack will make use of Proof Key for Code Exchange (PKCE) during authentication. 
129 If your authentication system provides the option, you should enforce PKCE to be required for extra security.
130
131 ### Switching to OIDC with Existing Users
132
133 When switching `AUTH_METHOD` from `standard` to `oidc`, BookStack will not 
134 link OIDC user accounts to existing BookStack users, where the email address is 
135 matching, since the "External Authentication ID" value of the existing BookStack user does 
136 not match the unique user ID provided by the OIDC system.
137
138 You can overcome this situation by logging into BookStack with an admin account while `AUTH_METHOD=standard`.
139 While logged in, change `AUTH_METHOD` to `oidc`.
140 This change of authentication method will show an "External Authentication ID" text
141 field, below the name and email inputs, when viewing a user account in BookStack.
142 Here you can enter the unique user ID that would be provided by your OIDC provider.
143 Once saved BookStack will then use this value to match OIDC and BookStack user 
144 accounts upon next login attempt.
145
146 If you need to update accounts in bulk, you could instead directly update the 
147 `external_auth_id` field of the `users` table within your BookStack database.
148
149 ### Debugging
150
151 To help when setting up or configuring BookStack to use your OIDC system, the below
152 `.env` option can help provide more insight:
153
154 ```bash
155 # Dump out the details fetched from the identity provider.
156 # Only set this option to true if debugging since it will block logins
157 # and potentially show private details.
158 OIDC_DUMP_USER_DETAILS=false
159 ```
160
161 Further to this, details of any BookStack errors encountered can be found by following
162 our [general debugging documentation](/docs/admin/debugging/).
163
164 ### Using a Different ID Claim
165
166 By default, BookStack will use the `sub` claim as a unique identifier to match up a user
167 between BookStack and the identify provider.
168 For the vast majority of use-cases, this is fine since this claim is part of the 
169 OIDC standard.
170
171 In some very select scenarios, you may want to use a different claim as the unique identifier.
172 This can be done by setting an `OIDC_EXTERNAL_ID_CLAIM` option in your `.env` like shown below,
173 where the value of the option is the name of the claim:
174
175 ```bash
176 # Configure a custom ID Token claim to be used as the
177 # "External Authentication ID" within BookStack.
178 OIDC_EXTERNAL_ID_CLAIM=upn
179 ```
180
181 Note that changing this with existing BookStack OIDC users, without changing their "External Authentication ID" values,
182 may cause issues upon future login since their existing store ID in BookStack may no longer align.
183
184 ### Group Sync
185
186 BookStack has the ability to sync OIDC user groups with BookStack roles.
187 By default this will match OIDC group names with the BookStack role display names with casing ignored.
188 This can be overridden by via the 'External Authentication IDs' field which can be seen when editing a role while OIDC authentication is enabled.
189 If filled, the names in this field will be used and the BookStack role display name will be ignored.
190 You can match on multiple names by separating them with a comma.
191 Commas can be escaped with a backslash (`\,`) if you need to map using a literal comma character.
192
193 When matching OIDC groups with role names or 'External Authentication IDs' values, BookStack will standardise the names of OIDC groups to be lower-cased and spaces will be replaced with hyphens. For example, to match a OIDC group named "United Kingdom" an 'External Authentication IDs' value of "united-kingdom" could be used.
194
195 This feature requires the OIDC server to provide a claim in the ID token with an array of group names.
196 You'll need to specify the attribute using the `OIDC_GROUPS_CLAIM` to tell BookStack what claim it can find groups on. This value can use dot-notation to access nested properties in the ID token JSON data, an example of which can be [found below](#nested-groups-claim-example).
197
198 Keep in mind you can use the `OIDC_DUMP_USER_DETAILS` option, as shown in the above [debugging](#debugging) section to dump out claim values provided by your authentication system to help understand what is being provided by your authentication system.
199
200 Here are the settings required to be added to your `.env` file to enable group syncing:
201
202 ```bash
203 # Enable OIDC group sync.
204 OIDC_USER_TO_GROUPS=true
205
206 # Set the attribute from which BookStack will read groups names from.
207 OIDC_GROUPS_CLAIM=groups
208
209 # Additional scopes to send with the authentication request.
210 # By default BookStack only sends the 'openid', 'profile' & 'email' scopes.
211 # Many platforms require specific scopes to be requested for group data.
212 # Multiple scopes can be added via comma separation.
213 OIDC_ADDITIONAL_SCOPES=groups
214
215 # Remove the user from roles that don't match OIDC groups upon login.
216 # Note: While this is enabled the "Default Registration Role", editable within the 
217 # BookStack settings view, will be considered a matched role and assigned to the user.
218 OIDC_REMOVE_FROM_GROUPS=true
219 ```
220
221 #### Nested Groups Claim Example
222
223 The below shows a reduced example of JSON data for an ID token, that has group data within a nested property,
224 along with the `OIDC_GROUPS_CLAIM` value that would be used for this structure to detect the provided "Editor" and "Admin" roles.
225
226 ```bash
227 OIDC_GROUPS_CLAIM=resource_access.bookstack.roles
228 ```
229
230 ```json
231 {
232   ...
233   "resource_access": {
234     "bookstack": {
235       "roles": [
236         "Editor",
237         "Admin"
238       ]
239     }
240   },
241   "email": "[email protected]"
242   ...
243 }
244 ```