Skip FOLIO Project Navigation

SAML SSO features and strategy

The purpose of this post is to prompt a discussion of the features needed and strategy for FOLIO support of single sign-on (SSO) based on the Security Assertion Markup Language (SAML). This is intended to focus on real-world, practical needs and step away from cases that are perhaps theoretically interesting but unlikely in practice.

A secondary purpose is to discuss SAML needs in the context of other FOLIO work on authentication (AuthN) and authorization (AuthZ).



It appears that all implementing libraries that rely on SAML-based SSO (e.g. Shibboleth) are members of federations such as InCommon and/or OpenAthens. Federations help automate establishing and maintaining the trust relationship between a FOLIO instance (Service Provider) and the library’s campus Identity Provider. This reduces the set up and maintenance burden on both the FOLIO operations staff and the campus identity management team.

This is highly desirable, the lack of Federation support for SAML-based SSO would be an anti-selling point.

Make SAML Metadata available through public API for easier IdP config

The ticket is about publishing SAML Service Provider (SP) metadata for a tenant through a public API. It is unclear whether this is still an active concern, or whether Federation-awareness would meet the underlying configuration need. There are two blocked tickets for this:

Login Authorization

Currently, in mod-login-saml, authentication to the IdP automatically grants authorization to log in to FOLIO. In practice, this means anyone with valid campus credentials can log in. FOLIO relies on its internal permission system to prevent people from seeing or doing things they ought not.

When using SAML for authentication, we should allow sites to also test for explicit authorization before allowing someone access to the system at all.

Linking SAML attributes to FOLIO permissions

There was some minor discussion of linking SAML attributes, like group membership, to assigning FOLIO permissions or to roles. In the abstract this seems like an interesting way to manage permission: a person could have some roles managed in the campus identity management infrastructure and FOLIO could be configured to assign appropriate permission sets. But is this realistic? Managing more granular, application-specific information may not be a good match at the campus level.

Question: what use cases to support?

At this writing, it seems like the use cases around Federation support and explicit login authentication have real, near-term practical value to sites. The other two cases are less clear.

Are there other real-world use cases, other SAML needs that are known today?

And which uses of SAML do we commit resources to supporting?

Security Audit Concerns

These two tickets address concerns raised by the security audit in Winter 2020:

Related Work in FOLIO

There was a recent spike to investigate expiring/refreshing access tokens:

Following this there was a suggestion to look closer at existing standards before rolling out our own AuthN|Z, particularly OAuth. An investigation was initiated but stalled by release prep:


The second question is one of strategy. Currently FOLIO maintains its own SAML Service Provider (SP) in the form of mod-login-saml. We could continue to enhance and maintain this. There are also modules for Apache and NGINX to, when acting as a reverse proxy, provide the SP functionality and release SAML attributes in a configurable way to the protected application.

While the information for this post was being assembled, the security team also began to consider this same matter of how best to support SAML SSO in FOLIO:

In any case, it is a good time to consider how FOLIO plans to consume and SAML attributes, which module(s) is responsible, how that information is propagated or reflected through FOLIO. (I.e., do SAML attributes just map directly to user permissions and possibly user attributes? Or do they need to be directly available to modules?)

These are not mutually exclusive, both options could be pursued. Any option we choose to support will require resources and longer-term effects. And a project we want to be intentional about this.

There are certainly more pros and cons than outlined below. I’m happy to add to this article based on the discussion.

FOLIO-supported SP (e.g. mod-login-saml)

This option would be to continue as we have been. The original authors of mod-login-saml (and of mod-login) have left the project. As authentication and authorization are being re-examined, this would be a good time to reconsider the whole


  • FOLIO has its own SP, baked into the product, reduces external dependencies.
  • Authentication and authorization with SAML could be considered in a wholistic context.


  • The project must maintain or have access to specific understanding of SAML and the expected behaviors of the SP. The security tickets above suggest some of the knowledge that must be maintained or accessible.

External SP in deployment environment

NGINX, Apache HTTPD and even IIS offer add-on modules for SAML and/or Shibboleth authentication. NGINX seems to be nearly universal in FOLIO deployments. Would we benefit from outsourcing SAML integration to external software?


  • The SP software is deployed in production much more broadly than a FOLIO SP would be, and is maintained by an active community with specialized knowledge.
  • Mechanisms to expose and access attributes are already defined


  • Project must be deliberate in planning to support the integration.
  • Places a demand on the deployment environment in order to meet a functional need.
  • FOLIO must support the provided mechanisms to access attributes.
  • External SPs may not be equivalent, nor equally robust


David Langenberg, Asst. Dir. for IdM at UChicago suggests not using FastGCI and Shib with NGINX. That integration has a reputation for being fragile. If NGINX is preferred he recommends staying with a baked-in SAML implementation. (Our campus prefers Apache, and the Apache/SAML integration has been robust.)

David Langenberg also suggests that we look at pac4j: security for Java. From reviewing the project site, pac4j bills itself as a security engine for Java, offers implementations for many frameworks, including Vert.x and Spring, supports a variety of authentication mechanisms, including OAuth and SAML, and is available under the Apache 2 license.

(mod-login-saml already uses pac4j. This might be an opportunity to re-consider the login architecture in general,.)


The main decisions I see are:

  1. What SAML SSO features and use cases does the FOLIO project agree to support?
  2. What is our strategy to integrate with SAML SSO, maintain a FOLIO module or relying on external software?
  3. How does FOLIO translate SAML attributes into actionable information at the module level?

These decisions affect development resources, deployment practices, and possibly architectural considerations. This is a good time to think about the options and to proceed deliberately.

  1. If we don’t know how SAML SSO actually works, it is not feasible to maintain our own module.
  2. Can we map attributes to Folio roles or permission sets ? Probably yes. Right now Folio doesn’t allow for this type of architecture. Right now, every user account in Folio is a patron.

Thank you Tod, for bringing this all together!

to 1. It should be also considered if there are current use cases that are in need of using SSO authentication flows besides SAML. If so, a closer look on the already mentioned pac4j might be good. So pac4j don’t just can serve SAML it serves every popular SSO auth flows from OAuth over OpenID to CAS. So sticking to pac4j which is used in mod_login_saml could open FOLIO to a lot more possible auth mechanisms which would give institutions more flexibility on choosing their auth method.

to 2. If SAML is considerd as the only auth mechnism I’ll tend to use the native service provider within an Apache setup. As this was the perfered SAML implementation at UFrankfurt I also can confirm its robustness.

to 3. In my opinion there should be flexible possiblities to map SAML attributes to permissions and/or roles in FOLIO since any underlying IdM of a Identity Provder might be sightly different from institution to institution. Never the less a good starting point might be the attribute affiliation for roles and if special permissions are needed they could implemented in the entitlement attributes.