On this page:

This exercise will show you how to configure Tachyon for use by different consumers. We will also go over the Tachyon Application Programming Interface (API) and the documentation of the API endpoints using Swagger. This will give you a visual representation of the APIs that you will need to use when creating your own consumer. These are the same API endpoints that are used by the Explorer application. If you can do something in Explorer you will be able to do it in any consumer. We will be using Postman as a consumer and writing our own consumer in later exercises. 

Tachyon License File for Consumers

1ETRNW102
  1. Log into 1ETRNW102 as 1ETRN\Tachyon_AdminPP and remain logged in.
  2. Right click on Start and choose Run. In the Run field type in \\1etrnap\c$ When the Authentication window opens use 1ETRN\Administrator
  3. Navigate to ProgramData\1E\Licensing and copy Tachyon.lic to c:\sources Open c:\sources\Tachyon.lic with Notepad to view the contents
  4. Search the file for Postman. This is the first consumer that we will be using. Notice that it is enabled.
  5. This licenses our consumers once we add them in Tachyon
  6. Search the file for QWidget - this is the powershell consumer we will be writing in later exercises
  7. Any consumers that you will write for your environment will need to be listed in your Tachyon license file

Consumer API Log

All Consumers interact with the Tachyon platform in the same way (including Explorer, Patch Success and Guaranteed State). We will look at the log to see the other Consumers as they work.

1ETRNAP
  1. Log into 1ETRNAP as 1ETRN\AppInstaller and remain logged in
  2. Navigate to c:\ProgramData\1E\Tachyon and open Tachyon.ConsumerAPI.log
  3. Browse through the log and notice the different API calls that are being made. You will see the API listed as well as the method (i.e. Get, POST, etc). You may have to scroll up to the top of the log.
  4. Leave the Log file open as we will look at it again in just a few minutes. You can scroll all the way down to the bottom now.

Adding Postman as a Consumer

We have our license file that allows us to use other consumers, but we also have to install the consumer in Tachyon. The consumers that ship with Tachyon (i.e. Explorer, Settings, etc) are already installed in Tachyon. If you remember from the Tachyon Install and Configure course we added Config Mgr as a Tachyon Consumer. Consumers are a piece of software - Principals in Tachyon are the users of that software. Tachyon checks each Consumer and also checks to see if the Principal has enough permissions to make that call. The Consumer is checked first - the Principal is only checked if the Consumer passes. We can register a new consumer either with the Settings application or with the consumer API (for example, during the installation of the consumer) since the API endpoints relating to Consumers do not check if the software calling them is a consumer.

1ETRNAP
  1. Still logged in as 1ETRN\AppInstaller
  2. Open Google Chrome and launch the Tachyon Portal using the bookmark in the Bookmarks bar (if it is not already open).
  3. Open the Settings Application and navigate to Configuration - Consumers
  4. Click the Add button in the far right
  5. In the Name field type in Postman
  6. In the Maximum simultaneous connections type in 5
  7. Check the two bottom boxes for Use Windows Authentication and Enabled
  8. Click the Add button

Adding the Principal

We are going to create a Role for Postman and add our Postman Service account to it.

1ETRNDC
  1. Open Active Directory Users and Computers
  2. Create a Service account called Postman. Set the password to Passw0rd
  3. Uncheck the box to force a password change at next login. Check the Password never expires box
1ETRNAP
  1. In the Settings Application navigate to Permissions - Roles add a new Role called Postman
  2. Open the Postman Role and add Read and Write permissions for the type Consumer
  3. Click Add again and select Instruction Set in the type field and in the Name field select All. Check the boxes for Actioner, Approver, Questioner, and Viewer. Click Add.
  4. Click Add again and select Instruction Set Management and check the Add, Delete and Read boxes. Click Add.
  5. Select the Management Groups tab and click Add and choose All Devices
  6. Add the Postman Service Account as a User in Tachyon and assign the Postman role to that user

Using Swagger

Before we actually start using external consumers we will look at the documentation for all the API endpoints. We can view this internal documentation using Swagger. This will give you the details for each of the endpoints to help you when you start making calls to them using your Consumer.

1ETRNW102
  1. Open Chrome from the Desktop shortcut and type in https://Tachyon.1etrn.local/Consumer/swagger/ui/index#
  2. Swagger is our documentation access to the Consumer API. The text shown in Swagger is spaced out for readability, in production they are compacted JSON on a single line with no white space between fields to minimize transmitted data.
  3. Scroll down to the Consumers category and notice Get/Consumers Click on Get
  4. Notice how the box will open to view the details on that API call
  5. Notice the Permissions required for this call - Read permission on 'Consumers' securable type. If you scroll farther down you will see the responses and an example for you to use. This is very good information that you will need when using the APIs for your own consumer.
  6. Navigate around Swagger noticing all the categories and the calls that can be made pertaining to those categories.  Open some other calls to see their options also.

Testing API Access

1ETRNW102
  1. Open Chrome (or another tab) and navigate to https://Tachyon.1etrn.local/Consumer/SystemInformation
  2. Notice our error message (in the <ErrorCode> section. Our request did not have the proper header

Your response should look like this

  1. In a new tab navigate to https://Tachyon.1ETRN.local/Consumer/Consumers
  2. Notice that we have a listing of all of the consumers that are currently available in our Platform.
    The Consumer type APIs are not covered by Role Based Access Control (RBAC). This allows for the registration of a consumer during the installation of that consumer.

Using the API from an External Source

The next steps will walk you through allowing HTTP calls within Tachyon. By default, Tachyon assumes that API callers will be authenticated using Windows authentication (i.e. NTLM challenge/response). However, a caller from outside the domain will have to provide credentials which correspond to a valid, authorized, domain account using an alternative protocol. The simplest mechanism for external source authentication is to use HTTP basic authentication over HTTPs. This is simple but reasonably secure.

1ETRNAP
  1. First we must add Basic authentication Role to the Tachyon server. Open Server Manager and Select Manage - Add Roles and Features. Click Next until you get to the Server Roles page
  2. Expand Web Server (IIS) - Web Server - Security and check Basic Authentication click Next until you are able to click install. Wait until it is finished and click Close
  3. It is critically important that HTTP calls be disabled if this option is pursued, since basic authentication passes credentials in plain text and is thus vulnerable to traffic interception. However, if HTTPS is used, the communications are fully encrypted. An attacker can only practically subvert this level of protection if they have sufficient access to one or both endpoints, so that they can alter the PKI chain of trust, managed through certificates in the endpoint certificate store(s).
  4. Now we will enable basic authentication for the Tachyon Consumer web service. Open IIS Manager and Navigate to the Tachyon site - Consumer node
  5. Double click Authentication and select Basic authentication and choose Enable
  6. Note the warning that SSL is not required. However, the warning applies to the site as a whole. The application endpoint associated with the Consumer API should already require SSL.

Double click SSL Settings for the Consumer website and you should see this. SSL is required for this application within the site. 

  1. Restart the Tachyon website
  2. Close IIS Manager and Server Manager

Lab Summary

In this lab you learned about configuring Tachyon for use by an external application and how to look at the internal Tachyon API documentation (Swagger).