Mod-login-saml should be tested with every flower release. The purpose of this page is to document the testing procedure to supplement the guide that already exists in the module's readme files here. Also see the usage section of the main readme.
Glossary
IDP (identity provider) - The 3rd party that is providing authentication for the user.
Binding - They type of binding that the IDP provides. FOLIO supports both REDIRECT bindings and POST bindings.
See the module's guide for more glossary items.
Step-by-step guide
Testing mod-login-saml consists of the following general steps.
- Configure a mock IDP (SSO Circle or samltest.id).
- Configure FOLIO to use the mock IDP through the FOLIO UI. Go to Settings->Tenant->SSO settings in the FOLIO UI and fill in the fields, following the instructions in the guide for the parameters for each.
- Log out.
- Test the login by clicking on the SSO login button in the FOLIO UI. This button appears after SAML has been configured in step 2.
See the testing section of the guide for detailed instructions for configuring both mock REDIRECT and POST IDPs.
In step 4 you will now see the following button. This is what you want to press.
Testing scenarios
The scope of testing has increased now that we are supporting refresh token rotation for SAML. This support was added in the Poppy release. Instead of testing only the two bindings (REDIRECT and POST) we need to test the two bindings for both RTR enabled mod-login-saml and non-RTR enabled mod-login-saml. Currently the default for mod-login-saml is for RTR support. In order to configure non-RTR support (also referred to as legacy token support) a configuration needs to be added to mod-login-saml for a given tenant via mod-login-saml's configuration endpoint as documented in the RAML here.
The four testing scenarios are documented in the following table.
Scenario | Stripes has RTR | Binding | Configuration Required | Configuration | Mock IDP | Notes |
1 | True | POST | No | No configuration for legacy needed | SSOCircle | No configuration on backend is required because this is the default for backend. Stripes requires configuration because its default is not to do RTR. |
2 | False | POST | Yes | Yes configuration is needed for legacy: SamlConfigRequest.callback = "callback" | SSOCircle | Configuration on backend is required because it is not the default. Stripes requires configuration. |
3 | True | REDIRECT | No | No configuration for legacy needed | samltest.id | No configuration on backend is required because this is the default for backend. Stripes requires configuration because its default is not to do RTR. |
4 | False | REDIRECT | Yes | Yes configuration is needed for legacy: SamlConfigRequest.callback = "callback" | samltest.id | Configuration is required on backend because it is not the default. Stripes requires configuration. |
A successful test for each scenario means that the user is able to login via the IDP via stripes without error and successfully make requests to the FOLIO back-end via stripes.
Configuration for legacy (non-RTR mode)
When testing legacy mode (meaning, when running without RTR enabled), the callback endpoint needs to be configured by providing a SamlConfigRequest via PUT to the saml/configuration endpoint of the module. See the callback property of the schema here. The callback has two forms: callback and callback-with-expiry . When the callback is configured as callback the user will be provided a legacy non-expiring token. When the callback is not configured, the callback will be callback-with-expiry and the user will be provided an expiring refresh token and access token pair as HttpOnly cookies.
Related articles
It may help to be familiar with the changes for refresh token rotation. Adding support for refresh token rotation has increased the scope of what needs to be tested.