The following is information regarding the administration of Authorization Policies within the TrustBuilder Administrator. For more details regarding concepts and definitions refer to the AZN chapter.
Role to Access
To access the Policies functionality in the TrustBuilder Administrator the TBAGPolicies role is needed.
The authorization policies part of a configuration is a service which has it's own set of configuration parameters and hence it's own configuration file known as a Rule Suite file. Rule Suite files are stored in the AZN directory of a main configuration. For a Rule Suite to function it must be enabled in the main configuration, this is simply checking a check box in the Rule Suite console.
The policies console can be accessed in two ways. Using the Policies link in the left side navigation of the main configuration or by right clicking on a configuration in the Administration screen and clicking policies
Enabling Authorization Policies
The authorization policies are ignored by the main configuration unless they are enabled. This means the service is not configured in the main configuration and so will not be exported to TrustBuilder when the configuration is exported. To enable the authorization policies check the check box that is found in the top right corner of every section of the policies console. When green the policies are enabled in the configuration when the check box is red it is not included. The change is immediate nothing else needs to be saved.
Navigating Through Pages
There are a number of different pages in the Policies console. At the top left of the screen there is a bread crumb trail illustrating which page is currently being used. Each step in the trail is clickable to navigate back/up to previous pages or back to the main configuration.
Authorization Policy Structure in the TrustBuilder Administrator
In TBA authorization policies there are two main parent items: Resources and Rule Suites. Resources are assigned to Rule Suites in a many to one relationship and Rule Suites define the action of the Rules using Policy Infomation Points, Conditions, Assertions and Hints.
- Rule Suites
- Policy Infomation Points (PiPs)
|Resources||This defines the resources that can be accessed by a given user. One resource is related to none or one Rule Suite|
|Rule Suites||This is a policy configuration file that can contain one or more PiPS and Rules. It contains the Rules, PiPs and Resources that are related to it.|
|Policy Information Points||Commonly termed as PiPs they are related to one Rule Suite. Their purpose is to retrieve any additional information needed by the policy. This could be valid Geo Location data from a database or a users secondary email addresses from LDAP.|
|Rules||The Rules contain the deciding logic that is performed to define access to the protected resources. A Rule Suite can contain one or more rules.|
|Conditions||Conditions, related to a Rule, defines what criteria must be true for assertions of that rule to be run. A Rule can have zero or more conditions.|
|Assertions||If the Conditions return true, or there are no Conditions, then the logic defined in the Assertions must be true for access to be granted to the Resource(s).|
|Hints||Hints give the opportunity to provide extra information concerning the outcome of the policy. For instance authorization requires a step up in credentials to access a certain Resource. Rules can have zero or more Hints.|
The Resources that require authorization. They are independent of Rule Suites and Rules and can be created alone. Resources require a unique name and also must be unique with a combination of resource domain and exact match. The following table explains this.
|A||trustbuilder||com||true||Yes this is the first resource|
|B||trustbuilder||com||false||Yes the name is unique, resource and domain are the same as A, but the exact match is different|
|C||trustbuilder||com||false||No the name is unique, resource and domain are the same as A and B but the exact match is the same as B so not unique in that combination|
|D||trustbuilder||be||false||Yes the name is unique, resource and exact match are the same as B but the domain is different.|
|D||securit||jp||true||No the name is not unique despite the resource and domain being unique.|
Adding a Resource
To add a Resource click the Add New Resource button. This will display a form to the right of the screen.
Complete the form and click the Save button. A new row is then created in the Resources table list.
Assigning a Resource to a Rule Suite
A Resource is assigned to a Rule Suite by selecting available Rule Suites from the Rule Suite drop down box in the relevant Resource row. The assignation is created and saved immediately. To dis-assign a Resource select none from the Rule Suite drop down box. Once a Resource is assigned to a Rule Suite it is displayed in the Rule Suite table list in the relevant row.
Editing a Resource
A Resource can be edited at any time by clicking the Edit button in the relevant Resource row. This will open a form on the right side. Click the Save button to update the data. The row of the current Resource that is being edited is highlighted.
Deleting a Resource
To delete a Resource check the check box to the left of the relevant Resource row and click the Delete Selected button. This will remove the Resource from the database and from the Rule Suite that it might be assigned to.
Authorization Rule Suites
A Rule Suite is the top level of authorization rules the name defines the name of the Rule Suite XML configuration file. If the policies console does not find one rule suite file in the configuration it will create a default rule suite xml file named default-rulesuite.
Adding a Rule Suite
To add a new Rule Suite click the Add New Rule Suite button. This will display a form to the right of the screen. Provide a unique name and an optional description and click the Save button. This will create a new row in the Rule Suites table list.
Editing a Rule Suite
A Rule Suite can be edited at any time by clicking the Edit button in the relevant Rule Suite row. This will open a form on the right side. Click the Save button to update the data. The row of the current Rule Suite that is being edited is highlighted.
Deleting a Rule Suite
To delete a Rule Suite check the check box to the left of the relevant Rule Suite row and click the Delete Selected button. This will remove the Rule Suite file and references related to any Resources.
Policy Information Points (PiPs)
PiPs are references to workflows and components that can be used to retrieve additional data in the calculation of an authorization policy. Only full (not draft) workflows and configured components can be listed.
Adding a new PiP
To add a new PiP click the Add New PiP button. This will display a form to the right of the screen. The PiP Name is used as a variable that the outcome of the workflow or component is assigned to that can be referenced in a Rule's Conditions or Assertions. The Payload is a name value set of data, that is translated to a JSON object, that is used as input to the workflow or component. To extra key value name pairs click the Add Payload Data button and an extra row will be added below. To remove a name value pair click the dustbin icon.
Once a PiP is added a new row will be displayed in the PiP table list:
Selecting a Workflow or Component for a PiP
To assign a workflow or component to a PiP select one from the service drop down list. This list only shows non-draft workflows and configured components. The change is immediate and the PiP is updated in the Rule Suite once it is selected.
Editing a PiP
A PiP can be edited at any time by clicking the Edit button in the relevant PiP row. This will open a form on the right side. Click the Save button to update the data. The row of the current PiP that is being edited is highlighted.
Deleting a PiP
To delete a PiP check the check box to the left of the relevant PiP row and click the Delete Selected button. This will remove the PiP from the Rule Suite file.
Access to Rules are from the Rule Suite rows in the Rule Suite table list. For each Rule Suite there is a Rule button. Clicking this will display the PiPs and Rules tabs. When a Rule Suite is created one Rule, named defaultRule, is created automatically.
Adding a Rule
To add a new Rule click the Add New Rule button. This will display a form to the right of the screen. Provide a unique name and an optional result variable name which can be accessed in scripts once the authorization rule has been executed. Click the Save button. This will create a new row in the Rule table list. This Rule is a child of the Rule Suite that is displayed in the bread crumb trail at the top left of the screen. Currently the Rule defaults to a weight of 1.0.
Editing a Rule Result Variable
To change the Result variable of a Rule click the Edit button in the relevant Rule row. This will open a form on the right side. Click the Save button to update the data. The row of the current Rule that is being edited is highlighted.
Deleting a Rule
To delete a Rule check the check box to the left of the relevant Rule row and click the Delete Selected button. This will remove the Rule from the parent Rule Suite that is displayed in the bread crumb trail.
Defining a Rule's Conditions, Assertions and Hints
To define a Rule's details click the Define button in the relevant Rule row in the table list. This will open a new screen with three tabs: Conditions, Assertions and Hints. The Rule that is being edited is displayed in the bread crumb trail situated top left of the screen.
Conditions and Assertions
Assertions are processed if the logic that is defined in Conditions is true, or there are no Conditions.
Add new Condition/Assertion Functions
A full list of available functions to create Conditions or Assertions is presented on the right hand side of the screen. Click on a function name in the list to add it to the Conditions or Assertions, depending upon which tab is currently displayed.
Each function takes one or more arguments, for each argument needed there is an input box. The left hand input is always the source of the data. For this to be a variable taken from a script or workflow, specified in the PiPs it should be written with a preceding dollar sign like this:
If needed the right hand value will be the matching argument. For instance using the String.equals might be something like this:
$username equals John
Saving Conditions and Assertions
Valid Conditions and Assertions are saved automatically when the specific tab is navigated away from. For instance if working in the Assertions tab, create 3 valid Assertions, click the Conditions tab the three Assertions will automatically be saved. Or if preferred there are also Save Assertions/Conditions buttons.
Overall Logical Operator
All Conditions and Assertions are evaluated using the overall operator. This can be one of the following that is applied across the list of functions.
- NOT AND
- NOT OR
To change the overall operator select the desired value from the drop down box located to the right of the Save button. Once the value is selected it is saved immediately.
Deleting Conditions and Assertions
To delete a Condition or Assertion check the check box to the left of the relevant function row and click the Delete Selected button.
Hints are information that can be provided in the result of an authorization policy.
To add a new Hint click the Add New Rule Hint button. Hints are made up of name value pairs (the same for PiPs) that form a JSON object. One row is provided when a new Hint is created with empty values. To add more name value pairs click the Add Hint Data button. To remove name value rows click the relevant dustbin button to the right of the row.
When Hints are Generated
A Hint can be defined to only be returned when the score of the Rule is 0 or it can be set to always be returned. This is done by changing the check box at the top of each Rule Hint group.
Valid Hints are saved automatically when the specific tab is navigated away from. For instance if working in the Hints tab, create a valid Hint, click the Conditions tab the Hint will automatically be saved. Or if preferred there is also a Save Hints button.
To delete a Hint and all of its data click the Delete Hint button.