This page is aimed to consolidate and document all known requirements (both functional and non-functional) applicable to FOLIO secrets management.
A user (administrator) wants to create/manage secrets through the secret storage directly and allow FOLIO modules to access those secrets (read-only access)
- No specific Jira examples though as per my understanding all those secrets being specified in modules' ModuleDescriptor-template.json files (in launchDescriptor.env section, e.g. DB_USERNAME, DB_PASSWORD etc.) fit this category
- A user (administrator) wants to create/manage secrets through FOLIO. E.g., a module might need to store credentials to some external system (like FTP or SMTP server credentials, API keys etc.) UI forms are involved as well for interaction with a user
- Example: INN Reach Central Server Configuration keeps API keys (key and secret) for Central and Local servers. As per requested behavior, UI Screen contains fields for setting / displaying API keys, and a user (administrator) uses them to save, view or update keys. One can use - UIINREACH-12Getting issue details... STATUS for reference and find mock ups there. Currently, backend module storage is used to store such keys
- A module wants to create/manage secrets so that a user is not even in the loop here, and the interaction is only between the module and secret storage.
Secrets access type
Is read-only access enough to cover use case #1 from above, or full access with CRUD support to cover use cases #2 and #3 is mandatory?
The following secret types are to be supported:
|Secret type||Format||Who creates?||Who accesses?||How does it work now?||Additional comments|
|login & password||String||different modules use their own storages for that|
|API key||String||different modules use their own storages for that|
Cannot be stored in SSM, Vault etc.
The following secret stores are to be supported:
|Secret store mechanism||Links||Environment & Comments|
|HarshiCorp Vault||https://www.vaultproject.io/||On-premises installations|
|AWS Systems Manager Parameter Store ( or just AWS SSM)||https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html||As an option for AWS cloud hosting|
|AWS Secrets Manager||https://aws.amazon.com/secrets-manager/||As an option for AWS cloud hosting|
|properties-file||For dev / test needs|
|environment variables||Standard EC2 machine with all dockers on it (native docker, so Env Var are only available) - IndexData (snapshots, testing)|
User interface for Secrets management
Home-grown unified web UI vs. store-specific UIs
Both AWS SSM and Vault have their own management user interfaces, Rancher provides an option to manage secrets in form of environment variables in UI forms.
Tech stack support
The following programming languages used on Folio platform are to be supported:
- Java Spring way
- Java Vert.x
- Node.js (RA: I haven't met such modules/components by my own but have heard they exist - should they be considered?)
- are there any other languages used?
Access to secrets must be logged for further audit
- Option 1 - Use secret stores native audit capabilities
- No development, just devops/hosting
- Access to properties files or System Environments won't be have such native audit capabilities
- Option 2 - FOLIO dedicated log storage
- e.g., based on mod-audit or a new one - just a unified way regardless of hosting details
- Development is required
Proposal - start now with option 1, may consider option 2 later if option 1 won't be enough.
Secret store access
Any particular FOLIO module should only access its own secrets
- check AWS ssm:GetParameters permission - it is the policy used to enforce access control and protect one service’s secrets from another (here https://aws.amazon.com/blogs/mt/the-right-way-to-store-secrets-using-parameter-store/ there is a pretty good overview of this process)
- in Vault an access can be managed via roles, tokens etc. (https://www.vaultproject.io/docs/auth)
A tenant should only access its own secrets
- tenant are FOLIO internal term, so that it seems now that access verification on tenant level cannot be supported on Secret store level
- tenant ID can be used as a part of secret name
Secrets update in runtime
Adding / updating tenant's secrets in a multi-tenant environment shouldn't result in downtime for other tenants, if possible.
Secrets updates can be challenging because of more complex mechanism of change notification, e.g. in case of password change or rotation - how to ensure that all instances are notified and use the recent value?
Can / should secrets be cached in apps?
- Concern is about storing secrets in memory - there's potential risk of data extracting from RAM, though this can be considered as a low risk / low impact
- Caching reduces load on Secret Store, and improves performance & availability
https://github.com/aws/aws-secretsmanager-caching-java - Java implementation of SSM caching client
"To use your secrets most efficiently, you should not simply retrieve the secret value from Secrets Manager every time you need to use the credentials. Instead, use a supported Secrets Manager client component to cache your secrets and update them only when required because of rotation. AWS has created such client components for you and made them available as open-source.
- Note that caching introduce some challenges, e.g. time-to-live and notification about changes