Token Authentication for External Applications	Top

Introduction	Top

Token authentication for external applications is a set of features designed to permit the integration of various software solutions with LabVantage. Two example use cases are the Scientific Data Management (SDMS) and Configuration Management Tool (CMT). Features available within these modules include the option to use external collectors and to set up a remote checkout. These applications will require a connection to the LabVantage application for the purpose of both retrieving data from and providing data to LIMS. The overall process for this includes:

1. Registration of the external application
2. Creation of a user account dedicated to this application
3. Generation of an authentication token

The advantages of using token authentication include:

• Unlike connection IDs, sessions using tokens do not time out at the same frequency of a normal LabVantage user. A token can be set to expire on a given date.
• Tokens secure the application by allowing connections through the LabVantage API only. Usage of this account to access the LabVantage web application is blocked.
• The token can restrict an external application to being able to use only SOAP, REST or a Sapphire Controller.
• The token can further restrict an application to being able to leverage a limited number of LabVantage actions specific to that token.
• These types of connections do not occupy a named user or a concurrent user license.
• Usernames and passwords will not be stored within an external application.

Registering an External Application	Top

Some external applications will be created for you when LabVantage is installed. No registration is necessary in order to configure these applications. If SDMS or CMT is your external application, you can move directly to the creation of a user account. External apps can be viewed and managed through the list page. Core applications are view only.

System Admin > Security > External Apps

The CMT Remote Handler allows slave/remote systems to communicate with this master system. The SDMS Collector is intended for use with external collectors. TalendDeveloper is intended for use when you are building Jobs and want to test them prior to loading them into LabVantage.

When you click the Add button from the list page, LabVantage will check the number of External Applications you are allowed to create according to your licensed amount.

1. Provide a unique identifier for your application.
2. Optionally provide a description for your documentation purposes.
3. Status can be Active or Disabled. Disable an application to block the flow of data.
4. Requires REST WebServices: Representational State Transfer technology is preferred by many over SOAP. It is not normal to enable both this, a Servlet, and SOAP for one application. If enabled, choose a REST Policy Node. If no node is chosen, the default is Sapphire Custom. Creating and referencing other nodes gives you more security over your data traffic. Leave empty (unticked/No) to block the use of REST for this application.
5. REST Policy Node: A token can be provided in one of three ways (as can a connectionid):
1. Via a Request parameter (token=xxx) - subject to the same restriction that connectionids have in the security policy property "Allow ConnectionId In Request"
2. Via a cookie ( token=xxx)
3. Via the HTTP header value: Authorization="Token xxxx"
   
   If a token is used for authentication (or if a connectionid is used that is derived for an External App user) then the External Application SDI for that token / user is consulted to see if REST commands are permitted for that application, and if they are, which RESTful policy node determines the REST resources available. Prior to 8.5, it was the Security Policy that was consulted to determine if Action processing was permitted, and if so, which actions could be executed. This list of actions has now been moved to the REST Policy, and the property in the Security Policy has been deprecated.
6. Requires Servlet: A “Sapphire Controller” entry point can be used (sc). This servlet-based entry point may host a custom handler class for specialized function. The public API includes two new Java classes: sapphire.servlet.BaseExternalApp and sapphire.servlet.BaseExternalHandler. Used in conjunction, these classes allow an external Java application to communicate with the LIMS over HTTP and execute commands within the LIMS application.
7. Servlet Handler Class: A Sapphire Controller entry point is available. This servlet-based entry point will host a custom handler class for specialized functions. The class defined here should inherit from the sapphire.servlet.BaseExternalHander. See the javadoc for these classes and more detailed information.
8. Requires SOAP WebServices: Some external applications will use SOAP. Enable this if you will permit your application to communicate with LIMS over SOAP. You may also need to adjust your Security Policy for this.
9. Default Token Expiry Days: Tokens can be given an expiration date. LabVantage can calculate an expiration date based on the creation date plus the number of days you enter here.

Creation of an Account	Top

This section focuses on just the steps necessary for an external application to leverage the LabVantage APIs. Additional information about user security can be found here. A User Type called "External App User" is available when adding an account to the system. When creating a user of this type, is it mandatory to define a corresponding External App. These connections do not consume a concurrent license. External operations authenticated with a Token will be executed on behalf of the user defined here. These users will create “internal” connection identifiers and operations will adopt their departments, roles and other security features of LabVantage. In the final step of this three-step process, you will create a token. The token will be for a specific user, an external app, and the allowed set of entry points for that application. External App users cannot login via the browser and must be associated with an external app which grants them access to the actions permitted in your policy.

System Admin > Security >Users... Add

1. Provide a unique identifier for the account. This example demonstrates the use of CMT.
2. Choose the User Type of "External App User".
3. Enter a Full Name.
4. Enter and confirm a Password.
5. Continue configuring your security options as needed.
6. Choose your external application form the External App lookup.
   
   
   
7. Save. Complete any other details as necessary for this account to access departmental records or perform role-based activities.

Generate an Authentication Token	Top

If a token is used for authentication, or if a connectionid is used that is derived for an External App user, then the External Application SDI for that token / user is consulted to see what commands are permitted for that application. If REST is allowed, The RESTPolicy node determines the REST resources available. The Permitted Actions property allows Full, Restricted (by a list), or Defined by Roles. Navigate to:

System Admin > Security > Auth Tokens

Click Add to open the Add Token page.

1. Auth Token identifiers will auto-generate upon save.
2. Description is optional. Use it for your documentation purposes.
3. Request Reason is optional. Use it for your documentation purposes.
4. External App allows you to choose from a list of applications you have registered.
5. External User will filter to show only those users designated for this external application
6. Token Status:
1. Pending Approval - The token cannot yet be used but is waiting for someone to approve it. This mode is used when the "Request Token" API is used
2. Disabled - The token cannot be used
3. Active - The token can be used
4. Expired - The token has previously expired and cannot be used unless the expiry date is changed and the status changed to Active
7. Token Value will auto-generate upon save. Copy from here to use this value when establishing connections. This value is read-only.
8. Allow to process as
1. Never – Process all actions as the user specified in the "External User".
2. Any User – Allows the external application to pass through any LabVantage user account for a connection and perform all actions as that user. This is generally not recommended for production systems.
3. Specific User – Use of this token will always process actions as the chosen User.
4. User in Department / User with Role – narrow down the list of allowable users
9. Process As: Depending on the value you chose for "Allow Process As", different options are shown. The connectionid (and hence security settings) will reflect the LIMS user instead of the external user.