BookStack ADFS SAML2 Setup

by Cody Ernesti

This post was updated on 2/15/2021 with an updated config to bypass the Single Logout issues.

In the last few weeks, v0.28 was released for BookStack, bringing lots of awesome new features and bug fixes, like their baseline API.

However, my favorite addition is the inclusion of SAML2 as a built-in authentication option. Looking through the code, they are taking advantage of the onelogin/php-saml library, which is very popular in a lot of other projects.

BookStack Setup

Not a lot of setup involved, simple edit your .env file with the following values:

## SAML Config
# Set authentication method to be saml2
AUTH_METHOD=saml2

# Set the display name to be shown on the login button.
# (Login with <name>)
SAML2_NAME=ADFS

# Name of the attribute which provides the users email address
SAML2_EMAIL_ATTRIBUTE=mail

# Name of the attribute to use as an ID for the SAML user.
SAML2_EXTERNAL_ID_ATTRIBUTE=http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn

# Name of the attribute(s) to use for the users display name
# Can have mulitple attributes listed, separated with a '|' in which
# case those values will be joined with a space.
# Example: SAML2_DISPLAY_NAME_ATTRIBUTES=firstName|lastName
# Defaults to the ID value if not found.
SAML2_DISPLAY_NAME_ATTRIBUTES=displayName

# Identity Provider entityID URL
SAML2_IDP_ENTITYID=http://sts.example.com/adfs/services/trust

# Auto-load metatadata from the IDP
# Setting this to true negates the need to specify the next three options
SAML2_AUTOLOAD_METADATA=false

# Identity Provider single-sign-on service URL
# Not required if using the autoload option above.
SAML2_IDP_SSO=https://sts.example.com/adfs/ls/

# Identity Provider single-logout-service URL
# Not required if using the autoload option above.
# Not required if your identity provider does not support SLS.
#SAML2_IDP_SLO=null

# Identity Provider x509 public certificate data.
# Not required if using the autoload option above.
SAML2_IDP_x509="MIIC2...."

ADFS Setup

I do not use ADFS with a GUI, so I don't have screenshots of what the ADFS Management MMC would show. I do however have the PowerShell and the claims rules you need.

Simply copy the claims rules into a file, and use that file in the PowerShell command provided below.

Claims Rules

@RuleTemplate = "LdapClaims"
@RuleName = "User Attributes"
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);

@RuleName = "Transform UPN to Name ID"
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");

PowerShell

Add-AdfsRelyingPartyTrust -Name Bookstack `
           -MetadataUrl https://docs.example.com/saml2/metadata `
           -IssuanceAuthorizationRules '@RuleTemplate = "AllowAllAuthzRule" => issue(Type = "http://schemas.microsoft.com/authorization/claims/permit", Value = "true");'`
           -IssuanceTransformRulesFile C:\bookstack-claimrules.txt