Saurabh RaiUnderstanding an Open Source Search Platform: Swirl
The team behind Swirl created a platform capable of connecting to multiple databases and searching through a single unified source.
That's Swirl Search for you.
This blog covers the second part of Swirl Security Overview (User Data, Metadata, and Credentials). This is a three-part series that guides you about Swirlโs security.
This blog is the second part of the Swirl Security overview. We have the first part, which discusses and explains Swirl in general. Read the first part here. ๐
Credential Storage
Swirl securely stores user credentials in its database to enhance the metasearch experience. This storage includes credentials for SearchProviders and OAUTH2 client details. Swirl also logs user activities in the same database and can save these logs to a file if configured.
Built on the Python/Django platform, Swirl ensures all portal URLs and APIs are accessed via HTTPS authentication.
To set up Swirl:
Begin by creating an administrator account. Instructions can be found in the Swirl Super User Creation Guide.
You can add and manage more users through the Django admin console. For a comprehensive guide, visit Django Admin Documentation.
Object Ownership
In Swirl, every object, such as SearchProviders, Search, and Results, is owned by a specific user. Typically, users, even those in the admin group, can only see their own Search and Result objects. However, thereโs an exception: if a SearchProvider object owned by an admin has its โsharedโ property set to โTrue,โ all users can view it. Rest assured, Swirl ensures any static credentials from such providers are automatically hidden.
If you want detailed insights on object ownership, visit the Swirl Admin Guide on Object Ownership.
Credential Sharing
Swirl supports the sharing of static credentials such as bearer tokens. These credentials can be shared by the admin user, as noted above. OAUTH2 credentials cannot be shared between users.
Securing the Swirl database so that the admin cannot access any data directly gives additional protection; please contact Swirl support for help.
Logging
In production mode, with logging level INFO, no search or result information is present in the logs. The output associated with a user running a search will be similar to:
2023-08-24 14:45:30,360 INFO admin search 545 FULL_RESULTS_READY 20 16.4
2023-08-24 14:45:30,366 INFO admin results 545 RelevancyMixer 20
Should an error occur, there will be diagnostic information; however, it may be limited unless Swirl is run in debug mode.
User Provisioning
For scenarios involving multiple users, Swirl offers the following provisions:
- User Permissions: Swirl equips users with the necessary permissions.
- Sharing SearchProviders: Users can access SearchProviders owned by the admin account.
- Access Methods: These tasks can be achieved either through the Django admin portal or the provided built-in APIs.
- Permission Requirement: To utilize Swirlโs features, users must possess the relevant permissions mentioned below.
- Support for OIDC: Swirl Metapipe and Swirl Enterprise support user provisioning via Open ID Connect (OIDC). This is facilitated through Microsoft SSO, leveraging the same APIs and processes.
User Permissions
The following Django permissions are required to use Swirl:
User Permissions Table
Swirl recommends granting these permissions to a group and then adding new users to that group. Additional permissions (like add and change querytransform and searchprovider) can be granted to a power user or developer group.
For more information on Swirl permissions, see Permissioning Normal Users.
Metasearch Authentication
SearchProviders
SearchProvider Configuration:
A SearchProvider is essentially a configuration of a Connector.
While administrators typically create and share these configurations with standard users, those with the right permissions can also create their own.
If you would like detailed insights, you can visit SearchProvider Object Reference.
Executing a Search:
Once logged in, users can initiate a search using one of the following methods:
- A GET request with either the ?q= or ?qs= parameter.
- A POST request with JSON data.
- The integrated Galaxy UI.
Initiating a search generates a โSearchโ object within the Swirl database. This object:
- Keeps track of the searchโs progress, including any status messages from the configured SearchProviders.
- Is owned by the user who initiated the search.
For a deeper dive, refer to:
Supported Authentication Schemes
When Swirl sends a query to a configured source, the following schemes are supported:
- Plain-text credentials, such as incorporating them in a URL
- HTTP Basic, Digest, and Proxy authentication
- Bearer tokens
- API tokens
- OAuth2
Where Swirl Stores Credentials
Swirl saves credentials, including plain text, API, and bearer tokens, within SearchProviders. These SearchProviders are specific records in the Swirl database. When non-admin users view shared SearchProviders owned by an administrator, the credential details are concealed for security.
For more details, please refer to Shared SearchProviders and Query Transformations.
Where Swirl Stores OAuth2 Data
In Swirl, when OAuth2 SearchProviders are set up:
- The userโs email address is saved in the Django User database.
- This email and a unique session key are used to obtain an OAuth2 token.
- This token is stored in the Swirl database if the โsubscribeโ feature is activated.
- If the โsubscribeโ feature isnโt needed, the token is temporarily kept in the session cache and isnโt saved elsewhere.
Search Expiration Service
For applications that handle sensitive data:
- The โRetentionโ property on Search objects can be adjusted to a value above 1.
- Setting this value ensures that the Search and its associated Result objects will be permanently removed after a specified duration, such as an hour, day, week, month, or even longer.
For detailed insights, visit The search Expiration Service Guide.
Dive Deeper into Swirlโs Security
If you havenโt already or need a refresher, read the previous blog in our series for a comprehensive understanding of Swirlโs security measures.
Support & Explore Swirl on GitHub: Visit Swirlโs GitHub page and consider giving us a ๐.
