If your configuration has a requirement for a container to handle authentication, but users/roles reside in an external database, Live Forms tenants using DB Container Security Manager can provide a database interface to fetch those user/roles. Some configuration is necessary and details may vary depending on the container you are using.
When using the Container Security Manager, anonymous access to public forms/flows, requires a public url.
On this Page:
- There must be a security database with available users and roles.
- There must be a frevvo.User role in the database.
- All the users in your DB-CSM tenant must have this role.
- The tenant admin must have the roles of frevvo.TenantAdmin, frevvo.Designer and frevvo.User.
Setting up the Security Database
- Modify your container configuration files to point to your security database. For example, setting up datasources are deployed in an xml file using the -ds.xml naming convention, such as jaas-ds.xml. In this example, the jaas-ds.xml. file for JBoss is modified to point to an Oracle security database so Live Forms can use it.
- Supply the SECURITY_DB_NAME and DB_PORT shown in the example for your database.
Configure the Container Security Queries
You will not be able to use the DB Container Security Manager,until you configure the required queries.These queries are global to the server installation and all tenants using the DB Container Security Manager will use the same queries. This limitation will be lifted in a future release.
The DB Container Security Manager should only query a JDBC security realm and never update it.
Container queries to your security database are used to extract users' metadata. The results from these queries are used by Live Forms to generate users list, user information, user roles etc. Note that, if this file is updated when the frevvo server is up, the server requires a restart to use the updated queries. If you are using a container other than tomcat, you may have created a frevvo-config.properties. Create this file if you do not already have one and add your queries to it. Of course, the queries must conform to the structure and syntax of your database. Here are some examples:
|Task||Description||Context Parameter||Available Parameters:||Resultset Columns:||Example query:|
|Find Subject Info||Returns a single row containing metadata about a given subject.||frevvo.security.container.findSubjectinfo|
SELECT user_name as firstName, user_name as lastName, user_email as email, null as maxAttachmentSize, null as taskNotification, null as reportsTo, null as signature, null as signatureType FROM users WHERE user_name = :userId
|Query All Roles||Returns all available roles in a tenant based on a given filter.||frevvo.security.container.queryAllroles|
SELECT role_name as role FROM roles WHERE UPPER(role_name) LIKE :filter ORDER BY role_name
|Query All User Ids||Returns all available user id's in a tenant based on a given filter.||frevvo.security.container.queryAllUserIds|
SELECT user_name as userId FROM users WHERE UPPER(user_name) LIKE :filter ORDER BY user_name
|Query All User Ids for a Role||Returns all available user id's in a tenant for a given role. This is used to retrieve all tenant administrators for a tenant.||frevvo.security.container.queryUserIdsForRole|
SELECT user_name as userId FROM user_roles WHERE role_name = :role and UPPER(user_name) LIKE :filter ORDER BY user_name
|Query All Roles for a user||Returns all roles for a given user.||frevvo.security.container.queryRolesForUser|
SELECT role_name as role FROM user_roles WHERE user_name = :userId ORDER BY role_name
|Query All Subject Info for a list of Roles||returns all SubjectInfo for a given list of roles and it is used to send notifications to flow participants.||frevvo.security.container.querySubjectInfoForRoles|
SELECT user_name as userId, user_name as firstName, user_name as lastName, user_email as email FROM users WHERE user_name IN (SELECT user_name FROM user_roles WHERE role_name IN (:roles))
Here's how the queries would look in the frevvo-config.properties file:
JAAS Authentication Configuration
The Java Authentication and Authorization Service must be configured when using DBCSM. Add the security configuration under the <security-domains> tag and modify the default-security-domain to point to this configuration. Here's an example of the entry in the standalone.xml file in a JBOSS configuration:
Modify the principalsQuery and rolesQuery
Here's an example of changes to the standalone.xml file.
Set up frevvo.war for JAAS Authentication
To identify any user with the role frevvo.User as a valid frevvo user, add this section to the web.xml file in the frevvo.war. The web.xml file is included in the <frevvo-home>\tomcat\webapps\frevvo.war. The frevvo.war must be unzipped/rezipped after modifications have been made as outlined in the steps below:
- Stop Live Forms if it is running.
- Unpack the frevvo.war file to a temporary location of your choice: e.g. c:\tmp\frevvo-war. Change the file extension from .war to .zip if necessary.
Edit c:\tmp\frevvo-war\WEB-INF\web.xml. Add the section:
- Save the changes to the web.xml file.
Rezip all the files in the c:\tmp\frevvo-war directory, even the ones you did not edit — if you change directories or zip them differently, Live Forms may not load correctly:
This is the correct structure for the frevvo.war zip-file.
Make sure you create the zip-file with the directory structure as shown in the image above. It is an easy mistake to include the containing directory in the zip-file.
Zip will often give your zip-file a .zip extension. Make sure you change this to a .war extension.
For Tomcat specific information, please see JDBC Realm. This Tomcat specific setup is being added here as an additional reference.
Add the JDBC Realm to Tomcat's server.xml
Add the Tomcat JDBC Realm Data Source
Add the following to the frevvo.xml (adjust user and password accordingly):
Create Tenant with DB Container Security
In order to successfully create a DB ContainerSecurityManager tenant, requires you must have an admin user that already exists and has the following roles: frevvo.TenantAdmin, frevvo.Designer.
- Restart Live Forms.
- Browse to the following url: http://<hostname>:<port>/frevvo/web/login
- Login into your Live Forms as the superuser:
- Username : admin@d
- Password : admin
- 5. Once you are logged in as administrator click on the “Manage Tenants” link.
icon to add a new Tenant .
- 7. Select “DB Container Security Manager” as the Security Manager Class.
8. Add a Tenant ID, Tenant Name and Tenant Description. Use the user ID from the Security DB that has the role “frevvo.TenantAdmin” as the Admin Id
- 9. Click Submit You should see a message “Tenant <TenantName> added successfully”
If the tenant admin user does not exist or it does not have the required roles, this error will display with the name of the tenant you are trying to add:
Managing DB Container Security Manager users & roles works the same as the existing LDAP Security Manager, You can see the list of the existing users, go to their corresponding home pages, but you will not be able to manage them.
Here is a screenshot of the expected functionality when managing users:
And here when managing roles:
Existing 5.0.x, 5.1.x, and 5.2.x installations using the old Container Security Manager (package com.frevvo.security) will still work as before when upgraded since the new DB Container Security Manager is a separate implementation. This method will be merged into the new in a future release.
Here is how you can create a new tenant using the old Container Security Manager:
Once your tenant is created, browse to this url to login as different users: http://<hostname>:<port>/frevvo/web/<tn>/<tenantname>/login.