Setting up SSO Authorization for BookStack

One of the most successful services (among those known to me) for storing internal documentation is BookStack. You can read how to deploy it and perform basic setup on the OF website, there is excellent documentation there. But the question of setting up SSO authorization using ADFS is information that is quite superficial, and even what can be found on the internet requires fairly deep knowledge of the topic. Therefore, I decided to share a compilation of information on this issue.

Setting up BookStack

Doesn't require a lot of settings, just edit .envfile,

 nano /var/www/bookstack/.env

By adding the following content to the end of the file:

AUTH_METHOD=saml2
AUTH_AUTO_INITIATE=true
SAML2_NAME=ADFS
SAML2_EMAIL_ATTRIBUTE=mail
SAML2_EXTERNAL_ID_ATTRIBUTE=http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn
SAML2_DISPLAY_NAME_ATTRIBUTES=displayName
SAML2_IDP_ENTITYID=https://adfs.*****.com/FederationMetadata/2007-06/FederationMetadata.xml
SAML2_AUTOLOAD_METADATA=true
SAML2_IDP_SSO=https://adfs.******.com/adfs/ls
SAML2_IDP_SLO=null
SAML2_IDP_AUTHNCONTEXT=true
SAML2_USER_TO_GROUPS=true
SAML2_GROUP_ATTRIBUTE=groups
SAML2_REMOVE_FROM_GROUPS=false



#APP_DEBUG=true
#SAML2_DUMP_USER_DETAILS=true
#SAML2_ONELOGIN_OVERRIDES=<json_format_data>

Setting up ADFS Server

Let's create Relaying Party trusts

Open the Relaying Party trusts snap-in after Click Add Relaying Party trusts

Next, select Claims aware and click Start

Select Data Source

Select Enter data about the relying parity manually

Let's set the Display Name

Give any clear name in the Display Name field

Certificate Configuration

Skip the certificate configuration by clicking next

URL Configuration

Select the item “Enable support for the SAML2.0” and then indicate in the field

https://book.***Ваш домен***.com/saml2/acs

Let's configure the identifiers

In the Relying party trust identifilers field, insert

https://book.*******.com/saml2/metadata

and click ADD

Let's choose an authorization policy

in the list provided, select Permit everyone

On the finish tab, uncheck the box next to Configure claims issuance policy for this application

Setting up connection points

Open the properties of the created Party trusts and go to the Endpoints tab

Let's check the created assertion consumer endpoint

After which we will create Logout Endpoints, for this we click

and fill it in according to the screenshot

Setting up requirements issuance

Let's create a matching rule for value fields

in the window that appears, click Add Rule

Fill in the field as follows

c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname", Issuer == "AD AUTHORITY"]
 => issue(store = "Active Directory", types = ("http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn", "mail", "groups", "displayName"), query = ";userPrincipalName,otherMailbox,tokenGroups,displayName;{0}", param = c.Value);

Let's create a value conversion rule

click Add Rule

Fill in the field as follows

c:[Type == "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn"]
 => issue(Type = "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier", Issuer = c.Issuer, OriginalIssuer = c.OriginalIssuer, Value = c.Value, ValueType = c.ValueType, Properties["http://schemas.xmlsoap.org/ws/2005/05/identity/claimproperties/format"] = "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress");

Done, you can check

Troubleshooting

to test the operation of ADFS, to view the information returned by ADFS in the browser in json format. The server can be uncommented in the file .env

APP_DEBUG=true
SAML2_DUMP_USER_DETAILS=true
SAML2_ONELOGIN_OVERRIDES=<json_format_data>

In this mode, AUTHORIZATION WILL BE DISABLED