Shibboleth SAML2 Details #2669

New Issue

OVERLORD · 2026-02-05T04:45:18+03:00

OVERLORD commented

2026-02-05 04:45:18 +03:00

Originally created by @ssddanbrown on GitHub (Feb 24, 2022).

Below reported by user Art in the BookStack discord. Adding here for historical purposes due to being very handy info that some may search for.

Some IDPs will provide OID instead of attribute names (Shibboleth for example).

In such case, you will need to write attribute OID into settings instead of attribute names. You can enable SAML2_DUMP_USER_DETAILS=true to see whether your IDP sends attributes by their names or by UID.

Example attribute configuration:

# uid
SAML2_EXTERNAL_ID_ATTRIBUTE="urn:oid:0.9.2342.19200300.100.1.1"

# email
SAML2_EMAIL_ATTRIBUTE="urn:oid:0.9.2342.19200300.100.1.3"

# displayName
SAML2_DISPLAY_NAME_ATTRIBUTES="urn:oid:2.16.840.1.113730.3.1.241"

# member/memberOf
SAML2_GROUP_ATTRIBUTE="urn:oid:1.3.6.1.4.1.5923.1.5.1.1"

I think it would be fantastic to mention it in the documentation, and maybe in .env.example

Shibboleth IDP might refuse to log in BookStack. The reason is that BookStack metadata lacks encryption key, while Shibboleth is by default configured to encrypt assertions (auth responses). This encryption is meant to protect personal user data, but normally SSL already does this job. If assertions are encrypted, BookStack (onelogin toolkit) will decrypt them with the same key used for signing.

The solution is to provide encryption public key to Shibboleth via metadata:

copy SP metadata from your BookStack instance (https://yoursite.example/saml2/metadata)
find the element <md:KeyDescriptor use="signing">...</md:KeyDescriptor> and duplicate it
in the duplicate, replace use="signing" with use="encryption"
feed this edited metadata to the Shibboleth IDP

Originally created by @ssddanbrown on GitHub (Feb 24, 2022). > Below reported by user Art in the BookStack discord. Adding here for historical purposes due to being very handy info that some may search for. Some IDPs will provide OID instead of attribute names (Shibboleth for example). In such case, you will need to write attribute OID into settings instead of attribute names. You can enable SAML2_DUMP_USER_DETAILS=true to see whether your IDP sends attributes by their names or by UID. Example attribute configuration: ```bash # uid SAML2_EXTERNAL_ID_ATTRIBUTE="urn:oid:0.9.2342.19200300.100.1.1" # email SAML2_EMAIL_ATTRIBUTE="urn:oid:0.9.2342.19200300.100.1.3" # displayName SAML2_DISPLAY_NAME_ATTRIBUTES="urn:oid:2.16.840.1.113730.3.1.241" # member/memberOf SAML2_GROUP_ATTRIBUTE="urn:oid:1.3.6.1.4.1.5923.1.5.1.1" ``` I think it would be fantastic to mention it in the documentation, and maybe in .env.example Shibboleth IDP might refuse to log in BookStack. The reason is that BookStack metadata lacks encryption key, while Shibboleth is by default configured to encrypt assertions (auth responses). This encryption is meant to protect personal user data, but normally SSL already does this job. If assertions are encrypted, BookStack (onelogin toolkit) will decrypt them with the same key used for signing. The solution is to provide encryption public key to Shibboleth via metadata: - copy SP metadata from your BookStack instance (https://yoursite.example/saml2/metadata) - find the element <md:KeyDescriptor use="signing">...</md:KeyDescriptor> and duplicate it - in the duplicate, replace use="signing" with use="encryption" - feed this edited metadata to the Shibboleth IDP

OVERLORD closed this issue

2026-02-05 04:45:20 +03:00

OVERLORD commented

2026-02-05 04:45:22 +03:00

@ssddanbrown commented on GitHub (Feb 24, 2022):

My response for reference:

Thanks for the info.
To be honest, I generally avoid IDP specific instructions within our docs since these platform-specific details can be hard to maintain (as changes are made over time and understanding/handling different configurations) and it infers some level of official support, at least for the docs instructions themselves, which ends up putting the burden of correctness and maintenance of those details upon me.
Same reason I stopped adding additional social auth providers.

Again, if it was quite common we could add some hints, like we've done for active directory and LDAP, but don't think I've had Shibboleth pop up in any other suport request types to far.

Would it be okay if I copied your comments into a GitHub issue so I have this information for later reference, and to track occurrences of Shibboleth requests, and to provide searchability of others using Shibboleth?

@ssddanbrown commented on GitHub (Feb 24, 2022): > My response for reference: Thanks for the info. To be honest, I generally avoid IDP specific instructions within our docs since these platform-specific details can be hard to maintain (as changes are made over time and understanding/handling different configurations) and it infers some level of official support, at least for the docs instructions themselves, which ends up putting the burden of correctness and maintenance of those details upon me. Same reason I stopped adding additional social auth providers. Again, if it was quite common we could add some hints, like we've done for active directory and LDAP, but don't think I've had Shibboleth pop up in any other suport request types to far. Would it be okay if I copied your comments into a GitHub issue so I have this information for later reference, and to track occurrences of Shibboleth requests, and to provide searchability of others using Shibboleth?

Sign in to join this conversation.

Branches Tags

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: starred/BookStack#2669