mod-login-saml

Copyright (C) 2017-2025 The Open Library Foundation

This software is distributed under the terms of the Apache License, Version 2.0. See the file "LICENSE" for more information.

Introduction

This module provides SAML2 SSO functionality for FOLIO.

Usage

1. On Stripes UI find Settings->Tenant->SSO settings, paste the IdP metadata.xml URL.

• mod-login-saml stores this configuration in the database for each tenant.

2. Call GET /saml/regenerate to generate the keyfile with random passwords, which mod-login-saml stores for the tenant too.

• Don't forget to send X-Okapi-Tenant header
• UI button will replace this manual step
• Response is sp-metadata.xml that needs to be uploaded to IdP's configuration.

3. Make sure there is a user stored with externalSystemId matches UserID SAML attribute.

• These default properties can be overridden by user.property and saml.attribute configuration parameters.
• SAML binding type can be overridden by saml.binding configuration property, allowed values are POST and REDIRECT
• There will be UI for these too.

4. Go back to Stripes login page (log out obviously), 'SSO Login' button show up. Clicking on it will forward to IdP's login page.

Endpoints are documented in RAML file

Maximum authentication lifetime

The IdP's maximum authentication lifetime must be configured to be smaller or equal to mod-login-saml's maximum authentication lifetime. Otherwise the login attempt will fail with a "500 server error" if it falls into the gap between the two values, see MODLOGSAML-208.

The maximum authentication lifetime of mod-login-saml is

• 8 hours in mod-login-saml >= 2.10.1 and mod-login-saml >= 2.9.4,
• 5 hours in mod-login-saml 2.10.0 and mod-login-saml <= 2.9.3.

For mod-login-saml >= 2.10.3 the MAX_AUTH_LIFETIME environment variable can be used to overwrite this default.

Environment variables

DB_*: Configures the connections to the PostgreSQL database. For examples see the bottom of the module descriptor, for details see https://github.com/folio-org/raml-module-builder?tab=readme-ov-file#environment-variables .

TRUST_ALL_CERTIFICATES: if value is true then HTTPS certificates not checked. This is a security issue in production environment, use it for testing only! Default value is false.

LOGIN_COOKIE_SAMESITE: Configures the SameSite attribute of the login token cookies. Defaults to Lax if not set. If served from the same host name Lax allows deep links from other sites, for example from a wiki or webmail to an inventory instance record, whereas Strict doesn't allow them.

MAX_AUTH_LIFETIME: Configures the number of seconds for mod-login-saml's maximum authentication lifetime, see above.

Sample users for samltest.id

mod-users ships with three sample users that allow SSO login using https://samltest.id/ IdP, for configuration see Guide.

Usernames and passwords are

rick    psych
morty   panic
sheldon bazinga

Additional information

Other documentation

Refer to the user documentation Guide.

For upgrading see NEWS or Releases.

This module is based on the PAC4J library and supports SAML Single Sign On (SSO) including federations like eduGAIN.

More mechanisms supported by PAC4J can be added to this module if needed:

Authentication mechanisms: OAuth (Facebook, Twitter, Google...) - CAS - OpenID Connect (OIDC) (e.g. with Apple, Azure Ad v2, Google, Keycloak) - HTTP - Google App Engine - LDAP - SQL - JWT - MongoDB - CouchDB - IP address - Kerberos (SPNEGO) - REST API.

Authorization mechanisms: Roles/permissions.

Other modules are described, with further FOLIO Developer documentation at dev.folio.org

Issue tracker

See project MODLOGSAML at the FOLIO issue tracker.

Quick start

Compile with mvn clean install

Run the local stand-alone instance:

java -jar target/mod-login-saml-fat.jar -Dhttp.port=8081

ModuleDescriptor

See the ModuleDescriptor for the interfaces that this module requires and provides, the permissions, and the additional module metadata.

API documentation

This module's API documentation.

The local API docs are available, for example:

http://localhost:8081/apidocs/?raml=raml/saml-login.raml
http://localhost:8081/apidocs/?raml=raml/admin.raml
etc.

Code of Conduct

Refer to the Wiki FOLIO Code of Conduct.

Code analysis

SonarQube analysis.

Download and configuration

The built artifacts for this module are available. See configuration for repository access, and the Docker image.