Security Configuration & Troubleshooting

PRIS can be configured to use:

  1. One of the built in Windows security mechanisms e.g. Windows Integrated Authentication (very restricted and only good for Windows programs running on the same domain, but if this is all that is needed, simple to setup).
  2. No security (may be ok if you are not worried about security within a firewall).
  3. Token based security (the most flexible option, as it has an authorisation scheme, can be used by anything, and can be used outside of a network domain, including externally, outside of a firewall)

Windows Integrated Security

  1. Make sure the following is uncommented in the PRIS web.config:

    2. <security>  
      <authentication>
       <windowsAuthentication enabled="true"/>
     </authentication>
 </security>

  1. In config/appSettings.config, set the following to windows:

    2. <add key="SecurityType" value="windows"

You will need to ensure that the consuming application is also set to use Integrated authentication.

Other than this one special case (i.e. a Windows program running on the same domain), this mode of authentication is very restricted, and has no authorisation scheme.

Token configuration

This is by far the most versatile security option, and includes authorisation via Dome Users/Roles. However, there is a small amount of setup, as shown below.

To enable token configuration:

  1. Make sure the Windows authentication block is either removed, or commented out:

    2. <!--<security>  
       <authentication>
        <windowsAuthentication enabled="true"/>
      </authentication>
  </security>-->

  2. Set the following in <pris install dir>/config/appSettings.config:

For the audience secret this MUST be unique for each installation of PRIS at each site.

A secret string of length 32 and converted to base 64 is to be used to encode and validate the JWT tokens.

To generate, as in the comments, there are two steps:

  1. Create/Generate a random key exactly 32 bytes in length. You can get a good generated value from http://randomkeygen.com (use the CodeIgniter Encryption Keys)
  2. To convert to base 64 refer to: https://www.base64encode.org

Once this is generated, it should never be changed. If it is, then all users will loose their logins and have to log out and re login.

If you forget to set the audience secret, you will see the following yellow “screen of death”:

The users and roles for this are done via the existing Dome User/Roles Module.

See PRIS Tokens (User Setup in Pitram Portal) for information on how to use and consume PRIS routes using token based security.

No Security

To turn off all security:

  1. Make sure the Windows authentication is removed or commented out, as explained above.
  2. In appsettings, set the type to none:

    3. <add key="SecurityType" value="none" />

See Also: General Configuration

Installation Testing & Troubleshooting

Test that PRIS itself is reachable

Use a browser to browse to the PRIS root, for example: site.com/pris or <server>/pris. The PRIS home page should appear.

Test a route with no need for security

Use a browser (anything other than Internet Explorer if you want to see the results easily) and enter: <server>/pris/v1/system/security/identity

A small result should be returned (in other words, no error is reported).

Test a route to get roles from the Pitram Portal

In the browser run the following (substituting your username and password):

v1/system/security/authenticateandgetclaims/{username}/{password}

For example:

v1/system/security/authenticateandgetclaims/peter/mypassword

Even if the credentials you enter are incorrect, you should get back an error telling you the username or the password is incorrect.

Test PRIS backend connection problems

If no results are coming back, or you are getting something like "PRIS cannot connect to Business Model server”, then we can test that the required WCF ports have been opened using netstat, as with this there is nothing to install (it’s part of Windows):

netstat -ano -p tcp | more

or

netstat -ano -p tcp |find "825"   (to filter on a port)

to see if the ports are open.

The above will show the PID, so we can look in Task Manager to make sure the correct application has the port open (we had a case where the BMS port was open, but it was the Dome connector using it).

More info can be found here: Determine which program uses or blocks a port

Extra error information can be obtained on the PRIS machine Event Viewer:

Further Testing

If errors are reported, the best place to look to get more information about the possible cause of those errors, is the Error Viewer on the machine on which PRIS is installed.

Now (from version 1.3) you can use the Open API test harness to test routes.

Another popular alternative is a small, free and easy tool is Postman:

https://www.getpostman.com

The first test we want to run (in Pitram Connect) is to get a security token. To do this, run the following (in POSTMAN or similar):

POST {prishost}/v1/system/security/token

The request body requires the following:

grant_type:password
username:yourusername
password:yourpassword
client_id:pitramconnect
device_id:postdeviceid

The header should have:

Content-Type:application/x-www-form-urlencoded

This body data is form encoded, so actually goes across as:

grant_type=password&username=yourusername&password=yourpassword&client_id=pitramconnect&device_id=postdeviceid

This may be needed if you are a test utility other than Postman.

If Pitram Connect has a problem, then we are most likely to see an error here.

If this does work then we should see something like:

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1bmlxdWVfbmFtZSI6InBlZWNlZSIsIkZpbGUgTWFuYWdlbWVudCI6IkZ1bGxBY2Nlc3MiLCJTeXN0ZW0iOiJGdWxsQWNjZXNzIiwiTG9jYXRpb24iOiJGdWxsQWNjZXNzIiwiRXF1aXBtZW50IjoiUmVhZEFjY2VzcyIsIlBlb3BsZSI6IkZ1bGxBY2Nlc3MiLCJpc3MiOiJQUklTIiwiYXVkIjoiUFJJUyIsImV4cCI6MTQ5NTU5ODE0NiwibmJmIjoxNDk1NTk2MzQ2fQ.7_DK_s4XF_mcUhkjHrIjcit7ROY9lHJDYkCjFX9lCQc",
  "token_type": "bearer",
  "expires_in": 1799,
  "refresh_token": "26dab2c9cd4e4e848de2504ed89ef712",
  "ClientId": "pitramconnect",
  "userName": "peecee",
  ".issued": "Wed, 24 May 2017 03:25:46 GMT",
  ".expires": "Wed, 24 May 2017 03:55:46 GMT"
}