This article describes the usage of the authentication policy import functionality that was introduced in IBM Security Verify Access (ISVA) version 10.0.8.0.
IBM Security Verify Access contains a number of different out of the box authentication policies that can be configured and used in a production environment for whatever purpose deemed fit. When a different type of authentication mechanism is required the process involves one of:
- Requesting the new functionality be implemented by development and added to future releases of the product.
- Engaging support, services or some other direct contact to have the authentication policy created using mapping rules and template files. These are then setup individually in ISVA and verified.
- Creating your own authentication policy.
From 10.0.8.0 authentication policy import functionality exists that allows the artifacts and process from options 2 and 3 above to be bundled in a zip file. This zip file can then be shared and easily imported into other environments.
A new GitHub location has been created where different authentication policy bundles can be downloaded and used by anyone
https://github.com/IBM-Security/verify-access-aac-authentication-policies
The bundles can be found in the releases section at the GitHub location.
At the time of writing this article there are only 2 bundles that can be downloaded. As more authentication policies are written they will be added to this location and made available.
If you have custom authentication policies that you have created and would like to share. Please reach out and this can be added to the repository.
The remainder of this article describes the process of creating and importing a bundle into IBM Security Verify Access. The authentication policy created will match the existing hello world example available on Github at
https://github.com/IBM-Security/verify-access-aac-authentication-policies/tree/master/authentication_policies/hello_world
The authentication policy does not do a lot but is used as an example of how to create and import a bundle into IBM Security Verify Access. A single mapping rule and two template files are created.
Procedure
1. Start with a clean directory in your file system.
2. Create a new sub directory named mapping_rules. This is where all of the required mapping rules for the authentication policy must exist.
3. In the mapping_rules directory create a new file names importexample.js.
Contents
importClass(Packages.com.tivoli.am.fim.trustserver.sts.utilities.IDMappingExtUtils);
IDMappingExtUtils.traceString("Entry example mapping rule");
var approved = context.get(Scope.REQUEST, "urn:ibm:security:asf:request:parameter", "approved");
var verify = context.get(Scope.REQUEST, "urn:ibm:security:asf:request:parameter", "@verifying@");
IDMappingExtUtils.traceString("Approved : " + approved);
IDMappingExtUtils.traceString("Verify : " + verify);
if (verify != null && verify != "") {
if (approved != null && approved == "on") {
success.setValue(true);
} else {
page.setValue("/authsvc/authenticator/importexample/notapproved.html");
}
} else {
page.setValue("/authsvc/authenticator/importexample/prompt.html");
}
4. Create a new sub directory named template_files. This is where all of the required template files for the authentication policy must exist.
- The template files must be added using the directory structure required by IBM Security Verify Access. See the existing template files in the local management interface (LMI) to see what is required.
- This directory structure can include globalized files that can support different languages.
5. In the template_files directory create a new file named prompt.html. This file will be added in the directory path C/authsvc/authenticator/importexample. The result is a new file:
C/authsvc/authenticator/importexample/prompt.html
Contents
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Example Imported Authentication Policy</title>
</head>
<body>
<form ID="exampleForm" ACTION="@ACTION@" METHOD="post">
<h1>Confirm Authentication</h1>
<hr/>
<br/>
<fieldset>
<input type="checkbox" name="approved" id="approved"/>
<label for="approved">I approve this authentication</label>
</fieldset>
<br/>
<input type="hidden" name="operation" value="verify" />
<input type="hidden" name="@verifying@" value="true" />
<div>
<button TYPE="submit" ID="submitButton">Submit</button>
</div>
</form>
</body>
</html>
5. In the template_files directory create a new file named notapproved.html. This file will be added in the directory path C/authsvc/authenticator/importexample. The result is a new file:
C/authsvc/authenticator/importexample/notapproved.html
Contents
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Example Imported Authentication Policy</title>
</head>
<body>
<h2>Authentication not approved</h2>
</body>
</html>
6. Locate and examine the yaml schema file at https://github.com/IBM-Security/verify-access-aac-authentication-policies/blob/master/policy.yaml.schema. This schema describes the data that is required and optional in the policy.yaml file.
7. Create a new file at the top level directory (ie alongside the mapping_rules and template_files directories) named policy.yaml. This yaml file describes the authentication policy and references the mapping rules and template files that will be created.
Contents
bundle:
name: Simple Hello World Example
description: This example shows the format for creating a new authentication policy bundle.
version: 1.0
documentation: https://github.com/IBM-Security/verify-access-aac-authentication-policies/tree/master/authentication_policies/hello_world
prereqs:
- Run the Authentication and Context Based Access Configuration wizard on the reverse proxy instance.
- Configure the Username Password authentication mechanism.
authentication_policy:
enabled: true
name: ImportExample
identifier: importexample
description:
policy:
steps:
- name: Username Password
sequence: 1
- name: Import Example
sequence: 2
authentication_mechanisms:
- name: Import Example
description: This is an example infomap based authentication mechanism.
identifier: importexample
mapping_rule: ImportExample
template_files:
- name: prompt.html
location: C/authsvc/authenticator/importexample
macros:
- name: "@verifying@"
value: verify_approval
description: The name of the form input that indicates that the operation is to verify the value of the submitted form.
- name: notapproved.html
location: C/authsvc/authenticator/importexample
mapping_rules:
- name: ImportExample
file_name: importexample.js
macros:
- name: "@verifying@"
value: verify_approval
description: The name of the form input that indicates that the operation is to verify the value of the submitted form.
8. Note the macros entries in the policy.yaml. These are used to indicate to the bundle installer that there are entries in the mapping rules and/or template files that can be updated during the installation of the bundle. This may include variable things like usernames, server names, etc. In the example above the macro named @verifying@ includes a default value verify_approval that will be added in the installer dialog but can be changed if required.
9. Zip all of the contents into a new bundle named importexample.zip.
10. Now that the bundle has been created, open the IBM Security Verify Access local management interface and navigate to AAC —> Policy —> Authentication.
11. Select the Import button in the dropdown menu.
12. A new dialog is opened to install the new authentication policy. Use the Browse button to locate and select the importexample.zip file. Click the Next button.
Note: If any errors are detected in the policy.yaml file the issue will be shown in an error message at this point.
13. A general information page is shown that describes the authentication policy that is going to be installed. All of this information is extracted out of the policy.yaml file. Click the Next button.
Note: The prerequisite tasks required for the authentication policy are listed on this page. Make sure the tasks are completed prior to completing the installation.
14. A page is shown that describes the actual authentication policy as it would if it was being created in the manual way. Click the Next button.
Note: All the fields are readonly apart from the Description. This can be updated if required as this is used as a descriptor in the created policy and is displayed in the LMI. Update it here is the length is going to be an issue.
Note: If an authentication policy already exists with the same name a warning is shown. In this case the Next button is disabled unless the Overwrite checkbox is checked. This will result in the new authentication policy overwriting the existing policy.
15. A page is shown that describes the actual authentication mechanisms as it would if it was being created in the manual way. Click the Next button.
Note: All the fields are readonly.
Note: If an authentication mechanisms already exists with the same name a warning is shown. In this case the Next button is disabled unless the Overwrite checkbox is checked. This will result in the new authentication mechanisms overwriting the existing mechanism.
16. A page is show that describes the mapping rule that will be created. This page also includes a table showing the macros and allows the value to be set/updated for that macro. The policy.yaml included a default value which has been added to the table already and as such no update is required. Click the Next button.
Note: All the fields are readonly apart from the macros table entries.
Note: If a mapping rule already exists with the same name a warning is shown. In this case the Next button is disabled unless the Overwrite checkbox is checked. This will result in the new mapping rule overwriting the existing mapping rule.
17. A page is show that describes the template file that will be created. This page also includes a table showing the macros and allows the value to be set/updated for that macro. The policy.yaml included a default value which has been added to the table already and as such no update is required. Click the Next button.
Note: All the fields are readonly apart from the macros table entries.
Note: If a template file already exists with the same name a warning is shown. In this case the Next button is disabled unless the Overwrite checkbox is checked. This will result in the new template file overwriting the existing template file.
18. A page is show that describes the template file that will be created. No macros exist for this template file and as such there is not macros table shown. Click the Next button.
Note: All the fields are readonly apart from the macros table entries.
Note: If a template file already exists with the same name a warning is shown. In this case the Next button is disabled unless the Overwrite checkbox is checked. This will result in the new template file overwriting the existing template file.
19. A summary page is shown that list the configuration steps that are about to occur. Check the steps and click OK.
20. A request is sent to IBM Security Verify Access to create the new authentication policy. Once complete a new summary page is shown that shows the results of each configuration step. The installation is complete at this stage. The dialog can be closed by clicking Close or click Next to view the JSON payloads that were used to create the authentication policy artifacts.
Note: There is a specific order in which the artifacts are created as they are needed by subsequent creations. This means that after the mapping rules and authentication mechanism is created a pending changes deployment is done. At the end of the installation the state is that the mapping rules and authentication mechanism changes are deployed but the template file and authentication policy changes are not deployed.
21. Try it out by accessing the new policy directly
https://www.mmfa.ibm.com/mga/sps/authsvc/policy/importexample
The username/password login is shown. Enter details of an existing user and click Login.
On successful authentication of the user a confirm authentication page is shown. Check the approval checkbox and click Submit.
A successful login is shown.
