https://github.com/folio-org/mod-login-saml
FOLIO SAML login module
https://github.com/folio-org/mod-login-saml
Last synced: 10 months ago
JSON representation
FOLIO SAML login module
- Host: GitHub
- URL: https://github.com/folio-org/mod-login-saml
- Owner: folio-org
- License: apache-2.0
- Created: 2017-07-03T13:12:27.000Z (almost 9 years ago)
- Default Branch: master
- Last Pushed: 2025-07-31T16:36:44.000Z (11 months ago)
- Last Synced: 2025-07-31T19:52:53.816Z (11 months ago)
- Language: Java
- Size: 958 KB
- Stars: 2
- Watchers: 15
- Forks: 10
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: NEWS.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# 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](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](ramls/saml-login.raml)
### 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](https://folio-org.atlassian.net/browse/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.
### Environment variables
`DB_*`: Configures the connections to the PostgreSQL database. For examples see the bottom of the [module descriptor](descriptors/ModuleDescriptor-template.json), 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.
### 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](GUIDE.md).
Usernames and passwords are
```
rick psych
morty panic
sheldon bazinga
```
## Additional information
### Other documentation
Refer to the user documentation [Guide](GUIDE.md).
For upgrading see [NEWS](NEWS.md) or
[Releases](https://github.com/folio-org/mod-login-saml/releases).
This module is based on the [PAC4J](https://www.pac4j.org/) library
and supports SAML Single Sign On (SSO) including federations like
[eduGAIN](https://edugain.org/).
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](https://dev.folio.org/source-code/#server-side) are described,
with further FOLIO Developer documentation at
[dev.folio.org](https://dev.folio.org/)
### Issue tracker
See project [MODLOGSAML](https://issues.folio.org/browse/MODLOGSAML)
at the [FOLIO issue tracker](https://dev.folio.org/guidelines/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](descriptors/ModuleDescriptor-template.json)
for the interfaces that this module requires and provides, the permissions,
and the additional module metadata.
### API documentation
This module's
[API documentation](https://dev.folio.org/reference/api/#mod-login-saml).
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](https://wiki.folio.org/display/COMMUNITY/FOLIO+Code+of+Conduct).
### Code analysis
[SonarQube analysis](https://sonarcloud.io/dashboard?id=org.folio%3Amod-login-saml).
### Download and configuration
The built artifacts for this module are available.
See [configuration](https://dev.folio.org/download/artifacts)
for repository access,
and the [Docker image](https://hub.docker.com/r/folioorg/mod-login-saml/).