Broker Principal Config Setting

Overview

To improve the capabilities of the Itential platform, the ability to build principal objects via broker calls to a local AAA adapter is supported. This configuration setting (brokerPrincipal) can be found within the authenticationProps of an active profile and it allows an AAA adapter to define a buildPrincipal function (i.e., create principal objects) instead of the Session Manager module.

Sample profile schema for brokerPrincipal

},
 "brokerPrincipal": {
    "$id": "#/properties/authenticationProps/properties/brokerPrincipal",
    "type": "boolean",
    "description": "When brokerPrincipal is set to true, the AAA adapter will be responsible for creating a principal.",
    "title": "Broker Principal",
    "default": false,
    "examples": [false]
}

For more information on the authentication properties in authenticationProps, see the Itential Configuration guide.

How to Use the Broker Principal Setting

To use this feature in developing a custom auth adapter:

1. Add the following code to your Local AAA adapter (at the end of the file before the export statement) and change the console log level to debug.

   --- BEGIN CODE ---
   
   const buildAnonymousPrincipal = function () {
   return {
   id: 9999,
   provenance: 'Pronghorn',
   username: 'anonymous',
   firstname: 'anonymous',
   groups: [],
   roles: [],
   allowedMethods: [],
   allowedViews: [],
   routes: [],
   };
   }
   /**
   
   Make sure a principal is stashed in redis
   
   @param {string} accountId
   */
   local_aaa.prototype.buildPrincipal = async function (accountId, callback) {
   const promised = new Promise((resolve, reject) => {
   console.log('START!')
   setTimeout(() => {
   console.log(I did a thing to build principal);
   resolve();
   }, 3000);
   });
   
   await promised;
   callback(buildAnonymousPrincipal());
   }
   --- END CODE ---
   

2. Restart IAP with the code changes.

3. Login to IAP as admin.

4. Navigate to Admin Essentials → Profiles → Select the active profile → Configure → authenticationProps Schema.

5. Verify there is a checkbox for Broker Principal (unchecked).

   Figure 1: Broker Principal Checkbox
   

6. Check the Broker Principal box and save the profile.

7. Restart IAP.

8. Login to IAP as admin.

9. Upon login, you should have no permissions as you are using the equivalent of an anonymous principal. This verifies the local AAA adapter buildPrincipal function is being called.