BookStack Code Mirror - website/blob - 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 id* value stored with your Bookstack user. If this match cannot be made, BookStack will effectively
 14 auto-register that user to provide a seamless access experience. They will be given the
 15 default role set under the "Default user role after registration" option in the
 16 application settings.
 17
 18 ### Requirements & Limitations
 19
 20 Listed below are some considerations to keep in mind in regard to BookStack's OIDC implementation:
 21
 22 - Only RS256 is currently supported as a token signing algorithm, Token encryption is not supported.
 23 - Discovery covers fetching the auth & token endpoints, in addition to parsing any keys at the JWKS URI,
 24   from the `<issuer>/.well-known/openid-configuration` endpoint.
 25   - Issuer discovery is not supported.
 26 - Group/Role handling is not currently supported but feedback, in the form of IDP-provided group examples, is welcome to help future implementation.
 27
 28 ### BookStack Configuration
 29
 30 To set up OIDC based authentication add or modify the following variables in your `.env` file:
 31
 32 ```bash
 33 # Set OIDC to be the authentication method
 34 AUTH_METHOD=oidc
 35
 36 # Set the display name to be shown on the login button.
 37 # (Login with <name>)
 38 OIDC_NAME=SSO
 39
 40 # Name of the claims(s) to use for the user's display name.
 41 # Can have multiple attributes listed, separated with a '|' in which
 42 # case those values will be joined with a space.
 43 # Example: OIDC_DISPLAY_NAME_CLAIMS=given_name|family_name
 44 OIDC_DISPLAY_NAME_CLAIMS=name
 45
 46 # OAuth Client ID to access the identity provider
 47 OIDC_CLIENT_ID=abc123
 48
 49 # OAuth Client Secret to access the identity provider
 50 OIDC_CLIENT_SECRET=def456
 51
 52 # Issuer URL
 53 # Must start with 'https://'
 54 OIDC_ISSUER=https://instance.authsystem.example.com
 55
 56 # Enable auto-discovery of endpoints and token keys.
 57 # As per the standard, expects the service to serve a
 58 # `<issuer>/.well-known/openid-configuration` endpoint.
 59 OIDC_ISSUER_DISCOVER=true
 60
 61 ############################################################
 62 ## NOTE: The below are only needed if not using the above ##
 63 ##       auto-discovery option.                           ##
 64 ############################################################
 65
 66 # Path to identity provider token signing public RSA key
 67 OIDC_PUBLIC_KEY=file:///keys/idp-public-key.pem
 68
 69 # Full URL to the OIDC authorize endpoint
 70 OIDC_AUTH_ENDPOINT=https://instance.authsystem.example.com/v1/authorize
 71
 72 # Full URL to the OIDC token endpoint
 73 OIDC_TOKEN_ENDPOINT=https://instance.authsystem.example.com/v1/token
 74 ```
 75
 76 A user in BookStack will be linked to an OIDC provided account via the `sub` claim.
 77 If the value of this ID changes in the identity provider it can be updated in BookStack,
 78 by an admin, by changing the "External Authentication ID" field on the user's profile.
 79
 80 ### Callback URL
 81
 82 Should your OIDC provider require a callback URL, the following can be used: `https://example.com/oidc/callback`.
 83 Change `https://example.com` to be the base URL of your BookStack instance.
 84
 85 ### Debugging
 86
 87 To help when setting up or configuring BookStack to use your OIDC system, the below
 88 `.env` option can help provide more insight:
 89
 90 ```bash
 91 # Dump out the details fetched from the identity provider.
 92 # Only set this option to true if debugging since it will block logins
 93 # and potentially show private details.
 94 OIDC_DUMP_USER_DETAILS=false
 95 ```
 96
 97 Further to this, details of any BookStack errors encountered can be found by following
 98 our [general debugging documentation](/docs/admin/debugging/).