Access Tokens

Creating Access Tokens

To create an access token, follow the steps below:

1. Click add_circle.
2. Select the Username. You must use a name that has been created in the Users page.
3. Enter the IP of the server address and netmask for computer(s) you want to allow to use this token to have access to this server; this defines the range of access. For example, if you only want a single user, or a set of users, to access the server using this token, limit that access by defining that IP and netmask. Leaving the field with its default of 0.0.0.0/32 will block all users of this token from accessing this server.  As a wild card, you can specify 0.0.0.0/0 and this would allow all IP addresses that use this token. Use a net mask when possible to limit access. See Net Mask below for more details.
4. Enter the APIs. This restricts which API endpoints the token can connect to. Using .* serves as a wild card and allows access to all APIs. If you'd like to limit APIs, regex must come be used: /(api/release/version|appliance/profile. In addition, when using health exchanges, you must append |extensions/healthexchange/.... This means the full API will look similar to this: /(api/release/version|appliance/profile|extensions/healthexchange). You can configure the API to allow access to any API that starts with /search. To do so, just enter /search on the line, no address is needed before it.
5. Select the Log Type. All API calls are logged, even feeding. They are then fed to SearchServer.
   • None: The token has no assigned log type, so all logged API requests are indexed in the audit log stores.
   • DoNotLog: The logs generated while bulk feeding data while using the access tokens with this log type are not sent or stored in searchserver's audit log stores and results in no logging of any API calls. This should be used only for ETL to prevent audit log bloating while feeding live data.
   • Custom: Its uses are in reports (you can filter by log type in queries) and also in Fluentd to tell it which log records do not need to be indexed to searchserver.
6.  Enter a Description. It should contain all information necessary to identify why the token is being created and how it is being used.
7. Click Create.

You will get a message with a long string of numbers and letters that is your actual token. You will immediately need to copy that token and paste it where you need it because once you close the box that contains the key, you will not be able to see it again. 

Net Mask

Net masking is a security feature that requires matching different sections of an IP address. Enter multiples of eight up to 32, with the higher number being more restrictive. Use /32 for the most secure; using /0 leaves it open. Each multiple of 8 adds one more portion of the IP address that much be matched. For example, if the IP address were 10.11.12.13, a net mask /8 would only require the 10 to match; whereas, entering /24 would require a match of 10.11.12, leaving the last portion of the IP address open.

Editing Access Tokens

If you find you need to make a change to an Access Token, rather than creating a new token  some fields are available for editing. Click edit next to the field you would like to change. See the Creating Access Tokens section above for more information on each of these fields.

Fields that can be edited:

• Description
• IPs
• APIs
• Log Type

The information may be changed for existing tokens. Note, though, that you will note see the actual token that was provided upon initial creation.

Using Access Tokens

After creating the access token, it displays on the screen as a long string of letters and numbers. If you need a copy of the token to paste it to another location, select Copy Token. Clicking OK creates the token but does not save the token to the clipboard. You will not be able to view the key again once you click OK.

Below are some examples of ways to use an access token.

This first example sends an authenticated request to the /api/account/whoami endpoint then logs out its response:

const HOST = '<your hostname>';
const TOKEN_OWNER = '<your username>@default';
const TOKEN = '<your token>';

const response = await fetch(`https://${HOST}/api/account/whoami`, {
  headers: {
    'X-PS-Auth-User': TOKEN_OWNER,
    'X-PS-Auth-Token': TOKEN
  }
});

console.log('status code:', response.status);
console.log('response body:', await response.json());

Here we are using the token as a health exchange endpoint. 

The following two examples below are options for using access tokens. The key with both examples is to use both AUTHTOKEN and AUTHUSER. Make sure with either option you replace 9.10.11.12 with the customer IP address, henryviii@default with the actual username, and mpid55 with the MPID you need.

The first is a curl example:

curl -kv -m 5000 --connect-timeout 5000 -H "AUTHUSER: henryviii@default" -H "AUTHTOKEN: M7GMSQTXXX" -X GET "https://9.10.11.12/extensions/healthexchange/patients/mpid55?PurposeOfUse=SYSADMIN"

The second is Python and has the same results:

url = "https://9.10.11.12/extensions/healthexchange/patients/mpid55?PurposeOfUse=SYSADMIN"
headers = {"AUTHUSER": "henryviii@default", "AUTHTOKEN": "M7GMSQTXXX"}
data = {}
r = requests.get(url, headers=headers, params=params, verify=False)
print(json.loads(r.content.decode()))

And then follow it up with this Python code. Make sure you use the same AUTHTOKEN and AUTHUSER values you used before.

#!/usr/bin/python
import requests
import json
url = "https://9.10.11.12/extensions/healthexchange/patients/mpid55"
params = {"PurposeOfUse":"SYSADMIN","imatTransactionId":"-293348119","targetoid":"2.16.840.1.113883.3.8073"}
headers = {"AUTHUSER": "henryviii@default", "AUTHTOKEN": "M7GMSQTXXX"}
data = {}
r = requests.get(url, headers=headers, params=params, verify=False)
print(json.loads(r.content.decode()))

Deleting Access Tokens

Deleting access tokens revokes access to any APIs, NiFi, or anything else that the token was allowing access to.

1. Locate and click on the token to be deleted.
2. Click Delete found in the right pane.
3. Confirm you'd like to delete the access token.