Discuss.FOLIO.org is no longer used. This is a static snapshot of the website as of February 14, 2023.

SAML SSO features and strategy

30 Jun '20

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.

3 Jul '20
  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.
6 Jul '20

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.

25 Aug '20

I would advocate that we use an external module for all login activity. There are plenty of projects that have figured this problem out robustly, and can integrate with other existing sources of truth if one needs to compose multiple SPs together or use different protocols. If we pick a particular project to integrate with, say Keycloak, then we could make mod-login-keycloak as the necessary adapter to connect to FOLIO, and only have to maintain one module rather than multiple.

I think this would also be an opportunity to decouple Users and Logins. It should be possible to have:

  1. A User with a Login (staff or student workers)
  2. A User without a Login (patrons who don’t work with FOLIO directly)
  3. A Login without a User (system logins)
26 Aug '20

First, I would like us to come to some explicit agreement within community about the SAML SSO features and use cases that the project will support. Currently, I see:

Use Cases/Features

  1. Authentication against the campus IdM infrastructure; that is, using IdM to confirm identity; this is exactly what we support now.

  2. Makes SAML SP metadata available through public API for easier IdP config. Does this have general support, and at what priority? See tickets linked above.

  3. Federation support, so our FOLIO instances can be more easily connected to the campus IdM infrastructure. Federations are common for institutions using SAML, this seems non-controversial. Agreed?

  4. Login Authorization, the ability to test in some configurable way for a SAML attribute that explicitly states the user is allowed login access to FOLIO. Is this desired, non-controversial, or is it not needed?

From the above write up, these seem like the most likely use cases/features. Are these the right features?

And what about Consortia? Are there any additional needs for consortia?

28 Aug '20

What use cases do have in mind here? I only can imagine a user who want to research in the OPAC but for that I’d assume there is an extra discovery service

28 Aug '20

I’ve one general question, is this discussion only scoped on SSO via SAML or should there also be a consideration to support other authentication flows?
In the first case we have to keep in mind that if the institutions IdM lives or should live outside of FOLIO there will be only SAML left to connect them.

Beside that and only on the scope of SAML I’d agree that these are the most likley use cases.

On No4 I’d like to strongly vote for an authorization by attribute feature. First use case that came in mind are different circulation rules that were mostly tied to the affiliation attribute.

For consortias I think we only need to have the possibility to open a FOLIO instance for more than one IdP. Since a consortia should be the sum of all participating institutions which all ideally should have their own IdM/SAML infrastructures. At this point I’d assume a permission management based on submitted attributes (Login Authorization) is absolutly necessary.

28 Aug '20

I’m envisioning that most Users would not have a Login. They’d likely still be able to log into the Discovery Layer, but that’s separate, a connection between the Discovery Layer and whatever authentication system. They’d just need their externalSystemId populated in FOLIO so that the Discovery Layer could pull up their User record details like current loans, requests and fines.

I think that only people who would be working in FOLIO should have a Login to the system.

29 Aug '20

Oh ok, now I see your point.
That means for the usual library user FOLIO is just a backend system and the whole interaction with it will be only via frontend applications like eg. discovery services. In that case you are right. I’d assume that this can be realized by a system login but also with a silent SAML or OAuth login.

I’ve to appologize I was socialized with LSPs that always also act as an OPAC. :wink:

3 Sep '20

I had intended for this discussion to focus on SAML SSO, partly because there are possibilities such as federation support that are unique to it. It may be that some of the SAML SSO needs also illustrate needs of other AuthN/AuthZ systems.

That said, it is probably time for another survey of implementing institutions to see who needs to integrate with other AuthN systems.

3 Sep '20

Another use case:

Use Cases/Features (cont’d)

  1. Ability to configure (a) maximum session duration and (b) session timeout after inactivity.
  2. Ability to configure system to send forceAuthn flag with every SAML AuthnRequest.
17 Sep '20

Here are the other tickets in the user management SIG that have to do with logging on:

Do you think any of these could fall into your purview?

18 Sep '20

These two certainly could fall under my purview:

Full disclosure: Though I may have thought differently in the past, I’m currently of the opinion that UXPROD-554, while theoretically interesting, should be closed. It would split the management of internal application permissions between the central IdM and the application itself, which I think would be too unwieldily in operation and unlikely to actually be used by any implementing library.

21 Sep '20

I want to push back on closing UXPROD-554 (the Grouper auth) - there are Grouper features that are really desirable, namely

  • the ability to expire a person’s permissions - e.g., if I set an expiration date on the Grouper membership and don’t renew it, their permissions would be automatically removed.
  • the ability to automatically script permissions being added - e.g., if a person is hired into a particular job family, they could be scripted to be automatically added into a grouper group, and get an automatic set of permissions (perhaps a base set for training, or some other set appropriate to the institution’s needs.)
  • audit trail - grouper makes it very clear who adds/drops people to permission groups. FOLIO doesn’t get close to that. If I’m at an institution that needs to know who did what in terms of permissions, and I want to go within the next year, an external tool like Grouper is the only way that that could happen.

I’m not under any illusion that the feature is going to be built any time soon - and it looks like Duke’s ranking disappeared, which is disturbing, so I’ll ask @karen_Newbery to re-rank it - but there are definitely needs here that are not accounted for in other features. In my opinion, it should not be closed.