LincDoc Support

• Home
• Submit a Request
• Check on a Request

• Knowledge Books
• Using LincDoc 3.0
• Using LincDoc 3.1+
• Client Onboarding
• Employee Onboarding
• Admit+

Home → Using LincDoc 3.1+ → Security → Example: Token-based Security Target

13.10. Example: Token-based Security Target

This example describes how to set up token-based security for generated documents via your SQL repository.

Important: This example scenario is not supported with Laserfiche or DocuWare repositories.

About the Example Scenario

In this scenario, you want to store generated documents (from an existing eForm or Document Package) inside your LincDoc SQL Repository. When the storage task is executed by LincDoc, you want to grant a manager full read/write access to all submitted documents. At the same time, you only want to grant the individuals (who submit the documents) read/write access to the documents that he/she submitted. The mechanism by which individuals can get back to their respective documents to make changes is in the form of an email sent to them. This email contains a custom link, which, when clicked, takes them directly to the eForm or Document Package, automatically populated with the data they previously submitted.

A folder contains documents for numerous individuals. You want to grant a manager access to all of the documents, but individuals should only have access to their specific file within the folder (the document he/she created). In addition, these individuals will be able to access the document easily, and securely, via a link in an email message.

Note: Throughout most of this example, the medical form (seen in other locations within the LincDoc help) is used as the example eForm. However, you can use any eForm or Document Package you like, if it suits your environment and the example scenario.

The overall process for configuring this scenario is as follows:

• Create a new folder in your repository that will hold all of the generated documents. 
• Set a security policy for the new folder.
• Verify that all generated documents for a particular eForm or Document Package will be saved in the new folder.
• Set token-based security through your repository.
• Define an email action to provide access to the documents generated by the selected eForm or Document Package.
• Execute and submit a sample document.
• View the generated document, both as an administrator (via the LincDoc Browse dialog box) and as the end user (via an automatically generated email).

Creating the Folder and Setting Folder-level Security

The first step is to create a new folder in your repository. This folder will store all of the generated documents in this scenario. Once created, the manager needs to have read and write access to this folder to allow full access to all of the generated documents.

1. Login to LincDoc as an administrator.
2. If necessary, select the appropriate eForm or Document Package from the Form Selection drop-down list.
   Tip: You can use any eForm of Document Package you like, as long as it has an email field to you can define prior to submitting it.
3. Click the browse button to access your repository's Browse dialog box.
4. On the Browse dialog box's toolbar, click the new folder button.
   
   The New folder name dialog box appears.
5. In the name text box, type secure.
6. Click OK.
   The new folder is created at the top level of your repository.
   
7. Right-click the secure folder, and select security from the menu that appears.
   
   The Security for dialog box appears. Notice that no policy is currently defined for the folder.
   
8. Click the create policy button.
   
   The lower portion of the dialog box becomes editable.
9. In the type list on the left side of the dialog box, click the everybody type.
10. In the Privileges for everybody list on the right side of the dialog box, verify that no privileges are selected (checked).
11. In the type list on the left side of the dialog box, click the owner type.
12. Select (check) the following privileges for the owner type in the Privileges for owner list:
• add_child
• read_data
• show_edit_ui
• write
13. Your dialog box should appear as shown below (you will need to scroll up to see the add_child privilege in the list).
14. 

15. These selections give the owner of a document (the user who fills out the eForm or Document Package and submits it) the ability to add the generated document to a folder (add_child), read the document's data (read_data), see the data in the Data Entry View (show_edit_ui), and edit the data (write).
    For more information on all available privileges, click here.

16. At the top of the Security for dialog box, click save.
17. Click OK to confirm the action.
18. Close the Security for dialog box.
    You are returned to the repository's Browse dialog box.

Defining the Token-based Name Setting

Now that you have created a folder for storing all of the documents, you need to configure your eForm or Document Package so that all generated documents are automatically placed within the correct folder and given a logical file name.

1. On the LincDoc toolbar, click the admin button.
2. Select edit from the menu that appears.
   The Admin dialog box appears.
3. On the eForm/Document Package tab, enter the following text directly in the Token-based name text box:
   secure/secure1-<<:doc-meta:created-date:hh-mm-ss>>
   Your tab should appear as shown below.
   
   This DRAT expression saves all generated documents to the new secure directory (via the secure/ entry), adds secure1- to the beginning of each document, and creates the rest of the file's name based on the creation date of the document (via the text enclosed by << >>).
   For more information on using DRAT, see Using Document Refinement Annotation Transformer (DRAT).
4. Save the eForm or Document Package.

Configuring Token Security Via the Repository

Now you will create a rule in your repository, which will define token-based security for all documents stored in the repository based on the current eForm/Document Package.

1. From the Admin dialog box, click the Repositories tab.
2. Click the edit (wrench) button for the repository you used earlier when creating the secure folder.
   
   The repository's Configure dialog box appears.
3. Click the Security tab.
   This tab can be used to create security rules for items stored in the repository. In this scenario, a rule will be created to configure token-based security.
4. Click the When saving a document, generate the security policy by evaluating the rules below option.
   Additional options appear, including a table that allows you to create rules for creating a security policy.
   
5. Verify that Start with an empty security policy is selected.
6. On the right side of the rules table, click the add button to create an empty rule.
   
   A blank rule appears in the table.
   
7. Configure the blank rule.
   1. Verify that the condition drop-down list is set to Always.
   2. Verify that the +/- drop-down list is set to add.
   3. Select token from the target drop-down list.
      Additional options appear.
      
   4. Type self-approval in the Token type text box.
      This entry represents the token name, and will appear in LincDoc when the token is used. This particular token represents one of two tokens created for document security, and it will control access to the document. The second token, which is created by LincDoc when a document is created, is the UUID that identifies the document itself.
   5. In the privileges column, select the last five privileges listed:
   • read
   • read_by_id
   • read_data
   • show_edit_ui
   • write

   Once complete, your rule should appear as shown below.
   

8. Click save to close the Configure dialog box.

Specify an Email Action to Provide Secure Document Access

In this section, you will create an email action that will provide document access to the user that submitted the form (based on that individual's email address, as specified in the form).

1. On Admin dialog box, click the Actions tab.
2. In the Buttons list, click the arrow button the corresponds to the Submit button.
   
   Additional options appear.
3. Hover over add, point to action, and click email.
   
   An email action is added below the Submit button.
4. Click the arrow button that corresponds to the new email action.
   
   Additional options appear.
5. Click edit.
   The email dialog box appears.
   
6. In the Reply To drop-down list, specify an email address that will appear as the "from" address when the email is received by an applicant.
7. Using the drop-down list adjacent to the TO drop-down list, select the field that represents the applicant's email address in the eForm or Document Package.
8. In the Subject text box, enter a meaningful subject for the email message.
9. Click the Send as HTML check box.
10. Enter the following text in the large, message body text box:
    Link: <<:doc-link:edit:Click here to edit:::html::self-approval>>
    This text uses DRAT syntax, and will provide a clickable link (the Click here to edit portion) in the email generated by this action. This link will allow a user to access a secure version of their document.
    In this example, the authentication token types DRAT parameter is being used with the doc-link DRAT type. Notice how the self-approval token, which was defined earlier, is part of this DRAT expression. For more information on using DRAT, see Using Document Refinement Annotation Transformer (DRAT).
    When completed, your email action should appear as shown below.
    
11. Click save to close the email dialog box.
12. From the Admin dialog box, save the eForm or Document Package.

Executing and Submitting the Form

Now that you have configured token-based security for this scenario, you need to execute the eForm/Document Package, fill in the necessary information, and submit it to see how the security functions.

1. (optional) Login as a sample non-admin user. You can also remain the administrator if you are just using this scenario to test and understand the process.
2. On the Admin dialog box, click Run.
   The Data Entry View of the eForm/Document Package appears.
3. Fill out the eForm/Document Package, as desired.

   Important: Be sure to specify an email address to which you have access, since it will be used to provide later access to the generated document.

4. Once the form is complete, click Submit.
   A document is generated and saved to your repository. In addition, an email is generated and sent to the email address you specified.

Examining the Generated Document (Admin)

Now that the document has been generated, you can examine it in the Browse dialog box and see how the token-base security was applied.

1. On the LincDoc toolbar, click the browse button to open the Browse dialog box.
2. Locate the newly generated document (in the secure folder you created earlier).
   
3. Click the check box adjacent to the file to select the file.
   Additional buttons appear in the Browse dialog box's toolbar.
4. In the toolbar, click the security button.
   The Security for dialog box appears.
   
5. In the type list on the left side of the dialog box, click the everybody and owner types. Notice that no privileges are selected for either entry (in the Privileges list of the right side of the dialog box).
6. In the type list, click the token type. Notice that the name you specified earlier (self-approval) appears in the type list, allowing you to easily identify the token.
   
7. In the Privileges for token self-approval list on the right side of the dialog box, verify that the last five privileges are selected (as defined earlier in your repository).
   
8. Close the Security for dialog box.

Viewing the Form Via the Email Message (Individual Applicant)

Based on how the email action was set up in the eForm/Document Package, the submitter (document creator) can now easily access the OpenForm version of the document. Once open, the user can both view the original information and make changes, if necessary.

1. Open the email generated by the eForm or Document Package.
   The body of the email will look similar to the example below.
   
2. Click the Click here to edit link.
   The OpenForm version of the document is opened in your default web browser. Notice that this view allows you to further edit the file and then resubmit (update) it.
3. Examine the URL in your web browser. An example URL is shown below (portions have been concealed for security purposes).
   

   Important: This URL grants full access to the specified document, including the ability to edit the document's contents, to anyone who possesses it. Therefore, it should be distributed with care.

   The following UUID strings are present in the URL:
• First UUID. Identifies the document itself within LincDoc.
  
• Second UUID (known as the access token). Controls login access to the document, allowing automatic (but secure) access after the URL is clicked in the email.
  

Knowledge Books