NIST SPECIAL PUBLICATION 1800-3C
Attribute Based Access Control¶
Volume C:
How-to Guides
Bill Fisher
National Cybersecurity Center of Excellence
National Institute of Standards and Technology
Norm Brickman
Prescott Burden
Santos Jha
Brian Johnson
Andrew Keller
Ted Kolovos
Sudhi Umarji
Sarah Weeks
The MITRE Corporation
McLean, VA
September 2017
SECOND DRAFT
DISCLAIMER
Certain commercial entities, equipment, products, or materials may be identified in this document in order to describe an experimental procedure or concept adequately. Such identification is not intended to imply recommendation or endorsement by NIST or NCCoE, nor is it intended to imply that the entities, equipment, products, or materials are necessarily the best available for the purpose.
National Institute of Standards and Technology Special Publication 1800-3c, Natl. Inst. Stand. Technol. Spec. Publ. 1800-3c, 577 pages, September 2017, CODEN: NSPUE2
FEEDBACK
You can improve this guide by contributing feedback. As you review and adopt this solution for your own organization, we ask you and your colleagues to share your experience and advice with us.
Comments on this publication may be submitted to: abac-nccoe@nist.gov.
Public comment period: September 20, 2017 through October 20, 2017
All comments are subject to release under the Freedom of Information Act (FOIA).
NATIONAL CYBERSECURITY CENTER OF EXCELLENCE
The National Cybersecurity Center of Excellence (NCCoE), a part of the National Institute of Standards and Technology (NIST), is a collaborative hub where industry organizations, government agencies, and academic institutions work together to address businesses’ most pressing cybersecurity issues. This public-private partnership enables the creation of practical cybersecurity solutions for specific industries, as well as for broad, cross-sector technology challenges. Through consortia under Cooperative Research and Development Agreements (CRADAs), including technology partners—from Fortune 50 market leaders to smaller companies specializing in IT security—the NCCoE applies standards and best practices to develop modular, easily adaptable example cybersecurity solutions using commercially available technology. The NCCoE documents these example solutions in the NIST Special Publication 1800 series, which maps capabilities to the NIST Cyber Security Framework and details the steps needed for another entity to recreate the example solution. The NCCoE was established in 2012 by NIST in partnership with the State of Maryland and Montgomery County, Md.
To learn more about the NCCoE, visit https://nccoe.nist.gov. To learn more about NIST, visit https://www.nist.gov.
NIST CYBERSECURITY PRACTICE GUIDES
NIST Cybersecurity Practice Guides (Special Publication Series 1800) target specific cybersecurity challenges in the public and private sectors. They are practical, user-friendly guides that facilitate the adoption of standards-based approaches to cybersecurity. They show members of the information security community how to implement example solutions that help them align more easily with relevant standards and best practices and provide users with the materials lists, configuration files, and other information they need to implement a similar approach.
The documents in this series describe example implementations of cybersecurity practices that businesses and other organizations may voluntarily adopt. These documents do not describe regulations or mandatory practices, nor do they carry statutory authority.
ABSTRACT
Enterprises rely upon strong access control mechanisms to ensure that corporate resources (e.g., applications, networks, systems, and data) are not exposed to anyone other than an authorized user. As business requirements change, enterprises need highly flexible access control mechanisms that can adapt. The application of attribute based policy definitions enables enterprises to accommodate a diverse set of business cases. This NCCoE practice guide details a collaborative effort between the NCCoE and technology providers to demonstrate a standards-based approach to attribute based access control (ABAC).
This guide discusses potential security risks facing organizations, benefits that may result from the implementation of an ABAC system, and the approach the NCCoE took in developing a reference architecture and build. It includes a discussion of major architecture design considerations, an explanation of security characteristic achieved by the reference design, and a mapping of security characteristics to applicable standards and security control families.
For parties interested in adopting all or part of the NCCoE reference architecture, this guide includes a detailed description of the installation, configuration, and integration of all components.
KEYWORDS
access control; access management; attribute provider; authentication; authorization; identity federation; identity management; identity provider; relying party
ACKNOWLEDGMENTS
We are grateful to the following individuals for their generous contributions of expertise and time.
Name | Organization |
Nate Lesser | NIST National Cybersecurity Center of Excellence |
Paul Timmel | NIST National Cybersecurity Center of Excellence |
Paul Grassi | NIST National Strategy for Trusted Identities in Cyberspace |
Mike Garcia | NIST National Strategy for Trusted Identities in Cyberspace |
Naomi Lefkovitz | NIST National Strategy for Trusted Identities in Cyberspace |
Rene Peralta | NIST National Strategy for Trusted Identities in Cyberspace |
Dave Ferriaolo | NIST Computer Security Division |
Vincent Hu | NIST Computer Security Division |
Roger Wiggenstam | NextLabs Inc |
John Conduit | NextLabs Inc |
Srikanth Karanam | NextLabs Inc |
Adam Madlin | Symantec Corporation |
Steve Kruse | Symantec Corporation |
Steve Schmalz | RSA |
Ben Smith | RSA |
Andrew Whelchel | RSA |
Chris Leggett | Ping Identity |
Paul Fox | Microsoft Corporation |
Derek Keatley | Microsoft Corporation |
Hemma Prafullchandra | Hytrust |
John McLeese | Hytrust |
Dave Cox | ID/Dataweb |
Chris Donovan | ID/Dataweb |
Pete Romness | Cisco |
Kevin McFadden | Cisco |
John Eppish | Cisco |
Chris Ceppi | Situational Corporation |
The Technology Partners/Collaborators who participated in this build submitted their capabilities in response to a notice in the Federal Register. Respondents with relevant capabilities or product components were invited to sign a Cooperative Research and Development Agreement (CRADA) with NIST, allowing them to participate in a consortium to build this example solution. We worked with:
Technology Partner/Collaborator | Build Involvement |
Ping Identity | PingFederate Federation Server |
NextLabs | Entitlements Management Policy Enforcement Point |
Microsoft | Policy Controller Policy decision point |
RSA | Control Center Policy Administration Point |
Symantec | Active Directory |
Cisco | SharePoint |
List of Figures
Figure 2‑1 Out-of-Band Token Length
Figure 2‑2 Successful List Created
Figure 10‑2 Ping Custom Data Store Interaction Diagram
Figure 10‑3 Ping Custom Data Store Class Diagram
Figure 10‑4 NextLabs PIP Plugin Class Diagram
Figure 10‑5 NextLabs PIP Plugin Interaction Diagram
Figure 10‑6 Communication Between Plugin and Relying Party
Figure 10‑7 Protocol Broker Interaction Diagram
Figure 10‑8 Protocol Broker Class Diagram
List of Tables
Table 2‑1 Persistent User Enrollment
Table 2‑4 Session Sign-In – Low Risk
Table 2‑5 Session Sign-In – Medium Risk
Table 2‑6 Session Sign-In – High Risk
Table 2‑7 Session Sign-In – Critical Risk
1. Introduction¶
The following guides show IT professionals and security engineers how we implemented this example solution. We cover all of the products employed in this reference design. We do not recreate the product manufacturers’ documentation, which is presumed to be widely available. Rather, these guides show how we incorporated the products together in our environment.
Note: These are not comprehensive tutorials. There are many possible service and security configurations for these products that are out of scope for this reference design.
1.1. Practice Guide Structure¶
This NIST Cybersecurity Practice Guide demonstrates a standards-based reference design and provides users with the information they need to replicate an Attribute Based Access Control (ABAC) implementation. This reference design is modular and can be deployed in whole or in parts.
This guide contains three volumes:
- NIST SP 1800-11a: Executive Summary
- NIST SP 1800-11b: Approach, Architecture, and Security Characteristics – what we built and why
- NIST SP 1800-3c: How-To Guides – instructions for building the example solution (you are here)
Depending on your role in your organization, you might use this guide in different ways:
Business decision makers, including chief security and technology officers will be interested in the Executive Summary (NIST SP 1800-11a), which describes the:
- challenges enterprises face in access control solutions
- example solution built at the NCCoE
- benefits of adopting the example solution
Technology or security program managers who are concerned with how to identify, understand, assess, and mitigate risk will be interested in this part of the guide, NIST SP 1800-11b, which describes what we did and why. The following sections will be of particular interest:
- Section 4.4.1, Risk, provides a description of the risk analysis we performed
- Section 4.4.3, Security Control Map, maps the security characteristics of this example solution to cybersecurity standards and best practices
You might share the Executive Summary, (NIST SP 1800-11a), with your leadership team members to help them understand the importance of adopting standards-based ABAC implementation.
IT professionals who want to implement an approach like this will find the whole practice guide useful. You can use the How-To portion of the guide, NIST SP 1800-3c, to replicate all or parts of the build created in our lab. The How-To guide provides specific product installation, configuration, and integration instructions for implementing the example solution. We do not recreate the product manufacturers’ documentation, which is generally widely available. Rather, we show how we incorporated the products together in our environment to create an example solution.
This guide assumes that IT professionals have experience implementing security products within the enterprise. While we have used a suite of commercial products to address this challenge, this guide does not endorse these particular products. Your organization can adopt this solution or one that adheres to these guidelines in whole, or you can use this guide as a starting point for tailoring and implementing parts of an ABAC solution. Your organization’s security experts should identify the products that will best integrate with your existing tools and IT system infrastructure. We hope you will seek products that are congruent with applicable standards and best practices. Volume B, Section 4.5, Technologies, lists the products we used and maps them to the cybersecurity controls provided by this reference solution.
A NIST Cybersecurity Practice Guide does not describe “the” solution, but a possible solution. This is a draft guide. We seek feedback on its contents and welcome your input. Comments, suggestions, and success stories will improve subsequent versions of this guide. Please contribute your thoughts to abac-nccoe@nist.gov.
1.2. Build Overview¶
The following section provides detailed instructions for implementing, configuring and integrating an ABAC solution coupled with identity and attribute federation. These instructions detail an example of an ABAC implementation using a policy enforcement point that is closely coupled with a SharePoint file server and two sources of environmental attributes. Before implementing this reference design, individuals should refer to NIST SP 1800-3b Approach, Architecture, and Security Characteristics to better understand the design decision that we made as part of this implementation.
1.3. Typographical Conventions¶
The following table presents typographic conventions used in this volume.
Typeface/Symbol | Meaning | Example | |
---|---|---|---|
Italics | filenames and pathnames references to documents that are not hyperlinks, new terms, and placeholders |
For detailed definitions of terms, see the NCCoE Glossary. | |
Bold | names of menus, options, command buttons and fields | Choose File > Edit. | |
Monospace
|
command-line input, on-screen computer output, sample code examples, status codes | mkdir
|
|
Monospace Bold
|
command-line user input contrasted with computer output | service sshd start
|
|
blue text | link to other parts of the document, a web URL, or an email address | All publications from NIST’s National Cybersecurity Center of Excellence are available at https://nccoe.nist.gov. |
2. Setting Up the Identity Provider¶
This guide details an attribute based access control (ABAC) implementation that leverages identity federation. In a federation model, the identity provider (IdP) authenticates the user requesting access and provides attributes assigned to that user to the relying party (RP). In addition to attributes assigned to the user, the IdP sends environmental and device attributes to the RP. The RP, which controls access to the resource requested by the user, utilizes the identity and attributes information to make runtime decisions to grant or deny access to the user.
In this section, we install and configure federation components at the identity provider. The components in this section facilitate federated, Security Assertion Markup Language (SAML)-based authentication using account credentials in the identity provider’s Microsoft Active Directory Domain Services (referred to as Microsoft AD in this guide). The federated authentication between the RP and IdP is facilitated by Ping Identity’s PingFederate application. This build also requires the user to authenticate with a second factor, which is handled by the RSA adaptive authentication server.
Each of the components used for the build are described in the Components section. Following the Components section are step-by-step instructions for installing, configuring, and integrating the components.
If you follow the instructions in this section, you will be able to perform a Functional Test to verify the successful completion of the steps for installing, configuring, and integrating the components.
2.1. Components¶
Federated Authentication at the IdP involves the following distinct components:
- Cisco Switch (Catalyst 2960-X Series): Acts as a switch and router in the build, routing traffic from users to the services and applications on another network segment
- Cisco Identity Services Engine (ISE): Authenticates users from other networks or network segments, and provides device and network attributes to the Ping-Federate IdP via the Situational Context Connector
- Microsoft AD: An LDAP directory service that stores user account and attribute information
- Nginx Web Server: A web server installed on a separate host that is required for handling Network Access Device (NAD) redirects for the Situational Context Connector. In this build, we used Nginx.
- PingFederate-IdP: A federation system or trust broker for the IdP
- PingFederate-RP: Serves as the trust broker for SharePoint
- RSA Adaptive Authentication (RSA AA): Requires the user to authentication using a Short Message Service (SMS) message sent to the user’s mobile phone. Collects environmental information about the user and the user’s system or agent at the time of authentication.
- SCE Plug-in: Handles communications between the PingFederate-IdP and the RSA AA
- Situational Context Connector: IdP Adapter for PingFederate that integrates PingFederate with the Cisco Identity Server Engine via the pxGrid Application Programming Interface (API)
2.1.1. Cisco Switch and Cisco Identity Services Engine¶
The Cisco Catalyst 2960-X Series switch serves as a switching and routing device, primarily for the purpose of routing users’ traffic from one network or network segment to another, where the protected resources and services are located. The Cisco ISE authenticates users whose traffic comes from the switch, and from that authentication provides device and network attributes to the PingFederate IdP via the Situational Context Connector.
2.1.2. Microsoft AD¶
Microsoft AD acts as a user identity management repository for the IdP. It includes the ability to provision and de-provision user identities; the creation, modification, and deletion of subject attributes; and the provisioning and de-provisioning of subject attributes to specific user identities. In this build, Microsoft AD is the only source for subject attributes from the IdP.
2.1.3. Nginx Web Server¶
Nginx acts as a web server that handles NAD redirects for the Situational Context Connector. It is used to trigger the NAD (Cisco Switch in this case) to insert the session identification (ID) as a parameter to create a secure browser cookie, which gets returned to PingFederate and then verified by the Context Connector during authentication. When the Context Connector matches the session ID from the secure browser cookie with the session ID from Cisco ISE, federation can continue, and a Security Assertion Markup Language (SAML) response is returned to the browser. Finally, the browser POSTs a SAML response to the PingFederate-RP.
2.1.4. PingFederate-IdP¶
Ping Identity PingFederate-IdP serves as a federation system or trust broker for the IdP. PingFederate-IdP provides initial user authentication and retrieval of user attributes to satisfy SAML requests from the RP. Once the user has been authenticated, PingFederate-IdP queries subject attributes from AD and environmental attributes from the RSA AA event log. PingFederate-IdP packages both subject and environmental attributes in a SAML 2.0 token to be sent to the RP.
PingFederate Usage Notes:
When using the PingFederate application to perform an administrative configuration, there is usually a sequence of screens that require user entry, ending with a summary page. Once you click Done on the summary page, you must also click Save on the following page to actually save the configurations. If you forget to click Save, you may inadvertently lose changes to the configuration.
In the PingFederate application and associated documentation, the RP is referred to as the Service Provider.
When using the PingFederate application to perform configuration, refer to the title of the tab with a small star icon to its left to identify the item you are currently configuring. For example, if you navigated to the following screen, you would be on the IdP Adapter screen.
2.1.5. PingFederate-RP¶
Ping Identity PingFederate-RP serves as the trust broker for SharePoint. When the user requires authentication, PingFederate-RP redirects the user to the IdP via a SAML request to get the necessary assertions. Once authenticated, PingFederate-RP arranges for the browser’s Hypertext Transfer Protocol Secure (HTTPS) content to have the proper information in proper format for acceptance at the target resource (SharePoint).
2.1.6. RSA Adaptive Authentication¶
RSA AA gathers environmental information about the user and the user’s system or agent at the time of authentication. RSA AA collects information such as patch level, operating system, and location, and it generates a risk score associated with the user authentication. A risk score threshold can then be defined in RSA AA, which, if exceeded, can force a user to step up to one of the additional authentication mechanisms. In this build, information collected by RSA AA to generate a risk score is also passed through PingFederate-IdP to the RP side of the operation to be used as environmental attributes. The RSA AA event log contains the transaction ID of each user authentication and the associated environmental information collected by RSA AA at the time of authentication.
2.1.7. SCE Plug-in¶
The SCE Plug-in handles communications between the PingFederate-IdP and the RSA AA. It is responsible for passing the RSA AA transaction ID for the user authentication that PingFederate-IdP uses to query the RSA AA event log.
2.1.8. Situational Context Connector¶
The Situational Context Connector is an IdP adapter for PingFederate that integrates PingFederate with the Cisco Identity Server Engine via the pxGrid API. Deploying this solution for PingFederate enables device-level authentication and authorization for web single sign-on (SSO) use cases. When a user attempts a SSO via PingFederate, the Context Connector queries Cisco ISE, retrieves the device context for the end‐user device, and matches device context with the credentials of an authenticated user. The result is a session based on a combination of user and device information. The Context Connector enables real‐time evaluation of Cisco ISE state-of-the-art device profiling. The Context Connector can provide information about the user and the session to the PingFederate IdP, which the PingFederate IdP includes in the SAML token sent to the PingFederate RP. The Context Connector relies on a web server for NAD redirects (implemented with Nginx on a separate server in this build), and a Session Validator that is included in the Situation Context Connector integration kit.
2.1.9. Required or Recommended Files, Hardware, and Software¶
Component | Required Files | Recommended or Minimum Hardware Requirements | Hardware Used in this Build | Recommended or Minimum Operating System or Other Software | Operating System or Other Software Used in this Build |
---|---|---|---|---|---|
Cisco ISE 2.1 (as Virtual Appliance) | ise-2.1.0.474.SPA.x86_64.iso | 16GB RAM; 6 cores, 2GHz or faster; 200 GB free disk space | 16GB RAM; 4 cores, 2GHz; 200 GB hard disk space | N/A | N/A |
Microsoft AD | N/A | 512MB RAM; 1.4GHz CPU; 32GB free disk space | 4GB RAM; 2.2GHz CPU; 108GB free disk space | N/A | Microsoft Windows Server 2012 |
PingFederate | N/A | 4GB RAM; 4 cores; 1.8 GHz or faster; 750 MB free disk space | 4GB RAM; 2.2GHz CPU; 98 GB | Microsoft Windows Server 2008 R2 | Microsoft Windows Server 2012 |
SCE Plug-in | sce-adapters-pingfederate-aa.1.1.jar | 1GB RAM; 1.8GHz CPU; 250MB free disk space | 4GB RAM; 2.2GHz CPU; 98 GB | N/A | Microsoft Windows Server 2012 |
RSA AA | Adaptive Authentication (On-Premise) 7.0.0.0-SNAPSHOT | 6GB RAM; 2.2GHz CPU; 40GB free disk space | 6GB RAM; 2.2GHz CPU; 150GB free disk space | Windows Server 2008; Apache Tomcat 7.0; Microsoft SQL Server 2008 | Microsoft Windows Server 2008 (64-bit) |
Situational Context Connector | Situational_Context_Connector_v21.zip (pf.plugins.ise-idp-adapter.jar; index.jsp); Situational_SessionValidator.zip | N/A | 4GB RAM; 2.2GHz CPU; 98 GB | N/A | Microsoft Windows Server 2012 |
Nginx web server | nginx-1.11.4.zip | N/A | 4GB RAM; 2.2 GHz CPU; 32GB | Windows XP, Linux 2.2, Free BSD 3 | Microsoft Windows 7 |
2.2. Configuring l PC for 802.1x Auth¶
On the client PC, go to Control Panel > System and Security > System.
Click on Change settings.
Click on the Change button.
Select Domain.
Enter the domain to join, “abac.test.” It will require authentication using a user that’ is capable of adding a computer to the domain controller.
2.2.1. Configure MS Native Supplicant for Wired 802.1x¶
On the client PC, go to Control Panel > System and Security > Administrative Tools > Services.
Right-click on Wired AutoConfig.
Select Properties.
Change the Startup type to Automatic.
Click Apply.
Click OK.
Go to Control Panel > Network and Internet > Network and Sharing Center.
Click on Change adapter settings.
Right-click on your connection adapter and select Properties.
Click the Authentication tab.
Click on Additional Settings.
Check the Specify Authentication Mode checkbox.
Select User of computer authentication.
Check the Enable single sign on for this network checkbox.
Click OK.
Click on Settings next to Microsoft: Protected EAP (PEAP).
Uncheck Validate server certificate.
Click OK and proceed back to the desktop and log out.
2.3. Install Nginx Web Server¶
A web server is required for NAD redirects during the Situational Context Connector’s authentication flow. In our build, we implemented the web server using Nginx.
Log on to the server that will host the Nginx web server.
Follow the instructions at the link below to install Nginx on Windows.
2.4. Install Microsoft AD¶
Log on to the server that will host Microsoft AD.
Follow the instructions at the link below to create a new Microsoft AD domain that will store the accounts and identity information for the identity provider.
During setup, you will be asked to provide a name for your new domain. The name of the domain used for this build is ABAC.TEST.
2.4.1. Create a User in Microsoft AD¶
To create a user account in the Microsoft AD Domain:
Launch the Active Directory Users and Computers program.
Click on the name of your domain in the left pane and then right-click on the Users folder in the right pane. In this guide, the name of the domain is “ABAC.TEST.”
In the pop-up menu that appears, select New, and then select User.
In the New Object - User screen that appears, type the First and Last name of the user, as well as their User logon name (that is, the account name).
Click Next.
In the password screen that appears, type in the user’s initial password. Then, type it again in the Confirm password field. When users log in for the first time, they will be prompted to create their own unique password.
Click Next.
In the confirmation screen with information about the new user that appears, click Finish to complete the operation.
When the user logs on to the domain for the first time, the user will be prompted to create a new, unique password.
The following illustrations demonstrate what the new password screens may look like on Microsoft Windows Server 2012 when the user Lucy Smith attempts to log on to a computer in the ABAC.TEST domain using her user name lsmith and the initial password.
When Lucy clicks OK, she will see the screen below. She will type in her new password, which adheres to the organization’s password strength policy; then she will type the password in again to confirm.
When she presses Enter, Microsoft Windows will change her password.
2.4.2. Create the Lightweight Directory Access Protocol User for Federated Authentication¶
Follow the steps in the previous section to create a user named Lightweight Directory Access Protocol (LDAP) user in Microsoft AD. The PingFederate-IdP will use this user account to perform LDAP queries in Microsoft AD.
2.4.3. Create the LDAP User for Cisco ISE Administration¶
Follow the steps in the previous section to create a user named ciscoise_svc_account in Microsoft AD. The Cisco ISE will use this user account to perform LDAP queries in Microsoft AD.
2.5. Configure the Cisco Switch¶
The Cisco Switch is configured in this build to represent realistic network segmentation separating users and protected network components and services on the IdP’s network. Two virtual local area networks (VLANs) are configured, and traffic is routed between the user VLAN and the services VLAN.
Complete the initial setup of the switch with the Running Express Setup instructions found in the document “Getting Started Guide for the Catalyst 2960-X and 2960-XR Switches,” available at the link below.
The switch in our build is configured as seen below.
service timestamps debug datetime msec service timestamps log datetime msec no service password-encryption ! hostname Switch ! boot-start-marker boot-end-marker ! ! username admin privilege 15 secret 5 $1$ZHMh$mD3FQRDvhAVbuFg49iOyq. aaa new-model ! ! aaa authentication login default local aaa authentication dot1x default group radius aaa authorization console aaa authorization exec default local aaa authorization network default group radius aaa accounting update periodic 5 aaa accounting dot1x default start-stop group radius ! ! ! ! ! aaa server radius dynamic-author client 10.33.7.9 server-key [xxxxxxxxxxxxxxxx] ! aaa session-id common clock timezone EST -4 0 switch 1 provision ws-c2960x-24ts-l ! ! ! ! ip dhcp excluded-address 10.33.50.193 10.33.50.194 ip dhcp excluded-address 10.33.7.1 10.33.7.230 ! ip dhcp pool CLIENTS network 10.33.50.192 255.255.255.240 default-router 10.33.50.193 dns-server 10.97.74.8 ! ip dhcp pool NCCOE network 10.33.7.0 255.255.255.0 default-router 10.33.7.1 dns-server 10.97.74.8 ! ! ip domain-name abac.test ip name-server 10.33.7.230 vtp mode transparent ! ! ! ! ! epm logging ! ! crypto pki trustpoint TP-self-signed-1455706752 enrollment selfsigned subject-name cn=IOS-Self-Signed-Certificate-1455706752 revocation-check none rsakeypair TP-self-signed-1455706752 ! ! crypto pki certificate chain TP-self-signed-1455706752 certificate self-signed 01 3082022B 30820194 A0030201 02020101 300D0609 2A864886 F70D0101 05050030 31312F30 2D060355 04031326 494F532D 53656C66 2D536967 6E65642D 43657274 69666963 6174652D 31343535 37303637 3532301E 170D3136 30383135 32313530 35385A17 0D323030 31303130 30303030 305A3031 312F302D 06035504 03132649 4F532D53 656C662D 5369676E 65642D43 65727469 66696361 74652D31 34353537 30363735 3230819F 300D0609 2A864886 F70D0101 01050003 818D0030 81890281 8100970B 2180DACE EC47660F 5DCEEBC8 8E55475C 39A36018 FE770EFF 378662F6 8846AD8E D4F0E922 33E1B06E AA2526F0 16A8B451 07227347 2B82C6F6 EFA04BAC D561EBA9 F0B85AE2 C50977DC 605D7573 489FD27B 0583F6FE 8D70DF0B CBD3162B 9E1FE937 371FA4AE 905EA47A 667ACC32 05D5DC7F 1E582001 DD40C159 3A21479C D34F0203 010001A3 53305130 0F060355 1D130101 FF040530 030101FF 301F0603 551D2304 18301680 1457B47B 85B93B03 3557754B 9298D87C 89EED062 64301D06 03551D0E 04160414 57B47B85 B93B0335 57754B92 98D87C89 EED06264 300D0609 2A864886 F70D0101 05050003 81810079 9AE74655 14C450FE 6F6B4E63 1CBCD9AF 15D8B911 2C55785A 020E18C7 4F3C28A7 A714E961 933DE0DF F3FB19F6 08AA2FD4 DCD95B9F 161317C0 3BDCD75F D4850E06 38153D02 260300D1 8D1D8794 9B9A0A3B C69269C6 E83CD422 F24F3C17 1AE8F70A F75E7B0F A8FF7946 85328DFB 1C39F676 C3FC5B29 A1900D37 E7226576 183765 quit dot1x system-auth-control ! spanning-tree mode rapid-pvst spanning-tree extend system-id ! ! ! ! vlan internal allocation policy ascending ! vlan 207,2084 ! ! ! ! ! ! ! ! ! ! ! ! interface FastEthernet0 no ip address no ip route-cache ! interface GigabitEthernet1/0/1 switchport access vlan 207 spanning-tree portfast edge ! interface GigabitEthernet1/0/2 switchport access vlan 2084 switchport mode access spanning-tree portfast edge ! interface GigabitEthernet1/0/3 switchport access vlan 207 spanning-tree portfast edge ! interface GigabitEthernet1/0/13 switchport access vlan 2084 spanning-tree portfast edge ! interface GigabitEthernet1/0/20 switchport access vlan 2084 switchport mode access authentication event fail action next-method authentication order dot1x mab authentication priority dot1x mab authentication port-control auto authentication violation restrict snmp trap mac-notification change added snmp trap mac-notification change removed dot1x pae authenticator dot1x timeout tx-period 10 spanning-tree portfast edge spanning-tree bpduguard enable ! interface GigabitEthernet1/0/21 switchport access vlan 207 switchport mode access authentication event fail action next-method authentication order dot1x mab authentication priority dot1x mab authentication port-control auto authentication violation restrict snmp trap mac-notification change added snmp trap mac-notification change removed dot1x pae authenticator dot1x timeout tx-period 10 spanning-tree portfast edge spanning-tree bpduguard enable ! interface Vlan1 no ip address no ip route-cache ! interface Vlan207 ip address 10.33.7.2 255.255.255.0 ! interface Vlan2084 ip address 10.33.50.194 255.255.255.240 ip helper-address 10.33.7.9 ! ip default-gateway 10.33.7.1 ip http server ip http authentication local ip http secure-server ! ! ip access-list extended ACL-REDIRECT deny ip any host 10.33.7.9 permit ip any host 10.33.7.6 ip radius source-interface Vlan207 logging origin-id ip logging source-interface Vlan207 logging host 10.33.7.9 transport udp port 20514 access-list 10 permit 10.33.7.9 access-list 10 deny any log ! snmp-server community ciscoro RO 10 snmp-server trap-source Vlan207 snmp-server source-interface informs Vlan207 snmp-server enable traps snmp linkdown linkup snmp-server enable traps mac-notification change move threshold snmp-server host 10.33.7.9 version 2c cisco mac-notification ! radius-server attribute 6 on-for-login-auth radius-server attribute 8 include-in-access-req radius-server attribute 25 access-request include radius-server dead-criteria time 30 tries 5 ! radius server ABAC-CiscoISE address ipv4 10.33.7.9 auth-port 1812 acct-port 1813 key [xxxxxxxxxxxxxxxx] ! ! line con 0 line vty 0 4 exec-timeout 300 0 logging synchronous line vty 5 15 logging synchronous ! ntp server 10.97.74.8 mac address-table notification change mac address-table notification mac-move ! end
2.6. Install and Configure Cisco Identity Services Engine¶
On a Redhat or CentOS server, boot from the Cisco ISE iso file.
At the installation screen, choose your boot option and press Enter.
Once installation is complete, it restarts. Enter setup and press Enter.
Enter ISE configuration information (ISE hostname, Internet Protocol [IP] addresses, domain name service [DNS] domain and name servers, Network Time Protocol [NTP] server, time zone, username, and password):
ISE will continue and create the database. ISE will automatically reboot after a successful installation. After the reboot, you can log in to ISE via any browser reachable in your domain by entering https://<IP Address of ISE server>/admin, as seen below:
After logging in, you will see the default ISE dashboard:
2.6.1. Configure Cisco ISE with Microsoft AD¶
While logged in to the ISE administration console, navigate to Administration > Identity Management > External Identity Sources > Active Directory.
Follow the instructions at the link below, beginning on page 11, Steps 1-9, to configure Cisco ISE with Microsoft AD. Note: these instructions are in the section Testing Environment > Cisco Identity Service Engine (ISE 2.0) VM Setup > Initial ISE Setup > AD User Setup.
Note: At step 3, provide the credentials of the user account created earlier to join ISE to the existing AD domain (eg, ciscoise_svc_account).
2.6.2. Add Network Device to ISE¶
Follow the instructions at the link below, beginning on page 14, Steps 1-3, to register the NAD with ISE. Note: these instructions are in the section Testing Environment > Cisco Identity Service Engine (ISE 2.0) VM Setup > Initial ISE Setup > Network Devices.
Note: The shared secret used on Step 2, “Enable Radius Authentication Settings and enter the shared secrets,” must be the same key that was used for configuring aaa on the switch. If the switch has not yet been configured, remember to record the secret used here so that it can be used when configuring aaa on the switch.
2.6.3. Configure ISE for pxGrid¶
Follow the instructions at the link below, beginning on page 15, Steps 1-4, to enable a pxGrid persona, used by the Situational Context Connector to query ISE for device and network attributes. Note: these instructions are in the section Configuring ISE for pxGrid.
2.6.4. Enable ISE Policy Sets¶
Navigate to Administration > System > Settings.
In the left sidebar, click on Policy Sets.
Click the Enabled radio button.
Click Save.
In the pop-up, click OK and log back into ISE.
2.6.5. Configure Authentication Policy¶
Navigate to Policy > Policy Sets.
In the left sidebar, click on Default.
Click on the Dot1x rule.
Click on the plus icon.
Change the value of Identity Source to “pxGrid_Users.”
Scroll to the bottom of the page and click Save.
2.6.6. Configure Authorization Policy¶
Navigate to Administration > Guest Access.
In the sidebar, click on Guest Portals.
Click Create.
Choose Sponsored Guest Portal.
Click Continue.
Provide a name, ABAC-Guest.
Under Portal settings, set the HTTPS port to 8000.
Click Save.
In the main menu, navigate to Policy > Policy Elements.
In the submenu, navigate to Results > Authorization > Authorization Profiles.
Click Add.
In the name field, enter “IDIPRedirect.”
Set the access type to “ACCESS_ACCEPT.”
Under Common Tasks, put a check next to Web Redirection (CWA, MDM, NSP, CPP).
In the revealed fields, choose Centralized Web Auth.
Set the ACL field to “ACL-REDIRECT.”
Set the value such that it matches the created guest portal, “ABAC-Guest.”
Put a check next to Static IP/Host name/FQDN.
Enter the hostname of the server on which Ping Federate is running, “idp.abac.test.”
Click Submit.
2.6.7. Add Rule for Authorization Policy¶
Navigate to Policy > Policy Sets.
In the right sidebar, click on Default.
Under the Authorization Policy section, click the triangle next to edit.
Provide a name for the rule, IDIP REDIRECT.
Click the plus button next to condition.
Choose, Select Existing Condition from Library.
Click the arrow next to Select Condition
Choose Compound Conditions.
Choose wired_802.1x.
Click the cog icon.
Choose Add Attribute/Value.
Select Network Access.
Select EapAuthentication.
Click the arrow in the box next to Equals.
Select EAP-MSCHAPv2.
Click the plus icon in the then box.
Select Standard.
Select IDIPRedirect.
Click Done.
Click Save.
Machine Authorization Policy Rule
- Navigate to Policy > Policy Elements > Results.
- In the left sidebar, navigate to Authorization > Downloadable ACLs.
Click Add.
For Name enter Wired_AD_ONLY.
For DACL Content match the entry below.
Click Submit.
Navigate back to Policy > Policy Sets.
Click on Default in the left sidebar.
Click the triangle next to the edit button on the IDIP REDIRECT line.
Click Insert New Rule Above.
Enter Wired Machine for the name.
Click the plus button next to condition.
Choose Create New Condition.
In the Select Attribute box, click the arrow.
Select PxGrid_Users.
Select ExternalGroups.
In the equals box, click the arrow.
Select ABAC.TEST/Users/Domain Computers.
In the Then box, click on the plus icon.
Click the arrow in the Select an Item box.
Click the cog in the top right of the pop-up window.
Select Add New Standard Profile.
Name the profile Wired_AD_ONLY.
In the Common Tasks section, check the box next to DACL Name.
Select Wired_AD_ONLY from the drop-down.
Click Save.
The completed rule should look similar to the one below.
User Authorization Policy Rule
Navigate back to Policy > Policy Elements > Results.
In the left sidebar, click on Authorization > Downloadable ACLs.
Click Add.
In the Name field, type Wired_PERMIT_ALL.
In the DACL Content field, type permit ip any any.
Click Submit.
Navigate back to Policy > Policy Sets.
Click on Default in the left sidebar.
Click the triangle next to the edit button on the IDIP REDIRECT line.
Click Insert New Rule Below.
In the name field, type Wired User.
Click the plus icon in the condition box.
Select Create New Condition.
In the Select Attribute box, click the arrow.
Select PxGrid_Users.
Select ExternalGroups.
In the equals box, click the arrow.
Select ABAC.TEST/USERS/Domain Users.
Click the cog.
Select Add Attribute/Value.
In the new attribute box, select Network Access.
Select WasMachineAuthenticated.
In the equals box, select True.
In the then box, click the plus icon.
Click Select an item.
Click the cog.
Select Add New Standard Profile
In the name field, put Wired_PERMIT_ALL.
In the Common Tasks section, check the box next to DACL Name.
In the box that appears, select Wired_PERMIT_ALL.
Click Save.
Back on the Policy page, click Save again. The final rule should
2.7. Install RSA AA¶
RSA AA (On-Premise) comes packaged as a virtual snapshot that must be installed on a virtual machine (VM). A full installation requires core and back office applications, database scripts, and maintenance tools – all necessary for this build. Follow these instructions to install RSA AA for the identity provider.
Log on to VMware and load the RSA AA virtual appliance (e.g., Adaptive Authentication [On-Premise] 7.0.0.0-SNAPSHOT).
Start the RSA AA VM using VMware.
Log on to the server that hosts the new VM.
Launch the RSA AA installation file.
On the Installation Types screen, select Full to install all required components. Then, click Next.
Click Next in the Installation Components screen.
In the environment screen, set the database type (MS SQL) and the JDBC driver file as shown in the following screenshot.
For the core database setup, create a new database, and set the core database properties and credentials.
On the Core Database screen, set parameters for the data and log files (directory, name, size, and growth).
On the Core Applications screen, select to install the image service, and provide the web service credentials and application server properties.
On the Site-to-User Authentication screen, select Install site-to-user images, which defines how the site authenticates users. Select Save images in the Core Database and select the directory shown in the following screenshot as the source directory. During enrollment, users are asked to select a personal image for authentication.
Review the configuration options on the Installation Parameters Summary and click Install. Once complete, you can confirm that the installation was successful by viewing the log files.
2.8. Configure RSA AA Rules¶
RSA has a built-in policy management application that allows administrators to create and update rules for user login based on various scenarios. For example, high-risk users can be required to answer challenge questions or respond to an out-of-band SMS. For more information, see the Back Office User’s Guide. This example shows how to create a challenge rule for users to confirm identity for large transactions using an out-of-band SMS code. RSA Back Office allows administrators to manage setup policy for enabling the enhanced features provided by the RSA adapter, such as answering challenge questions and providing SMS confirmation codes enabled through this interface.
2.8.1. Create Rule for Non-Persistent User Enrollment¶
RSA AA requires information for each user to help verify their identity. These users are classified into two groups: persistent and non-persistent users. A rule is created to request enrollment information for non-persistent users, those not kept in the user database.
Log in to the Back Office application [http://xxx.xxx.xxx.xxx:8080/backoffice]
Once logged in, click Manage Rules under Policy Management. Select New Rule.
In the Rule Details (in the General tab):
Set Rule Name to User Enrollment Not Persistent - Adapter.
Set the Status to Production.
Note: The rule cannot be in production until it is created and approved by an administrator.
In Event Type, select Create User and Enroll.
Set the Order to 1.
Click Next.
In the Rule Conditions page, add a condition (Condition 1) and with one expression (Expression 1). Set Expression 1 to Account Details such that Persistent User is Equal to FALSE.
Click Next.
In the Rule Actions page:
Review the rule settings in the Summary page. Then, click Save and Finish.
Once created, a rule is in Work in Progress status until approved by an administrator.
Click Status and Approve Status, then click Approve to set rule to Production status.
You can use these steps to create each of the rules in the following sections.
2.8.2. Create Rule for Persistent User Enrollment¶
Persistent users are those that will be added to the user table.
Table 2‑1 Persistent User Enrollment
Rule Name | User Enrollment Persistent –Adapter |
---|---|
Event Type | Create User, Enroll |
Rule Order | 2 |
Rule Condition | IF (Account Details > Persistent User Equal to TRUE) |
Rule Action | Allow |
Authentication Method | |
Create Case | No |
2.8.3. Create Rule for User Updates¶
Once users are created, a rule is applied to allow persistent users to update their information.
Table 2‑2 User Update
Rule Name | User Update |
---|---|
Event Type | User Update |
Rule Order | 3 |
Rule Condition | IF (Account Details > Persistent User Equal to TRUE) |
Rule Action | Allow |
Authentication Method | |
Create Case | No |
2.8.4. Create Rule for Challenge SMS¶
In this build, large transactions require users to respond to an out-of-band SMS challenge during authentication. When transactions meet the prerequisite, a random code will be sent to the user’s SMS-enabled device that must be entered to confirm the transaction.
Table 2‑3 Out-of-Band SMS
Rule Name | Challenge SMS for Payment |
---|---|
Event Type | Challenge |
Rule Order | 4 |
Rule Condition | IF (Transaction Details > Transaction Amount is BETWEEN 5000 and 10000) |
Rule Action | Allow |
Authentication Method |
|
Create Case | When Authentication Succeeds |
2.8.5. Increase SMS Token Length¶
The default token length for out-of-band SMS is currently set to four digits. Access the Administration tab on the Back Office application. Under Components, select Authentication Methods and scroll down to the Out-of-Band SMS section. Adjust the token length by changing the value of SMS - OTP Token Length to six.
Figure 2‑1 Out-of-Band Token Length
2.8.6. Create Policy for Session Sign-In¶
The following rules create different sign-in scenarios for users based on an RSA-generated risk score at the time of login. RSA AA uses a risk engine to give users a risk score to determine a level of trust at the time of access. See the tables in Section 2.8.8 for the session sign-in parameters for each risk level. Before the session sign-in rules are created, lists need to be created to group users together. This build will group users into four categories based on risk level (low, medium, high, and critical).
2.8.7. Create Lists for Session Sign-In¶
- Log in to the Back Office application.
- Go to Policy Management and select Manage Lists.
- Set List Name to Low Risk Users, List Type to User ID, and Status to Enabled.
- Under List Content, select Add Value and set the Value to demolowrisk and Organization to default.
- Click Add Value.
- Click Save.
Repeat these steps to create a list for Medium, High, and Critical risk users.
Figure 2‑2 Successful List Created
2.8.8. Create Rules for Session Sign-In¶
Repeat the steps as in Section 2.8.1 to create the session sign-in rules for different user groups.
Table 2‑4 Session Sign-In – Low Risk
Rule Name | Session Sign In – Low Risk |
---|---|
Event Type | Session Sign-in |
Rule Order | 5 |
Rule Condition | IF (Account Details > User ID within Low Risk Users) |
Rule Action | Allow |
Authentication Method | |
Create Case | No |
Table 2‑5 Session Sign-In – Medium Risk
Rule Name | Session Sign In – Medium Risk |
---|---|
Event Type | Session Sign-in |
Rule Order | 6 |
Rule Condition | IF (Account Details > User ID Within Medium Risk Users) |
Rule Action | Allow |
Authentication Method |
|
Create Case | When Authentication Fails |
Table 2‑6 Session Sign-In – High Risk
Rule Name | Session Sign In – High Risk |
---|---|
Event Type | Session Sign-in |
Rule Order | 7 |
Rule Condition | IF (Account Details > User ID Within High Risk Users) |
Rule Action | Challenge |
Authentication Method |
|
Create Case | When Authentication Fails |
Table 2‑7 Session Sign-In – Critical Risk
Rule Name | Session Sign In – Critical Risk |
---|---|
Event Type | Session Sign-in |
Rule Order | 8 |
Rule Condition | IF (Account Details > User ID Within Critical Risk Users) |
Rule Action | Challenge |
Authentication Method |
|
Create Case | When Authentication Fails |
2.8.9. Create Rule to Allow Forced Sign-In for Payment¶
The rules for session sign-in in the preceding sections were based predefined facts built within RSA AA. This build requires a rule that uses additional facts that are not within the build. Fortunately, new facts can be created within the Back Office application. Once custom facts are created, they can be used to build further rules.
2.8.10. Create Custom Fact¶
Log in to the Back Office application.
Go to Policy Management and select Manage Custom Facts.
Select New and set the Field Name to Force Workflow, Field Type to String, and Status to Enabled.
Click Save.
Create a new rule using this custom fact that allows payment if this fact is met. Use the settings in the following table.
Table 2‑8 Force Allow
Rule Name | Force Allow |
---|---|
Event Type | Payment, Session Sign-in |
Rule Order | 9 |
Rule Condition | IF (Custom Fact > Force Workflow Equal to Allow) |
Rule Action | Allow |
Authentication Method | |
Create Case | No |
2.9. Install and Configure PingFederate-RP¶
The PingFederate installation in this section is for the Federation Server at the RP. This is the only component at the RP in this section. Even though the goal of this section is to set up the federation for the IdP, the basic configuration of the PingFederate-RP in this section is necessary to produce metadata that is exchanged with the IdP. A complete configuration of the PingFederate-RP will be performed in Section 3 of this guide.
Log on to the RP’s server that will host the PingFederate service, and follow the instructions at the link below to install PingFederate and run it as a Windows service.
Follow these steps to perform a basic configuration of the PingFederate-RP and export the metadata.
Launch your browser and navigate to the PingFederate app URL: https://<DNS_NAME>:9999/pingfederate/app. Replace DNS_NAME with the fully qualified name of the RP’s PingFederate server (e.g., https://rp.abac.test:9999/pingfederate/app).
Log on to the PingFederate application using the credentials you configured in the previous installation section.
On the Main Menu under System Settings, click Server Settings.
Click the Roles and Protocols tab.
Select Enable Identity Provider (IdP) role and support the following.
Select SAML 2.0.
Select WS-Federation.
Select Enable Service Provider (SP) role and support the following.
Select the SAML 2.0.
Click Next.
On the Federation Info screen, enter the Base URL and SAML 2.0 Entity ID using the format https://<DNS_NAME>:9031 (e.g., https://rp.abac.test:9031).
Enter the WS-Federation Realm using the format urn:<DNS_NAME> (e.g., urn:rp.abac.test).
Note: Keep a copy of the urn, because it will be used later to configure the WS-Federation relationship with SharePoint.
Click Save.
On the Main Menu under Administrative Functions, click Metadata Export.
On the Metadata Role screen, select I am the Service Provider (SP).
Click Next.
On the Metadata Mode screen, select Select information to include in metadata manually.
Click Next.
On the Protocol screen, make sure that SAML 2.0 is listed.
Click Next.
On the Attribute Contract screen, click Next.
On the Signing Key screen, select the certificate that will be used to sign communications with the IdP.
Click Next.
On the Metadata Signing screen, if you plan to sign the metadata file that will be exported, select the certificate that will be used to sign the file.
Click Next.
On the XML Encryption Certificate screen, select the certificate that the Identity Provider will use to encrypt XML messages.
Click Next.
Click Export.
This will create an export file that contains the metadata of the RP, which you can download using the browser. This file will be used later in the section, when configuring the PingFederate-IDP.
2.10. Install PingFederate-IdP¶
This PingFederate installation in this section is for the PingFederate-IdP.
Log on to the server that will host the PingFederate service for the IdP, and follow the instructions at the link below to install PingFederate and run it as a Windows service.
https://documentation.pingidentity.com/display/PF73/Installation
2.11. Install the SCE Plug-in for the PingFederate-IdP¶
The SCE Plug-in integrates the features provided by RSA AA with PingFederate-IdP by providing a customizable user interface when RSA AA is accessed. New users will be enrolled into RSA’s enhanced security features and be prompted to provide information such as security questions, a phone number, email address, and an SMS-enabled device. Follow the instructions below to install the SCE Plug-in adapter for the IdP. The variable <PF-install> used in the instructions corresponds to the PingFederate installation path. In this build, the PingFederate installation path was c:\pingfederate-7.3.0.
Log on to the server that hosts the PingFederate service for the Identity provider.
Download the SCE Plug-in adapter jar file (e.g.,
sce-adapters-pingfederate-aa.1.1.jar
) to the local PingFederate server.Copy the jar file to <PF-install>/server/default/deploy
From the adapter
dist/conf/template
folder, copy all .html files to<PF-install>/server/default/conf/template.
From the adapter
dist/conf/template/assets
folder, copy the aa folder to<PF-install>/server/default/conf/template/assets
From the adapter
dist/data/adapter-config
folder, copy the aa folder to<PF-install>/server/default/data/adapter-config
From the adapter
dist/lib
folder, copy all .jar files to<PF-install>/server/default/lib
2.12. Install the Situational Context Connector for the PingFederate-IdP¶
The Situational Context Connector and a Session Validator must be installed. In this build, both are installed on the PingFederate-IdP Server.
2.12.1. Install Situational Context Connector¶
Log on to the server that hosts the PingFederate service for the Identity provider.
Download the Situational Context Connector integration zip file (e.g.,
Situational_Context_Connector_v21.zip
) to the local PingFederate server.Stop the PingFederate service if it is running.
Unzip the integration kit distribution file (
Situational_Context_Connector_v21.zip
) and copy the adapter file,pf.plugins.ise-idp-adapter.jar
, from the /dist to the PingFederate “deploy” folder:<PF_install>\pingfederate\server\default\deploy
Create a new sub-directory under the PingFederate \deploy folder called “portal.”
<PF_install>\pingfederate\server\default\deploy\portal\
Create a new sub-directory under the new \portal\ directory called “gateway.”
<PF_install>\pingfederate\server\default\deploy\portal\gateway\
Copy the “index.jsp” from the Adapter .zip /dist folder to
<PF_install>\pingfederate\server\default\deploy\portal\gateway\
Edit the sessionIdCookie.setDomain parameter in the
index.jsp
file to specify the cookie domain of your PingFederate server (Note: valid cookie domains must contain a minimum of two “dots.” For example “.company.com.”Start or restart the PingFederate server.
2.12.2. Install Situational Session Validator¶
On the same PingFederate-IdP server, unpack the contents of the
Situational_SessionValidator.zip
file found in the Context Connector integration kit zip file (Situational_Context_Connector_v21.zip
).Navigate to the folder where you unpacked the Situational Session Validator and locate the
redirector.properties
file.Edit the values in the
redirector.properties
file according to your environment.Start the session validator by running the runme script, runme.bat. Afterward, you will see a Command Prompt window pop up running the script.
2.13. Configure PingFederate-IdP¶
Follow the instructions in the subsections below to configure PingFederate as the Federation Server for the IdP.
Launch your browser and go to https://<DNS_NAME>:9999/pingfederate/app.
Replace DNS_NAME with the fully qualified name of the IdP’s PingFederate server (e.g., https://idp.abac.test:9999/pingfederate/app).
Log on to the PingFederate app using the credentials you configured during installation.
2.13.1. Configure SAML Protocol¶
On the Main Menu under System Settings, click Server Settings.
Click the Roles and Protocols tab. Select Enable Identity Provider (IdP) role and support the following.
Select SAML 2.0.
Click Save.
2.13.2. Create Data Store for Microsoft AD¶
On the Main Menu under System Settings, click Data Stores.
Select LDAP.
Click Next.
Enter the Hostname where the Microsoft AD is hosted (e.g., activedirectory.abac.test).
For the LDAP Type, select Active Directory.
Enter the User DN created in the earlier section named Create the LDAP User for Federated Authentication (e.g., CN=LDAP User, CN=Users,DC=ABAC,DC=Test).
Enter the password associated with the LDAP User DN. Select the option to use LDAPS.
Click Next. Then, click Save on the Summary screen.
2.13.3. Create Credential Validator for Microsoft AD¶
On the Main Menu under Authentication, click Password Credential Validators.
Click Create New Instance.
Enter a unique Instance Name you would like to use to refer to this configuration (e.g., AD username password).
Enter a unique Instance Id (typically the same as the Instance Name) without any spaces.
For Type, select LDAP Username Password Credential Validator.
Click Next.
For the LDAP DATASTORE, select the Active Directory data store you created earlier (e.g., activedirectory.abac.test).
Enter the SEARCH BASE (location in the directory where the LDAP search begins) for your Microsoft AD LDAP directory (e.g., DC=ABAC,DC=TEST).
Enter the SEARCH FILTER (e.g., sAMAccountName=${username}. The SEARCH FILTER allows Ping to search the LDAP directory, looking for a match where the attribute named sAMAccountName matches the username value passed from the PingIdentity server.
Click Next.
You should see two attributes listed under CORE CONTRACT, DN, and username.
Click Next.
You should see a summary page.
Click Done.
You should see a list of the credential validator instances, including the newly added validator (e.g., AD username password).
Click Save to complete configuration of the credential validator.
2.13.4. Create IdP Adapter for Authentication with Microsoft AD via Web Browser Form¶
The IdP Adapter created in this section is the logical component PingFederate uses to authenticate a user with Microsoft AD via a web browser login page.
On the Main Menu under Application Integration Settings, click Adapters.
Click Create New Instance.
In Instance Name, enter a unique name for the instance. The name will be used to refer to this configuration (e.g., AD HTML forms).
Enter a unique Instance Id (typically the same as the instance name) without any spaces. For Type, select HTML Form IdP Adapter.
Click Next.
Under PASSWORD CREDENTIAL VALIDATOR INSTANCE, click on the Add a new row to Credential Validator’s hyperlink. This will add a new selection box under the PASSWORD CREDENTIAL VALIDATOR INSTANCE with the value of “—Select One—“ in it. In that new box, select the credential validator for Microsoft AD that was created in an earlier section (e.g., AD username password).
Under PASSWORD CREDENTIAL VALIDATOR INSTANCE, click the Update hyperlink on the right side of the page. This will cause the selection box to turn grey.
Click Next. Then, click Next again to bypass the Extended Contract screen.
On the Adapter Attributes screen, select the PSEUDONYM check box in the username row.
Click Next. On the Summary screen, click Done.
- Click Save to complete configuration of the new adapter.
2.13.5. Create IdP Adapter for Two-Factor Authentication with RSA AA¶
The IdP Adapter created in this section is the logical component PingFederate uses to authenticate a user with RSA AA using a second factor.
On the Main Menu under Application Integration Settings, click Adapters.
On the Manage IdP Adapters screen, click Create New Instance.
On the Type screen, enter an Instance Name and Instance ID.
Set the following settings on the Adapter Type page before clicking Next:
On the IdP Adapter configuration page, click Show Advanced Fields and input the following parameters while leaving the rest as default, before clicking Next:
On the Extended Contract screen, type transactionid (all lowercase). Then, click Add. By default, username should already be listed under Core Contract.
Click Next.
On the Authentication Context screen, select SecureRemotePassword as the fixed value for authentication. This value will be included in the SAML assertion. Click Next.
On the Adapter Attributes screen, select username as the Pseudonym. Click Next.
On the Summary screen, verify that the information is correct and click Done.
On the Manager IdP Adapter Instances screen, click Save to complete the Adapter configuration.
2.13.6. Create Composite IdP Adapter Integrating Microsoft AD and RSA AA¶
The IdP Adapter created in this section is a composite adapter that integrates the two previously created adapters for Microsoft AD and RSA AA. When a user is directed to the PingFederate IdP server, the user will see a web form where they can enter their Microsoft AD credentials. Following authentication with Microsoft AD, PingFederate will initiate the second factor authentication with an SCE Plug-in. The SCE Plug-in will then present the user with a request for the second factor.
On the Main menu under Application Integration Settings, click Adapters.
On the Manage IdP Adapters screen, click Create New Instance.
Enter a unique Instance Name you would like to use to refer to this configuration (e.g., RSA Multifactor).
Enter a unique Instance Id (typically the same as the Instance Name) without any spaces.
For Type, select Composite Adapter.
Click Next.
On the IdP Adapter screen, under ADAPTER INSTANCE, click on the Add a new row to ‘Adapters’s hyperlink. This will add a new selection box under the ADAPTER INSTANCE with the value of “—Select One—“ into the box. In that new box, select the adapter instance for HTML forms with Microsoft AD that was created in an earlier section (e.g., AD HTML forms).
Under ADAPTER INSTANCE, click the Update hyperlink on the right side of the page. This will cause the selection box to turn grey.
Repeat the previous steps to add another row to Adapters using the hyperlink on the right side of the page. This time, select the AdaptiveAuthentication adapter in the selection box. When complete, the IdP Adapter screen will look similar to the screenshot below, with two adapters configured under ADAPTER INSTANCE.
Under TARGET ADAPTER, click on the Add a new row to ‘Input User Id Mapping’ hyperlink. This will add a new selection box under the TARGET ADAPTER with the value of “—Select One—“ in the box.
In that new box, select the adapter instance for the RSA authentication that was created in an earlier section (e.g., AdaptiveAuthentication).
In the new USER ID SELECTION box, select username.
Under TARGET ADAPTER, click the Update hyperlink on the right side of the page. This will cause the selection box to turn grey.
Click Next.
On the Extended Contract screen, enter the value username in the EXTEND THE CONTRACT field.
Click Add. Enter the value transactionid (all lowercase) in the EXTEND THE CONTRACT field.
Click Add. Then, click Next.
On the Adapter Attributes screen, in the username row, select the PSEUDONYM column.
Click Next. On the Summary screen, click Done.
Click Save to complete configuration of the new composite adapter.
2.13.7. Create IdP Adapter for the Situational Context Connector and ISE Authentication¶
The IdP Adapter created in this section is the logical component PingFederate uses to obtain connection (device and network) information obtained from ISE Authentication via the Situational Context Connector. These device and network attributes serve as environmental attributes in this build.
On the Main menu under Application Integration Settings, click Adapters.
On the Manage IdP Adapters screen, click Create New Instance.
On the Type screen, enter an Instance Name and Instance ID.
For Type, select Context Connector v2.0, and click Next.
Enter configuration information and click Next.
On the Extended Contract screen, you can configure additional attributes for the adapter. We retained the defaults and clicked Next.
On the Adapter Attributes screen, in the row for ise_username, check the box in the Pseudonym column. Click Next. (Note: if you added other attributes in Step #6, you could check the box under Pseudonym for those as well.)
On the Summary screen, review the configuration and scroll down to click Done.
On the Manage IdP Adapter Instances screen, click Save.
2.13.8. Configure the Federation Connection to the Relying Party¶
This PingFederate SP Connection at the PingFederate-IdP will configure the SAML exchange with a server in the RP’s environment. This connection will also enable a user to authenticate using the composite adapter created in the previous section.
On the Main Menu under SP CONNECTIONS, click Create New.
On the Connection Type screen, make sure Browser SSO Profiles is selected.
Click Next. On the Connection Options screen, make sure Browser SSO is selected.
Click Next.
On the Import Metadata screen, click Browse and select the metadata file that you exported from the RP’s PingFederate server.
Click Next.
On the Metadata Summary screen, click Next.
On the General Info screen, you should see some configuration information (e.g., Base URL) about the RP that was taken from the metadata file that you selected earlier.
Click Next. On the Browser SSO screen, click Configure Browser SSO.
Select IdP-Initiated SSO and SP-Initiated SSO. Then, click Next.
On the Assertion Lifetime screen, click Next.
On the Assertion Creation screen, click Configure Assertion Creation. This will bring up a sequence of sub-screens, starting with the Identity Mapping screen.
On the Identity Mapping screen, select the Standard option.
Click Next. This will bring up the Attribute Contract screen.
Click Next.
On the Authentication Source Mapping screen, click Map New Adapter Instance. This will launch a sequence of sub-screens, beginning with the Adapter Instance screen.
On the Adapter Instance screen, select the composite adapter created in an earlier section (e.g., RSA Multifactor).
Click Next. On the Assertion Mapping screen, select Use only the Adapter Contract values in the SAML assertion.
Click Next.
On the Attribute Contract Fulfillment screen, for SAML_SUBJECT, select Adapter for the SOURCE field and username for the VALUE field.
Click Next.
Click Next.
Click Done. This will bring you back to the Authentication Source Mapping screen, and you should see the composite adapter (e.g., RSA Multifactor) listed.
Click Next.
On the Summary screen, click Done. This will take you back to the Configure Assertion Creation screen.
Click Next.
On the Protocol Settings screen, click Configure Protocol Settings. This will launch a sequence of sub-screens, beginning with the Assertion Consumer Service URL screen.
On the Assertion Consumer Service URL screen, make sure that the BINDING field is set to POST and the ENDPOINT URL field is set to /sp/ACS.saml2.
Click Next.
On the Allowable SAML Bindings screen, select POST and Redirect.
Click Next.
On the Signature Policy screen, select Require AuthN requests to be signed when received via the POST or Redirect bindings.
Click Next. On the Encryption Policy screen, select The entire assertion.
Click Next.
On the Summary screen, click Done.
This will take you back to the Protocol Settings screen.
Click Next.
On the Summary screen, click Done.
This will take you back to the Browser SSO screen.
Click Next.
On the Credentials screen, click Configure Credentials.
For the Signing Certificate field, select the certificate to be used to sign the SAML message.
Select the certificate that you configured for the server in an earlier section.
Select the Signing Algorithm for your environment (e.g., RSA SHA256).
Click Next.
Click Next.
On the Select XML Encryption Certificate screen, select the Block Encryption Algorithm (e.g., AES-128), and the Key Transport Algorithm (e.g., RSA-OAEP).
For the selection box above the Manage Certificates button, select the RP’s public key certificate to be used to encrypt the message content.
Click Next.
On the Summary screen, click Done. This will take you back to the Credentials screen.
Click Next.
On the Activation & Summary screen, select Active for the Connection Status field.
Copy the Identity Provider’s SSO Application Endpoint URL (e.g., https://idp.abac.test:9031/idp/startSSO.ping?PartnerSpId=https://rp.abac.test:9031) to the clipboard and save it to a text file, because this URL will be used in the Functional Test section.
Click Done. This will take you to a screen that lists the connections for the server, including the new connection you just created. Click Save to complete the configuration.
2.13.9. Configure ISE Composite Adapter¶
From the Main page, click on Adapters.
Click Create New Instance.
In the Instance Name field, enter ISE-RSA Composite Adapter.
In the Instance ID field, give the same name without spaces.
In the Type field, choose Composite Adapter.
Click Next.
Click Add a new row to ‘Adapters’.
Choose CiscoISE.
Click Update.
Click Add a new row to ‘Adapters’.
Choose RSA Multifactor.
Click Update.
Click Next.
Add the attributes from both the ISE and RSA adapters.
Click Next.
Check the Pseudonym box next to username.
Click Next.
Click Done.
Click Save.
2.13.10. Applying the Composite Adapter¶
From the main page, click on rp.abac.test under SP Connections.
Scroll down and click on Authentication Source Mapping.
Click on Map New Adapter Instance.
In the Adapter Instance box, select the composite adapter.
Click Next.
Select the top radio button labeled Retrieve additional attributes from multiple data stores using one mapping.
Click Next.
Click Add Attribute Source.
Enter ActiveDirectory for Source Id and Description.
Select activedirectory.abac.test in the Active Data Store drop-down.
Click Next.
In the BaseDN field, enter DC=ABAC,DC=TEST.
Add all of the attributes from the LDAP Directory Search.
Click Next.
In the Filter field, enter sAMAccountName=${ise_user_name}.
Click Next.
Click Save.
Click on Attribute Sources & Data Store.
Click on Add Attribute Source.
Enter RSAAA for Source Id and Description.
Select JDBC:sqlserver in the Active Data Store drop-down.
Click Next.
Select dbo in the Scheme drop-down.
Select EVENT_LOG in the Table drop-down.
Add each of the columns from the table.
Click Next.
In the Where field, enter USER_ID=${transactionid}.
Click Next.
Click Done.
Click Next.
Map all the attributes as shown in the screenshot below.
Click Next.
Click Next.
Click Save.
Back at the main page, click on rp.abac.test under SP Connections.
Scroll down and click on Database Filter.
In the Where field, enter EVENT_ID=${transactionid}.
Click Save.
2.14. Certificates¶
Once you have installed the various products for this ABAC build, you can replace the default self-signed certificates with certificates signed by a Certificate Authority (CA). For our build, we used Symantec’s Managed PKI Service to sign our certificates using a local CA. Certificates were used to support various exchanges that require encryption, such as digital signature, SAML message encryption, and encryption of TLS communications.
Although the detailed instructions of configuring certificates signed by a CA vary by vendor product, the general process is described below. For each certificate, you perform the following high-level steps:
- Using the vendor product (e.g., PingFederate, SharePoint), generate a certificate signing request on the server where you want to use the certificate. Save the signing request to a file.
- Submit an enrollment request to your CA. You will need to provide the signing request that was generated in Step 1. This step is typically where you provide information such as the name of the server you intend to use the certificate on (e.g., “idp.abac.test”).
- A representative at the CA will examine the enrollment request and approve it. The representative will issue a certificate response signed with the CA’s key. You can download the signed response. If you are using a CA that is locally managed by your organization, you will also need to download the public key of the CA, because you will need to add this the Trusted Certificate Authorities on each server and client that will be using the certificates.
- Go back to the vendor product where you created the certificate signing request. If you are using a local CA, you will first need to add the Certificate Authority’s public key to the list of Trusted Certificate Authorities.
- Import the certificate file for your server that was signed by the CA.
2.14.1. Certificate Configuration PingFederate¶
In the PingFederate app, on the main menu, under Certificate Management, click Trusted CAs to import the public key of your local CA. If you are using a well-known, external, major CA and that authority’s public key is already available in cacerts in the Java runtime, it is not necessary to import the same certificate into the PingFederate Trusted CA store.
For SSL Server certificates, follow the instructions in the link below. The applicable sections are “To create a new certificate,” “To create a certificate-authority signing request,” and “To import a certificate authority response.” Once you have imported a signed certificate response, you will need to active the certificate on the PingFederate runtime server instance on which your applications are running. Follow the instructions in the section “To activate a certificate.”
For digital signatures and performing encryption / decryption, follow the instructions in the link below. The applicable sections are the same as for SSL Server certificates.
2.15. Functional Test of All Configurations for Section 2¶
The instructions in this section will help perform an integrated test all of the configurations in Section 2. Using the browser and PingFederate, a user will log on and validate that the federated authentication to Microsoft AD and RSA AA are properly configured.
The test for this section was performed using the Mozilla Firefox browser and the “SAML tracer” add-on, which enables examination of HTTPS POST and SAML messages.
Install the Firefox SAML tracer add-on from the link below.
Launch your Firebox browser and select SAML tracer from the Tools menu.
Minimize the SAML tracer window. The SAML tracer will automatically record the details of the HTTPS messages in the background.
Go back to the main browser window and navigate to the Identity Provider’s SSO Application Endpoint URL identified in the previous section (e.g., https://idp.abac.test:9031/idp/startSSO.ping?PartnerSpId=https://rp.abac.test:9031).
Enter the Username of the account created in Microsoft AD earlier in this section (e.g., lsmith).
Enter an invalid password for the account. Do not enter the correct password.
Click Sign On.
Close the existing browser and launch a new browser.
Navigate to the Identity Provider’s SSO Application Endpoint URL again.
Enter the user name of the account created earlier in this section (e.g., lsmith). Then, enter the correct password.
Click Sign On.
Expected Result: You should see the two-factor RSA AA plug-in screen. This screen prompts you to enter the SMS text validation code received by your mobile phone.
Enter the SMS validation code received on your mobile phone and proceed. This will initiate a communication with the RSA AA server to validate the code that was entered.
Expected Result: The browser should redirect to the RP’s Federation Server (e.g., rp.abac.test), and you should see an error message similar to the screenshot below.
Go back to the SAML tracer window. Scroll to the bottom of the list of messages in the upper pane. Click on the last message (e.g., POST https://rp.abac.test:9031/sp/ACS.saml2) that has a SAML icon associated with it. This will show the details of the POST message.
Expected Result: In the details page at the bottom, on the http tab, you should see that the browser sent a POST message to the RP’s PingFederate server rp.abac.test. The HTTP response status code (identified on the line that begins with HTTP) should be a 500 Server Error.
Click on the SAML tab.
Expected Result: You should see the details of the SAML message, including the Issuer. The Issuer should be the IdP’s Federation server, idp.abac.test.
3. Setting up Federated Authentication Between the Relying Party and the Identity Provider¶
3.1. Introduction¶
In the previous section of this How-To Guide we demonstrated how to set up federated, SAML-based authentication at the identity provider (IdP). Before continuing with this section, it is necessary to have a working federation service that will represent the identity provider and can receive and issue SAML 2.0 request and responses. For instructions on how to set this up using Ping Federate, please refer to Section 2 of this guide.
In order to federate identities and attribute information between organizations a federation service must exist at both the identity provider and the relying party (RP). A trust relationship between these two services must then be instantiated to allow for identity and attribute requests and responses. In this section we configure an instance of PingFederate (henceforth called PingFederate-RP) at the relying party to act as a federation service and to redirect users to the PingFederate-IdP via a SAML request. We then configure the trust relationship and federated authentication between the PingFederate-RP and the PingFederate-IdP, allowing the SAML request to be processed by the identity provider and the subsequent return of a SAML response containing identity and attribute assertions.
If you follow the instructions in this How-To Guide section, you will be able to perform a functional test to verify the successful completion of the steps for installing, configuring, and integrating the components.
3.2. Components¶
Federated authentication between the relying party and the identity provider involves the following distinct components:
- PingFederate-IdP: A federation system or trust broker for the identity provider
- PingFederate-RP: Serves as the trust broker for SharePoint
3.2.1. PingFederate-IdP¶
Ping Identity PingFederate-IdP serves as a federation system or trust broker for the IdP. PingFederate-IdP provides initial user authentication and retrieval of user attributes to satisfy SAML requests from the RP. Once the user has been authenticated, PingFederate-IdP queries subject attributes from AD and environmental attributes from the RSA AA event log. PingFederate-IdP takes the name:value pairs of both the subject and environmental attributes and stores them in a SAML 2.0 token to be sent to the RP.
PingFederate Usage Notes:
When using the PingFederate application to perform an administrative configuration, there is usually a sequence of screens that require user entry, ending with a summary page. Once you click Done on the summary page, you must also click Save on the following page to save the configurations. If you forget to click Save, you may inadvertently lose changes to the configuration.
In the PingFederate application and associated documentation, the relying party is referred to as the “Service Provider.”
When using the PingFederate application to perform configuration, refer to the title of the tab with a small star icon to its left, to identify the item you are currently configuring. For example, if you navigated to the following screen, you would be on the IdP Adapter screen.
3.2.2. PingFederate-RP¶
Ping Identity PingFederate-RP serves as the trust broker for SharePoint. When the user requires authentication, PingFederate-RP redirects the user to the IdP via a SAML request to get the necessary assertions. Once authenticated, PingFederate-RP arranges for the browser’s HTTPS content to have the proper information in proper format for acceptance at the target resource (SharePoint).
3.3. Export Metadata from the Identity Provider¶
Follow the instructions in this section to export a metadata file from the PingFederate-IdP.
Logon to the server that hosts the PingFederate service for the Identity Provider.
Launch your browser and navigate to the PingFederate application URL: https://<DNS_NAME>:9999/pingfederate/app.
Replace DNS_NAME with the fully qualified name of the Identity Provider’s PingFederate server (e.g., https://idp.abac.test:9999/pingfederate/app). Logon to the PingFederate application using the credentials you configured during installation.
On the Main Menu under Administrative Functions, click Metadata Export.
On the Metadata Mode screen, select Use a connection for metadata generation.
Click Next. On the Connection Metadata screen, select the connection to the relying party that you configured in the previous section (e.g., https://rp.abac.test:9031). This should automatically populate some of the fields on the screen with information from the connection.
Click Next. On the Metadata Signing screen, if you plan to sign the metadata file that will be exported, select the certificate that will be use to sign the file.
Click Next. On the Export & Summary screen, you should see a summary of the options that were selected.
Click Export. This will create an export file that contains the metadata of the identity provider that you can download using the browser.
Copy the metatdata file to the server that hosts the PingFederate service for the relying party.
3.4. Configure PingFederate-RP Connection to the PingFederate-IdP¶
Follow the instructions in this section to configure a PingFederate connection from the relying party to the identity provider.
Logon to the server that hosts the PingFederate service for the relying party.
Launch your browser and go to: https://<DNS_NAME>:9999/pingfederate/app.
Replace DNS_NAME with the fully qualified name of the relying party’s PingFederate server (e.g., https://rp.abac.test:9999/pingfederate/app). Logon to the PingFederate application using the credentials you configured in the previous installation section.
On the Main Menu under IDP CONNECTIONS, click Create New.
On the Connection Type screen, select Browser SSO Profiles.
Click Next.
On the Connection Options screen, make sure Browser SSO is selected.
Click Next.
On the Import Metadata screen, click Browse and select the metadata file that you exported from the Identity Provider’s PingFederate server.
Click Next.
On the Metadata Summary screen, click Next. On the General Info screen, you should see some configuration information (e.g., Base URL) about the identity provider that was taken from the metadata file that you selected.
Click Next.
On the Browser SSO screen, click Configure Browser SSO.
On the SAML Profiles screen, select IdP-Initiated SSO and SP-Initiated SSO.
Click Next.
On the User-Session Creation screen, click Configure User-Session Creation.
On the Identity Mapping screen, click Next.
On the Attribute Contract screen, click Next.
On the Target Session Mapping screen, click Map New Connection Contract Mapping.
On the Connection Mapping Contract screen, click Manage Connection Mapping Contracts.
On the Manage Contracts screen, click Create New Contract.
On the Contract Info screen, enter the Contract Name (e.g., SharePoint 2013).
Click Next.
Click Next.
On the Summary screen, click Done.
On the Manage Contracts screen, you should see the new contract listed. Click Save.
On the Connection Mapping Contract screen, for the CONNECTION MAPPING CONTRACT field select the name of the new contract that was created (e.g., SharePoint 2013).
Click Next. On the Attribute Retrieval screen, select Use only the attributes available in the SSO Assertion.
Click Next. On the Contract Fulfillment screen, for the SOURCE field select Assertion. For the VALUE field, select SAML_SUBJECT.
Click Next.
On the Issuance Criteria screen, click Next.
On the Summary screen, click Done.
On the Target Session Mapping screen, you should see new contract (e.g., SharePoint 2013) listed under the CONNECTION MAPPING CONTRACT NAME field.
Click Next.
Click Done.
On the User-Session Creation screen, click Next.
On the Protocol Settings screen, click Configure Protocol Settings. This will bring up a sequence of sub-screens.
On the SSO Service URLs screen, click Next.
On the Allowable SAML Bindings screen, select POST and select Redirect.
Click Next.
On the Default Target URL screen, click Next.
On the Signature Policy screen, make sure that the following are selected:
- Specify additional signature requirements and
- Sign AuthN requests sent over POST and Redirect bindings
Click Next. On the Encryption Policy screen, select
- Allow encrypted SAML Assertions and SLO messages and
- The entire assertion
Click Next.
On the Summary screen, click Done.
On the Protocol Settings screen, click Next.
On the Summary screen, click Done.
On the Browser SSO screen, click Next.
On the Credentials screen, click Configure Credentials.
On the Digital Signature Settings screen, select
Click Next.
On the Signature Verification Settings screen, click Manage Signature Verification Settings.
On the Trust Model screen, click Next.
On the Signature Verification Certificate screen, select the certificate to verify digital signatures.
Click Next.
On the Summary screen, click Done.
On the Signature Verification Settings screen, click Next.
On the Select XML Decryption Key screen, select the certificate associated with the private key that will decrypt messages from the identity provider.
Click Next.
On the Summary screen, click Done.
On the Credentials screen, click Next.
On the Activation and Summary screen, select Active for the
- Copy the relying party’s SSO Application Endpoint URL (e.g., https://rp.abac.test:9031/sp/startSSO.ping?PartnerIdpId=https://idp.abac.test:9031) to the clipboard and save it to a text file, because this URL will be used in the Functional Test section.
- Click Save to save the configuration.
3.5. Functional Test of All Configurations for Section 3¶
This section provides instructions to perform an integrated test all of the configurations in Section 3.
Using the browser and PingFederate, a user will logon at the identity provider, and then get redirected to the relying party.
Note: This test is similar to the test in Section 2, except this time the relying party has a destination endpoint connection that was configured in Section 3, so the response code from the relying party’s Federation server (e.g., rp.abac.test), should be an HTTP 200 status code.
Launch your browser and navigate to the relying party’s SSO Application Endpoint URL identified in the previous section (e.g., https://rp.abac.test:9031/sp/startSSO.ping?PartnerIdpId=https://idp.abac.test:9031).
Launch the SAML tracer as in Section 2 and minimize the tracer window.
Enter the Username and Password of the account created in Section 2 (e.g., “lsmith”) and click Sign On.
When the RSA Adaptive Authentication screen comes up, enter the SMS text validation code.
Return to the SAML tracer window.
Scroll to the bottom of the list of message in the upper pane.
Click on the last message (e.g., POST https://rp.abac.test:9031/sp/ACS.saml2) that has a SAML icon associated with it. This will show the details of the POST message.
6. Attribute Exchange between the Identity Provider and Relying Party¶
6.1. Introduction¶
In previous sections of this How-To Guide, we demonstrated foundational steps to building an ABAC solution:
- configuring federated authentication at the PingFederate-IdP
- configuring the SAML exchange between the PingFederate-IdP and PingFederate-RP
- configuring the Relying Party’s SharePoint site
- configuring the federated logon at the SharePoint site
Building upon that foundation, this section describes how to:
- create custom attributes and set values for them in Microsoft AD
- configure the PingFederate-IdP to pull user and environmental attributes during authentication
- configure the PingFederate-RP to pass the user and environmental attributes to the RP’s SharePoint
- configure SharePoint to load the user and environmental attributes passed from the PingFederate-RP into the web session
If you follow the instructions in this How-To Guide section, you will be able to perform a Functional Test to verify the successful completion of the steps for installing, configuring, and integrating the components.
6.2. Create Custom User Attributes in Microsoft AD¶
Follow the instructions in this section to create custom user attributes in the Microsoft AD schema. You will add a new attribute and add it to the “user” class. Microsoft AD user accounts inherit from the “user” class; therefore, the new attribute will be available to all of the users in the domain.
6.2.1. Preparing the AD Schema for Creating New Custom Attributes¶
6.2.1.1. Backing Up Your Directory before Making Schema Changes¶
Microsoft recommends that you back up your directory before making schema changes. Choose the names of your new custom attributes carefully, because the creation of a new attribute is a permanent operation.
Log on to the server that contains the Microsoft AD schema (typically the schema is on the domain controller).
Launch a Command Prompt, using the Run as Administrator option.
Execute the following command: regsvr32 schmmgmt.dll
Click the Start button and enter mmc.exe in the search field.
Launch the mmc.exe program.
Click on the File menu. Then, click Add / Remove Snap-in.
Click on Active Directory Schema in the list of Available snap-ins on the left; then, click Add to add it to the Selected snap-ins on the right.
Click OK.
Expand the Active Directory Schema on the left.
6.2.1.2. Reviewing Existing Attributes to Avoid Redundancies when Creating New Attributes¶
Before you create a new attribute, it is important to review existing user attributes in your Active Directory Schema. Under Active Directory Schema on the left, expand the Classes folder and scroll down to click on the user class. Examine the existing set of user class attributes listed on the right. These attributes are native to Active Directory, and can be assigned to users as subject attributes. These attributes may meet existing requirements for implementing subject attribute, alleviating the need to add custom attributes to the schema. You can list the attributes in alphabetical order by clicking on the Name column.
If you wanted to create an attribute to store the user’s cell phone number, you would look through the attributes and notice that the attribute cellphone does not exist. However, there is an attribute named mobile that could be used to store a cell phone number.
Once you have identified that the creation of a new attribute is warranted, proceed with the following instructions.
6.2.1.3. Creating New Custom Attributes¶
Launch a browser window and go the Microsoft site: https://gallery.technet.microsoft.com/scriptcenter/56b78004-40d0-41cf-b95e-6e795b2e8a06
Copy the oidgen.vbs script code that is shown on the page to the clipboard.
Open Notepad and paste the script into the editor.
Save the script to a file on the desktop named oidgen.vbs.
Go back to the Active Directory schema window.
On the left pane, click on the Attributes folder.
Right-click on the Attributes folder and select Create Attribute.
Click Continue on the warning window.
Enter the name of your new attribute and select the type of attribute in the Syntax field. In the example below, the name of the new attribute is clearance and the type of attribute is Unicode String.
6.2.1.4. Generating an ID to Enter into the Unique X500 Object ID Field¶
Next, you need to generate an ID to enter into the Unique X500 Object ID field.
Go to the desktop and double-click on the oidgen.vbs script that was saved earlier. This should execute the script to generate a unique Object ID.
Enter this long Object ID into the Unique X500 Object ID field in the Active Directory Create New Attribute window.
Click OK to create the new attribute.
Scroll down the list of attributes and make sure your newly added attribute is listed there.
6.2.1.5. Adding the New Attribute to the User Class¶
Next, you need to add the new attribute to the user class.
In the left pane, expand the Classes folder. Scroll down the list of classes, right-click on the user class, and select Properties.
Click on the Attributes tab.
Click Add. Scroll down and click on the new attribute.
Click OK on the Select Schema Object window, and then click OK one more time on the user properties window. At this point, you have added the new attribute to the user class.
6.2.2. Set Values for Custom User Attributes in Microsoft AD¶
Once you have created a new custom attribute in the Active Directory user class, that new attribute will be available for all users in the domain. You will be able to set specific values for the new attribute for each distinct user. Follow the instructions in this section to set a user-specific value for a new attribute in Active Directory.
Log on to the Microsoft AD server.
Open the Active Directory Users and Computers program.
Click on the View menu and select Advanced Features.
Right-click on Saved Queries and select New > Query. Enter a name for your query (e.g., My Users).
Click on Define Query. From the Name list, select Has a value.
Click OK. Then, click OK again to create your new query.
Double-click on the specific user (e.g., Lucy Smith) that you want to modify to bring up the properties window.
Click on the Attribute Editor tab.
Scroll down and locate the new custom attribute for which you want to set a value (e.g., clearance).
Double-click on the attribute, and enter a value suitable for your organization. In this example, the clearance attribute will be set to a value of Interim for the user Lucy Smith in subsequent steps.
Click OK and then click OK again. The information is saved and the User Properties window closes.
Note: When you set an attribute value in the attribute editor and then go back to the Users query view, you have to press F5 or click the Action menu > Refresh to see the new value.
6.2.2.1. Adding New Columns to the Users Query View¶
Next you will add new columns to the Users query view to help monitor the custom attribute values for each user in the directory. By default, the Users view only shows the attribute values for Name, Type, and Description.
- In the Saved Queries folder, click on the name of the query to be modified (e.g., My Users).
- Click on the View menu and select Add/Remove Columns…
- From the list of Available columns, scroll up or down to find desired columns.
- Click on column name and click on the Add button.
- When all desired columns have been chosen, click OK.
The following screenshot shows a query view after adding custom attribute columns. The example contains new columns for the attributes User Logon Name, Company, Department, Title, Staff Level, and Clearance.
6.3. Configure PingFederate Servers to Pull User Attributes¶
6.3.1. Configure PingFederate-IdP to Pull User Attributes During Authentication¶
Follow the instructions in this section to configure the PingFederate-IdP to pull user attribute values from Microsoft AD and Cisco ISE during the authentication process. In the following example, the value for the user attribute company is extracted from Microsoft AD.
Launch your browser and go to https://<DNS_NAME>:9999/pingfederate/app.
Replace DNS_NAME with the fully qualified name of the IdP’s PingFederate server (e.g., https://idp.abac.test:9999/pingfederate/app).
Log on to the PingFederate application using the credentials you configured during installation.
On the Main Menu under SP CONNECTION, click Manage All SP.
Click on the link for the connection created in Section 3 (e.g., https://rp.abac.test:9031).
On the Activation & Summary screen, scroll down to the Assertion Creation group and click on the ATTRIBUTE CONTRACT link.
On the Attribute Contract screen, under the EXTEND THE CONTRACT column, enter the name of the attributes to be extracted from Microsoft AD, Cisco ISE, and RSA AA (e.g., company) in the empty text field.
Click Add.
Click Save to complete the configuration.
6.3.1.1. Functional Test of Pulling User Attributes During Authentication¶
The instructions in this section will help you perform a test to ensure that the Identity Provider is getting the configured attributes (e.g., company) from Active Directory and passing them in a SAML message to the RP. The Firefox SAML tracer add-on is used to examine the SAML message.
Follow the instructions in the section Temporarily Disable SAML Encryption for Testing and Troubleshooting Message Exchanges at the end of this section to disable SAML encryption. Once SAML encryption has been disabled, you can proceed with the following functional test instructions.
Launch your Firebox browser and select SAML tracer from the Tools menu. This launches an empty SAML tracer window.
Minimize the SAML tracer window.
The SAML tracer automatically records the details of the HTTPS messages in the background.
Go back to the main browser window and go to the RP’s SharePoint site (e.g., https://SharePoint.abac.test).
Select Federated Logon from Identity Provider.
In the Identity Provider’s PingFederate Sign On screen, enter the credentials for the account you are testing with (e.g., lsmith) and click Sign On.
On the RSA two-factor authentication screen, enter the validation code and proceed. The browser redirects you to the PingFederate-RP and then to the RP’s SharePoint site. You may not notice the redirection to the PingFederate-RP if it happens quickly.
Go back to the SAML tracer window. Scroll down and click on the last POST message that contains a SAML icon.
Click on the SAML tab. Scroll down the SAML message and locate the AttributeStatement node and sub nodes.
Expected Result: Ensure that the attribute you configured from Microsoft AD contains a node. In the example screenshot above, you can see that there is an Attribute node for the company attribute because of the line <saml:Attribute Name= “company”.
Expected Result: Ensure that the AttributeValue node contains the expected value for the attribute from ActiveDirectory. In the example screenshot above, you can see there is an AttributeValue node for the company attribute and the value is Conway Inc. This is correct, because in our Microsoft AD environment, the user account we tested with is lsmith (Lucy Smith), and Lucy’s company attribute in Microsoft AD is set to a value of Conway Inc.
When you complete this functional test, you must enable SAML encryption between the IdP and RP again. Follow the instructions in the section Temporarily Disable SAML Encryption for Testing and Troubleshooting Message Exchanges, subsection Enable SAML Encryption at the end of this section again to enable SAML encryption.
6.3.2. Configure PingFederate-IdP to Pull Environmental Attributes During Authentication¶
Follow the instructions in this section to configure the PingFederate-IdP to get environmental attribute values from the RSA Adaptive Authentication system during the authentication process. The environmental attributes are passed along with the user attributes in the SAML messages that is sent to the RP. In the example below, the environmental attribute ip_address will be pulled from RSA Adaptive Authentication.
RSA Adaptive Authentication stores environmental attributes about the user’s web transactions in a SQL Server database named RSA_CORE_AA. The PingFederate-IdP will be configured to query to the RSA_CORE_AA database and get the value of ip_address from the EVENT_LOG table.
Before you can configure the query for ip_address, you must first create an account for the PingFederate application in the RSA_CORE_AA database. Follow the instructions below to create the account in the SQL Server database.
Log on to the server that hosts the RSA Adaptive Authentication SQL Server database engine.
Open SQL Server Management Studio.
Expand the RSA-AA-Server folder, then the Security folder.
Right-click on Logins and select New Login.
Set the Login name (e.g., ping), under SQL Server authentication and choose a password that meets the Windows password policy.
Under Server Roles, select public.
Under Status, set permission to connect to database engine to Grant and Login to Enabled. Click OK.
6.3.2.1. Configuring a New Data Store that Connects to the RSA database¶
Next, you will configure a new Data Store that connects to the RSA_CORE_AA database on the Identity Provider’s PingFederate server. This new data store will be used in the RP Connection to query the EVENT_LOG table during the authentication process.
Follow the instructions below to create a new Data Store for the RSA_CORE_AA database.
Launch your browser and go to https://<DNS_NAME>:9999/pingfederate/app. Replace <DNS_NAME> with the fully qualified name of the IdP’s PingFederate server (e.g., https://idp.abac.test:9999/pingfederate/app).
Log on to the PingFederate application using the credentials you configured during installation.
Under Server configuration, select Data Stores.
Under Manage data stores, select Add new data store. Select Database as type of data store. Click Next.
On the database config page, set the JDBC URL to: jdbc:sqlserver://<RSA_SERVER_IP_ADDRESS>:1433;databaseName=RSA_CORE_AA
- Replace <RSA_SERVER_IP_ADDRESS > with the IP address of the server that hosts the RSA_CORE_AA database.
Set the driver class to com.microsoft.sqlserver.jdbc.SQLServerDriver
In the Username and Password fields, enter the credentials for the Ping user created in the SQL server RSA Database.
Under Validate Connection SQL, type SELECT 1=1.
Check the box to allow multi-value attributes. Click Next.
Review the settings on the summary page. Then, click Save.
6.3.2.2. Modifying the SP Connection to the RP to Add New Environmental Attribute¶
Next, you will modify the SP Connection to the RP and add a new environmental attribute, ip_address, from the RSA_CORE_AA database.
Go to the PingFederate main menu. On the Main menu under SP CONNECTION, click Manage All SP.
Click on the link for the SP connection created in Section 2 (e.g., https://rp.abac.test:9031).
On the Activation & Summary screen, scroll down to the Assertion Creation group and click on the ATTRIBUTE CONTRACT link.
On the Attribute Contract screen, under the EXTEND THE CONTRACT column, enter the name of the environmental attribute to be pulled from the RSA_CORE_AA database (e.g., ip_address) in the empty text field.
Click Add.
Click Next.
On the Authentication Source Mapping screen, click on the name of the ADAPTER INSTANCE (e.g., RSA Multifactor).
Click on the Attribute Sources & User Lookup tab.
Click Add Attribute Source.
On the Attribute Sources & User Lookup screen, enter a unique name in the Attribute Source Id field (e.g., RSAEventLog).
Enter a description (e.g., Atts from RSA).
For the Active Data Store field, select the existing Data Store that connects to the RSA_CORE_AA database.
Click Next.
On the Database Table and Columns screen, select the dbo Schema.
Select the EVENT_LOG table.
Under the Columns to return from SELECT, select the IP_ADDRESS column and click Add Attribute.
Click Next.
On the Database Filter screen, enter the text on the following line into the text field for the Where. Make sure to include the quotes.
EVENT_ID = ‘${transactionid}’
Click Next.
On the Summary screen, click Done.
On the Attribute Sources & User Lookup screen, click Done.
On the Attribute Contract Fulfillment screen, for the ip_address attribute, select the SOURCE and VALUE. For the SOURCE, select JDBC (Atts from RSA). For VALUE, select IP_ADDRESS.
Click Save to complete the configuration.
6.3.2.3. Functional Test of Pulling Environmental Attributes during Authentication¶
To test that the Identity Provider’s PingFederate server is successfully getting the environmental attributes during the authentication process, follow the instructions in the section Functional Test of Pulling User Attributes during Authentication. The only exception to those instructions is that when you examine the SAML message, you need to look for the environmental attribute that is being pulled from the RSA_CORE_AA database. See below for an example.
Once you have the message open in the SAML tracer window, scroll down the message and locate the AttributeStatement node and sub-nodes.
Expected Result: Ensure that the attribute you configured to be pulled from the RSA_CORE_AA database contains a node. In the example screenshot above, you can see that there is an Attribute node for the ip_address attribute because of the line <saml:Attribute Name=“ip_address”.
Expected Result: Ensure that the AttributeValue node contains the expected value for the attribute from the RSA_CORE_AA database. In the example screenshot above, you can see that there is an AttributeValue node for the ip_address attribute, and the value is 10.255.207.19.
6.3.3. Configure PingFederate-RP to Pull Attributes from the Identity Provider’s SAML Exchange¶
Once the PingFederate-IdP completes the authentication for a user, the IdP will send a SAML message to the PingFederate-RP. That SAML message will contain attributes.
Follow the instructions below to configure the PingFederate-RP to get attributes and their associated values from the SAML message exchange with the IdP. In the example below, the attribute being configured at the RP is the company attribute.
Launch your browser and go to https://<DNS_NAME>:9999/pingfederate/app. Replace DNS_NAME with the fully qualified name of the Relying Party’s PingFederate server (e.g., https://rp.abac.test:9999/pingfederate/app). Log on to the PingFederate application using the credentials you configured during installation.
On the main menu, under IDP CONNECTIONS, click on the connection that was configured to the IdP in Section 3 (e.g., https://idp.abac.test:9031).
On the Activation & Summary screen, scroll down to the User-Session Creation group and click on the ATTRIBUTE CONTRACT link.
On the Attribute Contract screen, under the EXTEND THE CONTRACT column, enter the name of the attribute to be pulled from the IdP’s message (e.g., company) in the empty text field. In the ACTION column, click Add.
Click Done.
On the User-Session Creation screen, click Configure User-Session Creation.
On the Summary page, under User-Session Creation, click on the CONNECTION MAPPING CONTRACT link.
On the Connection Mapping Contract screen, make note of the CONNECTION MAPPING CONTRACT being used, because you will need to modify it by adding new attributes. In the example screenshots, the contract name is SharePoint 2013.
Click on Manage Connection Mapping Contracts.
On the Manage Contracts screen, click on the name of the contract that is being used for the current configuration (e.g., SharePoint 2013).
On the Summary screen, click on the Contract Attributes link.
On the Contract attributes screen, under the EXTEND THE CONTRACT column, enter the name of the attribute to be shared with the PingFederate service provider connection (e.g., company).
In the ACTION column, click Add.
Click Done.
On the Manage Contracts screen, click Save.
On the Connection Mapping Contract screen, you should see the new attribute (e.g., company) listed on the page.
Click on the Contract Fulfillment tab.
On the Contract Fulfillment screen, for the new attribute (e.g., company), select Assertion for the SOURCE field and select company for the VALUE field.
Click Save to complete the configuration.
6.6. Functional Test of All Configurations for Section 6¶
The instructions in this section will perform an integrated test all of the configurations in Section 6. Using the browser, you will log on using an account that was created in Microsoft AD. Then you will use the SharePoint claims viewer to validate that the newly configured attributes are passed from the IdP to the RP and that the attributes are successfully loaded into the SharePoint web session.
Launch your browser and go to the RP’s SharePoint site (e.g., https://SharePoint.abac.test).
Select Federated Logon from Identity Provider.
Enter the credentials of the Microsoft AD account created earlier in this guide (e.g., lsmith).
Click Sign On. On the RSA Adaptive Authentication screen, enter the SMS validation code received on your mobile phone. Then, click Continue.
Once you arrive at the SharePoint site home page, navigate to the claims viewer page that was created in the earlier section (e.g., https://SharePoint.abac.test/SitePages/ClaimsView.aspx). Expand the claims viewer web part on the page to see a list of claims.
6.6.1. Temporarily Disable SAML Encryption for Testing and Troubleshooting Message Exchanges¶
Follow the instructions below to temporarily disable the encryption of SAML messages between the IdP and the RP. You should perform the steps in this section only when explicitly instructed to do so in another section of the guide (e.g., during a functional test). You may also need to refer back to this section in the future to test or troubleshoot SAML message exchanges in your environment.
Temporarily disabling the encryption can help test that the expected attributes are being exchanged between the IdP and the RP. By temporarily disabling the encryption, you will be able to see the attributes and their associated values in the SAML messages using the Firefox SAML tracer add-on or a comparable software tool. When testing or troubleshooting is completed, you can enable the encryption again.
6.6.1.1. Disable SAML Encryption¶
Launch your browser and go to https://<DNS_NAME>:9999/pingfederate/app. Replace DNS_NAME with the fully qualified name of the IdP’s PingFederate server (e.g., https://idp.abac.test:9999/pingfederate/app). Log on to the PingFederate application using the credentials you configured during installation.
On the Main menu under SP CONNECTION, click Manage All SP.
Click on the link for the SP connection for which you want to disable the encryption (e.g., https://rp.abac.test:9031).
Scroll down to the Protocol Settings group.
Click on the ENCRYPTION POLICY link.
On the Encryption Policy screen, select None.
Click Save.
At this point, you have disabled SAML encryption at the IdP for this specific connection to the RP. You can perform authentication testing using the Firefox SAML tracer to examine the SAML messages being sent by the IdP to the RP.
6.6.1.2. Enable SAML Encryption again¶
Once testing is completed, follow the instructions below to enable the encryption once again.
On the PingFederate Main Menu under SP CONNECTION, click Manage All SP.
Click on the link for the SP connection for which you want to enable the encryption (e.g., https://rp.abac.test:9031).
Scroll down to the Protocol Settings group.
Click on the ENCRYPTION POLICY link.
On the Encryption Policy screen, select The entire assertion.
Click Save.
On the Select XML Encryption Certificate screen, select the Block Encryption Algorithm (e.g., AES-128), and the Key Transport Algorithm (e.g., RSA-OAEP). For the selection box above Manage Certificates, select the RP’s public key certificate to be used to encrypt the message content.
Click Save.
You have now enabled the encryption for the connection again.
8. Defining Policies and Enforcing Access Decisions with NextLabs¶
8.1. Introduction¶
In previous sections of this How-To Guide, we installed several NextLabs products that can be used to define and deploy Attribute Based Access Control (ABAC) policies, and enforce decisions regarding user access to Microsoft SharePoint resources based on user, object, and environmental attributes, and the corresponding policies in place. This How-To Guide will illustrate how to use and configure NextLabs Policy Studio, the product responsible for Policy Lifecycle Management, and discuss policy strategy and the translation of business logic into policy.
Within Policy Studio, we will define and deploy policies and policy components. In NextLabs, the word Component is a named definition that represents a category or class of entities, such as users, data resources, or applications; or of actions, such as Open or Copy. Components are similar to using parts of speech to construct policy statements. For example:
- Noun: All employees in the human resources department or Any file with an .xls extension
- Verb: Copy, Print, or Rename File
Deployment is simply the distribution of new or modified policies and policy components to the appropriate enforcement points on desktop PCs, laptops, and file servers throughout the organization. This means you can create, review and refine policies as long as you like, but they are not enforced until you actually deploy them.
Finally, the Functional Test section will illustrate how to ensure that policies are being updated, evaluated, and enforced on Microsoft SharePoint.
8.1.1. Components and Sub-Components Used in this How-To Guide¶
NextLabs Policy Studio –provides the Policy Administration Point of the ABAC architecture. This component was installed with the rest of the NextLabs product suite used in this implementation in Section 7. Policy Studio provides the graphical user interface for Policy Lifecycle Management (defining, deploying, modifying, and deactivating policies).
- Located on the SQL Server
NextLabs Policy Server SharePoint Enforcer configuration file
- Automatically exists after NextLabs Control Center installation
- Located within the NextLabs software architecture on the SQL Server
NextLabs AgentLog and bundle.bin files
- Automatically exist after NextLabs Policy Controller installation
- Located within the NextLabs software architecture on the SharePoint Server
8.1.2. Pre-requisites to Complete Prior to this How-To Guide¶
If you intend to do a setup without identity federation and federated logins, you must:
If you intend to incorporate a trust relationship between an IdP and RP, and use federated logins into SharePoint, you must:
- Install and configure Active Directory (see Section 2).
- Setup and configure the RP and IdP (see Section 3).
- Install and configure Microsoft SharePoint (see Section 4).
- Configure the SharePoint federated login with the RP (see Section 5).
- Configure the attribute flow between all endpoints (see Section 6).
- Install and configure NextLabs Control Center, Policy Studio, and Policy Controller (see Section 7).
8.2. Policy Strategy¶
8.2.1. Top-Level Blacklisting Deny Policy, Whitelisting Allow Sub-Policies¶
In order to demonstrate a policy set with high security and fine-grained control, we employed a general blacklisting, then fine grained whitelisting sub-policy strategy for the policies. We chose this strategy because we considered it a more secure paradigm for securing SharePoint resources. Using this strategy, the access control logic initially applies a general deny all access decision at the top level for a given set of related attributes, then specifies conditions under which access can be allowed in various sub-policies based on sufficient correlating user, resource, and/or environment attributes. For example, later in this guide we will describe a policy set in which we initially deny all users on resources that have a sensitivity level attribute, however there is a sub-policy that specifies that a for resources at sensitivity level 2, allow users with a clearance attribute of Secret during regular business hours. The alternative to this approach would be to apply a general allow all access decision at the top level initially, then specify conditions under which users should be denied access. Because there can be many unforeseen edge cases that may not be anticipated by a business protecting its assets, we consider the general blacklisting, then whitelisting sub-policies approach a more feasibly secure solution. According to our strategy, any time a user, resource, or environment attribute does not comply with a whitelisting sub-policy to allow access, the access decision will default to deny.
8.2.2. Global Policies¶
In addition to the blacklisting versus whitelisting approach taken in our policy strategy, we also employed the use of global policies. The term global policy refers to the general applicability of the policy sets to more than one user and more than one resource at a given time. We defined our policies such that they have global effects and do not apply only to very specific use cases by themselves. The collective logic taken from the multiple global policies in place applies to the many kinds of access events that must be controlled according to a business’s complex and distributed business rules, which we describe below in Section 8.3.
8.3. Translation of Business Logic into Policy¶
8.3.1. ABAC Build Scenario – Runabout Air Business Rules¶
In previous sections of our Practice Guide we have constructed an example business scenario where an airline company, Runabout Air, has acquired another airline company, Conway Airlines. In this scenario the two companies have not yet merged their active directory forest and established a trust relationship such that historically Conway Airlines employees will be able to access resources on the Runabout Air SharePoint according to policies that correspond to Runabout Air’s business rules. The business rules we based our policies on are, generally:
- Some documents are more sensitive than others, and should be marked in SharePoint at different sensitivity levels. These documents should be strictly protected, and access should be restricted to Runabout Air’s normal business hours. Also, users should only be granted access to sensitive documents if they have sufficient clearance.
- Users should only be able to access documents that belong to their department, or to the departments relevant to them in the case of some instances of a need for cross-department access, i.e., business intelligence employees should have access to both sales and marketing department documents.
- Some documents are time-sensitive and pertain to system or other business maintenance, and should be marked in SharePoint as maintenance documents. These documents should only be accessed outside of Runabout Air’s normal business hours, so as to reduce the likelihood of disruption of normal business operation.
- There are times when a suspicious IP address or range of addresses should be blocked from accessing any SharePoint resources, or when a user from a particular IP address or range of IP addresses should only have access to low-sensitivity documents. There must be a mechanism in place to ensure access is denied for users attempting to access any high-sensitivity documents from an environment with that IP address or within a given IP address range.
8.3.2. Translation of Runabout Air Business Rules into ABAC Policies¶
ABAC Policies created from the above business rules might look like this:
Top-level sensitivity policy: default to deny access to all users attempting to access resources that have a sensitivity level attribute defined in SharePoint as greater than 0, unless explicitly allowed access by a sub-policy.
- For documents whose sensitivity attribute is defined as 1, allow access any time of day, any day of the week, to users with a clearance attribute of None, Secret, or Top Secret.
- For documents whose sensitivity attribute is defined as 2, allow access between the hours of 6am and 6pm for users with a clearance attribute of Secret or Top Secret.
- For documents whose sensitivity attribute is defined as 3, allow access between the hours of 6am and 6pm for users with a clearance attribute of Top Secret.
Top-level department policy: default to deny access to all users attempting to access resources that have a department attribute and project status defined in SharePoint.
For users whose department attribute is defined as a value equal to the document’s department attribute value, allow access for documents with a project status of any value.
For users whose department attribute is Business Intelligence, allow access for documents with a department attribute of Sales or Marketing and with a Project status of any value.
Note: The Project status metric is necessary because the department attribute is defined at the site level within SharePoint. Restricting users based only on the resource’s department attribute in this policy set results in the user being stuck in a deny access loop, no longer being able to access the Runabout Air root site and navigate to their correct department’s documents. Because each document has a project status attribute defined in addition to the department attribute, the policies can specify the targets of this policy as having both project status and department attributes defined, even though the department attribute is the most pertinent attribute for enforcing the access control relating to department access rules.
Top-level maintenance policy: default to deny access to all users attempting to access resources that have a maintenance attribute defined in SharePoint
- For documents whose maintenance attribute is defined as no, allow access to users, any time of day, any day of the week.
- For documents whose maintenance attribute is defined as yes, allow access to users between 6pm and 6am, any day of the week.
Top-level IP Address policy: default to deny access to all users attempting to access resources that have a sensitivity attribute defined in SharePoint.
- For documents whose sensitivity attribute is defined as 1, allow access to any user from an environment with any IP address defined.
- For documents whose sensitivity attribute is defined as 2 or 3, allow access to users coming from an environment with an IP address other than a restricted IP or one within a restricted IP range.
8.4. Using the NextLabs Policy Studio GUI for Policy Definition and Deployment¶
In this section, we will provide step-by-step instructions for how to define, deploy, modify and re-deploy, and deactivate necessary policy components and policies within Policy Studio. The examples we will use correspond to the Runabout Air business rules and ABAC policies described in Section 8.3.1 and Section 8.3.2. Note that Policy Studio was installed on the SQL Server, which is where all of the activity in Section 8.4 occurs.
8.4.1. Login and Initial Screen in Policy Studio¶
Given you have followed the instructions found in Section 7, follow these instructions to login to the NextLabs Policy Studio:
In Windows Explorer, find and open the policystudio.exe application file:
In the Control Center Policy Studio window, enter User Name and Password, then click Login to connect to the Policy Management Server.
If login was successful, you will see the Policy Studio’s graphical user interface, specifically the main screen where new policies and new components are defined, deployed, modified, and deactivated. Note the Policies panel in the top-left, the Components panel in the bottom-left, and an open space to the right where editing panels emerge for editing the policies and components.
After following the instructions in this section to define and deploy several user and resource components, as well as four policy sets, the Policy Studio interface will show the new components and policies populated in the left-side panel.
8.4.3. Defining and Deploying Components¶
8.4.3.1. Explanation of Components in NextLabs¶
According to the NextLabs Policy Studio User Guide available to customers, it is necessary to define components to represent various kinds of entities in your information environment. There are several times when you might want to define a new component:
- After setting up your Control Center system, before constructing policies for the first time (which is the reason here at this point in our How-To literature)
- When new classes of information or users come under the control of information policy
- When a new policy requires a policy component that has not yet been created
- When conditions at the organization change in any way that adds new items to be covered by information control policies. For example, if the company reorganizes and adds a new division, you might need a new policy component to represent the employees in that division.
Furthermore, when you are constructing a component, you do not need to save your work explicitly. Work is automatically saved as you go. If you are interrupted while working on a policy component, or want to work on another task and return to constructing the policy component later, you can stop and continue the constructing process as desired. Your work will be saved in draft status. You can find the policy component later in the appropriate component panel.
8.4.3.2. Defining and Deploying User Components¶
According to the Runabout Air business rules in Section 8.3.1 and ABAC policies in Section 8.3.2, it is possible that you may need to create a User Component to match the following conditions: user clearance attribute, user department attribute, and user IP address. This is correct except for the user department attribute. Because of the cross-departmental access of Runabout Air’s Business Intelligence employees, we use logical syntax instead of graphical components while defining that policy. Also, a note regarding the user IP address component: even though IP address is an environmental attribute, it can be configured in NextLabs as a user attribute coming from SharePoint Claims, or as a resource attribute, which requires different configuration in NextLabs. For our example we use the IP Address from SharePoint Claims, which is handled as a user attribute.
8.4.3.2.1. Clearance Components¶
Clearance = None
In the Components panel in the bottom-left of the Policy Studio window, click on the Subjects heading, and then click on the Users tab. Then click New to create a new component.
In the Create New User Component window, enter a descriptive component name, such as clearance = None. Click OK.
In the component editing panel you will see the following:
In the editing panel, click on the plus sign box under Property Name and enter clearance in the property name text box, keep the default is as the action, then enter None into the value text box. Click Submit.
In the Submit window, click Submit.
From the component editing panel, note the differences. The new status reads Submitted for Deployment. Click Deploy.
In the Deploy window, click OK. Note: You may deploy immediately, which we choose in our example. You could also deploy the following day at midnight, or at a different specific date and time.
Verify at the bottom of the component editing panel that the Status now reads Pending Deployment. This will remain for the duration of the heartbeat (described in Section 7).
After the duration of the heartbeat has passed, Status will then read as Deployed. This indicates that the component is actively deployed in your ABAC system.
Clearance = Secret
The easiest way to create additional attribute components is to duplicate existing ones. To duplicate the existing user attribute component:
From the Component panel, highlight the name of the existing component, i.e., clearance = None
Click on Edit from the menu toolbar at the top of the window and select Duplicate from the drop-down menu, or right-click on the component and select Duplicate from the floating menu:
In the Duplicate window, edit the name of the new component, i.e., clearance = Secret. Click Save.
Edit the property value to match the component’s purpose, i.e., Secret. Click Submit.
Repeat steps 5-9 from Section 8.4.3.2.1.1 to Submit and Deploy this component.
Clearance = Top Secret
- Repeat steps 1-5 in Section 8.4.3.2.1.2 for duplicating a new user attribute component. The new component should be named clearance = Top Secret, and the property value should equal Top Secret.
8.4.3.2.2. IP Address component¶
Repeat steps 1-3 in Section 8.4.3.2.1.2 for duplicating a new user attribute component. The new component should be named ip_address = 10.33.7.211.
From the component editing panel, edit the Property Name to ip_address and the value to 10.33.7.211, leaving the default action is. Then click Submit.
Repeat steps 5-9 from Section 8.4.3.2.1.1 to Submit and Deploy this component.
8.4.3.3. Defining and Deploying Resource Components¶
8.4.3.3.1. Maintenance components¶
Maintenance = yes
In the Components panel in the bottom-left of the Policy Studio window, click on the Resources heading, and then click on the Portals tab. Then, click New to create a new component.
Enter a descriptive component name, such as maintenance = yes, then click OK.
In the editing panel, click on the plus sign box under Property Name and enter maintenance in the Property Name text box, keep the default is as the action, and enter yes into the value text box. Then click Submit.
Repeat steps 5-9 from Section 8.4.3.2.1.1 to Submit and Deploy this component.
Maintenance = no
Similar to the steps taken for duplicating user components, do the following to duplicate the existing resource maintenance component to create the other resource components.
In the Component panel in the bottom-left corner of the Policy Studio interface, right-click on the maintenance = yes component. In the floating menu, select Duplicate.
In the Duplicate window, edit the name of the new component. Example: maintenance = no.
In the component editing panel, change the property value to no and click Submit.
Repeat steps 5-9 from Section 8.4.3.2.1.1 to Submit and Deploy this component.
8.4.3.3.2. Sensitivity components¶
Sensitivity = 1
Repeat steps 1-4 from Section 8.4.3.3.1.2 to duplicate an existing resource component to create the Sensitivity = 1 component.
Sensitivity = 2
Repeat steps 1-4 from Section 8.4.3.3.1.2 to duplicate an existing resource component to create the Sensitivity = 2 component.
Sensitivity = 3
Repeat steps 1-4 from Section 8.4.3.3.1.2 to duplicate an existing resource component to create the Sensitivity = 3 component.
8.4.3.3.3. Project status component¶
Project status = any
Repeat steps 1-4 from Section 8.4.3.3.1.2 to duplicate an existing resource component to create the Project status = any component.
Note: Before the Submit step, in the component editing panel, enter the property value as *.
8.4.4. Defining Policy¶
After following the steps to define and deploy components in Section 8.4.3, you can continue on to define policies that relate to the Runabout Air scenario business rules discussed in Section 8.3. In order to define policies in Policy Studio, login as described in Section 8.4.1.
8.4.4.1. Creating a Policy Set Folder¶
Before being able to create any policies in Policy Studio, first you must create a folder, or choose an existing one.
From the main Policy Studio window, click New Folder.
Enter the name of your folder and click OK.
8.4.4.2. Defining Department-based Policy Set¶
8.4.4.2.1. Defining the Top-level Department Policy that Enforces a General Deny Decision¶
In the Policies panel in the top-left corner of the main Policy Studio window, click on your new folder to highlight it. Then click New Policy.
In the Create New Policy window, enter a name for the new policy. From the Policy Type drop-down menu, select Document Policy (which applies to all SharePoint policies). Click OK.
The new policy opens automatically in an editing panel. For this policy, keep the default Deny enforcement. Make these edits:
- In the On Resources area, click on the plus sign box next to Target. This automatically populates in and Resource Component.
- In the Condition Expression enter the ACPL: (resource.portal.department = “*” AND resource.portal.project status = “*”)
- In the Obligations area, check the Display User Alert box in order to customize the deny message displayed to the user when access is denied.
In the policy editing panel, your policy should look like this:
To deploy this policy, follow the steps in Section 8.4.5.
8.4.4.2.2. Defining a Department-based Sub-policy that Enforces an Allow Decision when Certain Conditions are met¶
In the Policies panel in the top-left corner of the main Policy Studio window, click on your new policy to highlight it. Then click on New Policy to create a sub-policy.
Select a name for the new sub-policy then click OK.
In the policy editing panel, make the following edits:
From the Enforcement drop-down menu, select Allow.
In the On Resources area, click on the plus sign box next to Target.
In the Components panel, click on Resources, then the Portals tab to see the components you created earlier.
From the Portals tab, left-click and hold the **Project status =
In the Conditions area, in the Condition Expression text box, enter the ACPL:
In the Policy Editing panel, your policy should look like this:
To deploy this policy, follow the steps in Section 8.4.5.
8.4.4.3. Defining a Sensitivity-based Policy Set¶
In order to define a sensitivity-based policy set, follow instructions similar to defining the department-based policy set in Section 8.4.4.2:
8.4.4.3.1. Defining the Top-level Sensitivity Policy that Enforces a General Deny Decision¶
In the Policies panel in the top-left corner of the main Policy Studio window, click on your folder to highlight it. Then click on New Policy.
In the Create New Policy window, enter a name for the new policy. From the Policy Type drop-down menu, select Document Policy (which applies to all SharePoint policies). Click OK.
The new policy opens automatically in an editing panel. For this policy, keep the default Deny enforcement. Make these edits:
In the Obligations area, check the Display User Alert box in order to customize the deny message displayed to the user when access is denied.
In the policy editing panel, your policy should look like this:
To deploy this policy, follow the steps in Section 8.4.5.
8.4.4.3.2. Defining a Sensitivity-based Sub-policy that Enforces an Allow Decision when Certain Conditions are met for Access to Sensitivity Level 1 Documents¶
Similar to the steps in Section 8.4.4.2.2 for creating the Department-based sub-policy, do the following:
In the Policies panel in the top-left corner of the main Policy Studio window, click on your new policy to highlight it. Then click New Policy to create a sub-policy.
Select a name for the new sub-policy then click OK.
In the policy editing panel, make the following edits:
From the Enforcement drop-down menu, select Allow.
In the Subject area, click on the plus sign next to User.
In the Components panel in the bottom-left corner of the Policy Studio window, click on Subjects, then the Users tab to see the components you created earlier.
Left-click and hold the clearance = None component to drag it onto the User field.
Left-click and hold the clearance = Secret component to drag it onto the User field.
Left-click and hold the clearance = Top Secret component to drag it onto the User field.
In the On Resources area, click on the plus sign box next to Target.
- In the Components panel in the bottom-left corner of the Policy Studio window, click on Resources, then the Portals tab to see the components you created earlier.
- Left-click and hold the sensitivity = 1 component to drag it onto the Target field.
In the policy editing panel, your policy should look like this:
To deploy this policy, follow the steps in Section 8.4.5.
8.4.4.3.3. Defining a Sensitivity-based Sub-policy that Enforces an Allow Decision when Certain Conditions are met for Access to Sensitivity Level 2 Documents¶
Similar to the steps in Section 8.4.4.3.2 for creating the sensitivity-based sub-policy for sensitivity level 1 documents, do the following:
In the Policies panel in the top-left corner of the main Policy Studio window, click on your new policy to highlight it. Then click New Policy to create a sub-policy.
Select a name for the new sub-policy then click OK.
In the policy editing panel, make the following edits:
From the Enforcement drop-down menu, select Allow.
In the Subject area, click on the plus sign next to User.
In the Components panel in the bottom-left corner of the Policy Studio window, click on Subjects, then the Users tab to see the components you created earlier.
Left-click and hold the clearance = Secret component to drag it onto the User field.
Left-click and hold the clearance = Top Secret component to drag it onto the User field.
In the On Resources area, click on the plus sign box next to Target.
- In the Components panel in the bottom-left corner of the Policy Studio window, click on Resources, then the Portals tab to see the components you created earlier.
- Left-click and hold the sensitivity = 2 component to drag it onto the Target field.
In the Conditions area, click on the plus sign boxes next to Time and Day. Edit those fields to match below:
In the policy editing panel, your policy should look like this:
To deploy this policy, follow the steps in Section 8.4.5.
8.4.4.3.4. Defining a Sensitivity-based Sub-policy that Enforces an Allow Decision when Certain Conditions are met for Access to Sensitivity Level 3 Documents¶
Similar to the steps in Section 8.4.4.3.2 for creating the sensitivity-based sub-policy for sensitivity level 1 documents, do the following:
In the Policies panel in the top-left corner of the main Policy Studio window, click on your new policy to highlight it. Then click New Policy to create a sub-policy.
Select a name for the new sub-policy then click OK.
In the policy editing panel, make the following edits:
From the Enforcement drop-down menu, select Allow.
In the Subject area, click on the plus sign next to User.
In the On Resources area, click on the plus sign box next to Target.
- In the Components panel in the bottom-left corner of the Policy Studio window, click on Resources, then the Portals tab to see the components you created earlier.
- Left-click and hold the sensitivity = 3 component to drag it onto the Target field.
In the Conditions area, click on the plus sign boxes next to Time and Day. Edit those fields to match below:
In the policy editing panel, your policy should look like this:
To deploy this policy, follow the steps in Section 8.4.5.
8.4.4.4. Defining a Maintenance-based Policy Set¶
In order to define a maintenance-based policy set, follow instructions similar to defining the department-based policy set in Section 8.4.4.2:
8.4.4.4.1. Defining the Top-level Maintenance Policy that Enforces a General Deny Decision¶
In the Policies panel in the top-left corner of the main Policy Studio window, click on your new folder to highlight it. Then click New Policy.
In the Create New Policy window, enter a name for the new policy. From the Policy Type drop-down menu, select Document Policy (which applies to all SharePoint policies). Click OK.
The new policy opens automatically in an editing panel. For this policy, keep the default Deny enforcement. Make these edits:
- In the On Resources area, click on the plus sign box next to Target. This automatically populates in and Resource Component.
- In Condition Expression, enter the ACPL: resource.portal.maintenance = “*”
- In the Obligations area, check the Display User Alert box in order to customize the deny message displayed to the user when access is denied.
In the policy editing panel, your policy should look like this:
To deploy this policy, follow the steps in Section 8.4.5.
8.4.4.4.2. Defining a Maintenance-based Sub-policy that Enforces an Allow Decision when Certain Conditions are met for Access to Documents whose Maintenance Attribute is defined as Yes¶
Similar to the instructions in Section 8.4.4.2.2 for defining a Department-based sub-policy, do the following:
In the Policies panel in the top-left corner of the main Policy Studio window, click on your new policy to highlight it. Click New Policy to create a sub-policy under this main policy.
Select a name for the new sub-policy, then click OK.
In the policy editing panel, make the following edits:
From the Enforcement drop-down menu, select Allow.
In the On Resources area, click on the plus sign box next to Target.
- In the Components panel in the bottom-left corner of the Policy Studio window, click on Resources, then the Portals tab to see the components you created earlier.
- Left-click and hold the maintenance = yes component to drag it onto the Target field.
In the Conditions area, click on the plus sign boxes next to Time and Day. Edit those fields to match below:
In the policy editing panel, your policy should look like this:
To deploy this policy, follow the steps in Section 8.4.5.
8.4.4.4.3. Defining a Maintenance-based Sub-policy that Enforces an Allow Decision when Certain Conditions are met for Access to Documents whose Maintenance Attribute is defined as No¶
Similar to the instructions in Section 8.4.4.2.2 for defining a Department-based sub-policy, do the following:
In the Policies panel in the top-left corner of the main Policy Studio window, click on your new policy to highlight it. Click New Policy to create a sub-policy.
Select a name for the new sub-policy, then click OK.
In the policy editing panel, make the following edits:
From the Enforcement drop-down menu, select Allow.
In the On Resources area, click on the plus sign box next to Target.
- In the Components panel in the bottom-left corner of the Policy Studio window, click on Resources, then the Portals tab to see the components you created earlier.
- Left-click and hold the maintenance = no component to drag it onto the Target field.
In the policy editing panel, your policy should look like this:
To deploy this policy, follow the steps in Section 8.4.5.
8.4.4.5. Defining an IP Address-based Policy Set¶
In order to define an IP address-based policy set, follow instructions similar to defining the department-based policy set in Section 8.4.4.2.
8.4.4.5.1. Defining the top-level IP Address Policy that Enforces a General Deny Decision¶
In the Policies panel in the top-left corner of the main Policy Studio window, click on your new folder to highlight it. Then click New Policy.
In the Create New Policy window, enter a name for the new policy. From the Policy Type drop-down menu, select Document Policy (which applies to all SharePoint policies). Click OK.
The new policy opens automatically in an editing panel. For this policy, keep the default Deny enforcement. Make these edits:
In the Condition Expression, enter the ACPL: resource.portal.sensitivity = “*”
In the Obligations area, check the Display User Alert box in order to customize the deny message displayed to the user when access is denied.
In the policy editing panel, your policy should look like this:
To deploy this policy, follow the steps in Section 8.4.5.
8.4.4.5.2. Defining an IP Address-based Sub-policy that Enforces an Allow Decision for Access to Resources at any Sensitivity Level when a User does not come from an Environment with a Restricted IP Address (ex: 10.33.7.211)¶
Similar to the instructions in Section 8.4.4.2.2 for defining a Department-based sub-policy, do the following:
In the Policies panel in the top-left corner of the main Policy Studio window, click on your new policy to highlight it. Click New Policy to create a sub-policy.
Select a name for the new sub-policy, then click OK.
In the policy editing panel, make the following edits:
From the Enforcement drop-down menu, select Allow.
In the On Resources area, click on the plus sign box next to Target.
- In the Components panel in the bottom-left corner of the Policy Studio window, click on Resources, then the Portals tab to see the components you created earlier.
- Left-click and hold the sensitivity = 1 component to drag it onto the Target field.
In the policy editing panel, your policy should look like this:
To deploy this policy, follow the steps in Section 8.4.5.
8.4.4.5.3. Defining an IP Address-based Sub-policy that Enforces an Allow Decision for Access to Resources at Only Sensitivity Level 1 when a User comes from an Environment with a Restricted IP Address (ex: 10.33.7.211)¶
Similar to the instructions in Section 8.4.4.2.2 for defining a Department-based sub-policy, do the following:
In the Policies panel in the top-left corner of the main Policy Studio window, click on your new policy to highlight it. Then click New Policy to create a sub-policy.
Select a name for the new sub-policy, then click OK.
In the policy editing panel, make the following edits:
From the Enforcement drop-down menu, select Allow.
In the Subject area, click on the plus sign box next to User.
In the On Resources area, click on the plus sign box next to Target.
- In the Components panel in the bottom-left corner of the Policy Studio window, click on Resources, then the Portals tab to see the components you created earlier.
- Left-click and hold the sensitivity = 1 component to drag it onto the Target field.
- Left-click and hold the sensitivity = 2 component to drag it onto the Target field.
- Left-click and hold the sensitivity = 3 component to drag it onto the Target field.
In the policy editing panel, your policy should look like this:
To deploy this policy, follow the steps in Section 8.4.5.
8.4.5. Deploying Policy¶
In order to deploy policies, follow steps similar to those for deploying a component (see Section 8.4.3.2.1.1):
In the Policies panel in the top-left corner of the main Policy Studio window, click on the policy you want to deploy. In the policy editing panel, click Submit.
In the Submit window, click Submit.
From the component editing panel, note the differences. The new status reads Submitted for Deployment. Click Deploy.
In the Deploy window, click OK. Note: You may specify to deploy immediately, which we choose in our example. You may also deploy at the following day at midnight, or at a different specific date and time.
At the bottom of the policy editing panel, verify that the Status is now Pending Deployment. This will remain for the duration of the heartbeat (described in Section 7).
After the duration of the heartbeat has passed, Status should read as Deployed. This indicates that the component is actively deployed in your ABAC system.
8.4.6. Modifying and Re-Deploying Policies and Components¶
In order to modify existing policies and re-deploy them, do the following:
8.4.6.1. Modifying and Deploying Existing Policies¶
In the Policies panel in the top-left corner of the main Policy Studio window, click on the policy you want to modify. In the policy editing panel, click Modify.
- Or, right-click the policy you want to modify and select Modify from the floating menu.
In the policy editing panel, make the desired changes and click Submit.
Follow the deploy instructions from Section 8.4.5 to deploy the modified policy.
8.4.6.2. Modifying and Deploying Existing Components¶
In the Components panel in the bottom-left corner of the main Policy Studio window, click on the component you want to modify. In the policy editing panel, click Modify.
- Or, right-click the component you want to modify and select Modify from the floating menu.
In the component editing panel, make the desired changes and click Submit.
Follow the deploy instructions from Section 8.4.5 to deploy the modified component.
8.4.7. Deactivating Policies and Components¶
8.4.7.1. Deactivating Policies¶
In the Policies panel in the top-left corner of the main Policy Studio window, right-click the policy you want to deactivate. Select Deactivate from the floating menu.
At the bottom of the policy editing panel, note the change in Status to Pending Deactivation. Click Deploy.
In the Deploy window, click OK. Note: You may specify to deploy immediately, which we choose in our example. You may also deploy the following day at midnight, or at a different specific date and time.
Verify at the bottom of the policy editing panel that the Status is now Pending Deactivation. This will remain for the duration of the heartbeat (described in Section 7).
After the duration of the heartbeat has passed, Status should read as Inactive. This indicates that the component is currently inactive in your ABAC system.
8.4.7.2. Deactivating Components¶
- In the Components panel in the bottom-left corner of the main Policy Studio window, right-click on the component you want to deactivate. Select Deactivate from the floating menu.
- Follow steps 2-5 in Section 8.4.7.1 for deactivating policies.
8.4.8. Deleting Policies and Components¶
Note: In order to delete a policy or component, you must first deactivate the item and any related sub-items.
8.4.8.1. Deleting Policies¶
In the Policies panel in the top-left corner of the main Policy Studio window, right-click on the policy you want to delete. Select Delete from the floating menu.
In the Delete window, click Yes.
8.4.8.2. Deleting Components¶
- In the Components panel in the bottom-left corner of the main Policy Studio window, right-click on the policy you want to delete. Select Delete from the floating menu.
8.5. Configuring Attributes in NextLabs¶
Section 6 illustrated how to configure the attribute flow between several of the servers and components in the ABAC architecture. Note that the NextLabs Entitlement Manager was installed on the SharePoint Server, which is where all of the activity in Section 8.5 occurs.
In order to configure NextLabs to enforce policy on all of the attributes coming from the front-channel as SharePoint Claims, you must first stop the NextLabs Policy Controller service, edit the configuration.xml file in the SharePoint Enforcer software architecture, restart Internet Information Services (IIS), then restart the NextLabs Policy Controller service using the following instructions.
8.5.1. Stopping the NextLabs Policy Controller Service¶
On the SharePoint Server, click the Windows icon and begin typing the word Services.
Double-click on the icon to open the Services application.
Within the Services application window, in the list of services, click on the Name column to sort by alphabetical order, and look for Control Center Enforcer Service.
If the status of the Control Center Enforcer Service is Running, stop it.
8.5.2. Editing the Configuration File¶
8.5.2.4. Saving Changes to the Configuration File¶
From the File menu, click Save, or Ctrl+S on your keyboard.
8.5.3. Restarting IIS via Windows PowerShell¶
Click the Windows icon.
In the Search text box, begin typing PowerShell.
Click on Windows PowerShell.
In the PowerShell window, type the command: iisreset. Press Enter.
In the PowerShell window, verify that services stopped and restarted successfully.
8.5.4. Restarting the NextLabs Policy Controller Service¶
Click on the Windows icon and begin typing the word Services.
Double-click the Services icon to open the application.
Within the Services application window in the list of services, click on the Name column to sort by alphabetical order and look for Control Center Enforcer Service.
Right-click Control Center Enforcer Service and click Start.
- It may be necessary to click the Refresh icon in order to see the Control Center Enforcer Service status change to Running.
8.6. Functional Test¶
8.6.1. Updated Bin File After Policy Creation/Modification¶
After a policy or component is deployed for the first time, or modified and re-deployed within Policy Studio on the SQL Server, an encrypted bundle.bin file on the SharePoint Server will be updated after one heartbeat. As explained in Section 7, on the SharePoint Server it is the responsibility of the Controller Manager component of the NextLabs Policy Controller (PDP) to encrypt the bundle.bin file on the local file system for use during policy evaluation by the PDP.
To ensure the policy logic is being correctly sent from the NextLabs Policy Studio (PAP) on the SQL Server to the bundle.bin file on the SharePoint Server for use by the NextLabs Policy Controller (PDP), you can find the bundle.bin file and decrypt its contents to see your policy logic decrypted there.
9. Leveraging NextLabs Control Center Reporter for Reporting and Auditing Purposes¶
9.1. Introduction¶
In previous sections of this How-To Guide (Section 7), we installed several NextLabs products that can be used to define and deploy Attribute Based Access Control policies and enforce decisions regarding user access to Microsoft SharePoint resources based on user, object, environmental attributes, and the corresponding policies in place. We also illustrated how to use and configure the NextLabs Policy Studio, the product responsible for Policy Lifecycle Management, and discussed policy strategy and the translation of business logic into policy (Section 8).
In this section of the How-To Guide, we will illustrate how to use the NextLabs Control Center Reporter, a component of the previously installed NextLabs Control Center (Section 7), in order to generate reports and provide a graphical user interface for prior policy evaluation and access control decisions in your environment.
Reporter is automatically installed during the NextLabs Control Center installation, which was detailed in Section 7. In this How-To section, we will introduce Reporter, its purpose, interface, and capabilities, then illustrate some example uses based on our build.
9.1.1. Components Used in this How-To Guide¶
NextLabs Control Center Reporter v7.5.0 (64) – web application and graphical user interface for evaluating prior policy evaluation access control decisions and generating reports for monitoring and auditing.
9.1.2. Pre-requisites to Complete Prior to this How-To Guide¶
If you intend to do a setup without identity federation and federated logins, you must:
If you intend to incorporate a trust relationship between an IdP and RP and use federated logins into SharePoint, you must:
- Install and configure Active Directory (see Section 2)
- Setup and configure the RP and IdP (see Section 3)
- Install and configure Microsoft SharePoint (see Section 4)
- Configure the SharePoint federated login with the RP (see Section 5)
- Configure the attribute flow between all endpoints (see Section 6)
- Install and configure NextLabs Control Center, Policy Studio, and Policy Controller (see Section 7)
- Define and deploy policies based on your business rules (see Section 8)
9.2. Introduction to NextLabs Control Center Reporter¶
The NextLabs Control Center Reporter is a web application that can be used to generate reports on how information is being used in your environment. You can use Reporter to define and run custom queries about policy enforcement activities that are recorded in the Activity Journal, a native, automatic logging mechanism built into the NextLabs SQL database that was configured during installation of the NextLabs Control Center (Section 7). These queries are referred to as reports. Reports can be designed to answer a wide variety of questions, such as who has access to certain documents, who is using which resources and when, what types of policy enforcement is taking place, what activity occurred within a given department, and so on.
In addition to reports, you can also use Reporter to create monitors that trigger alerts when specified policy enforcement criteria are met. You can design monitors to cover a wide range of scenarios, such as sending an alert through email when access to a certain resource has been denied more than a specified number of times in a given time period; or when the volume of classified documents that have been downloaded in a given time period exceeds a specific file size. Together, monitors and alerts can provide continuous coverage of critical policy enforcements in an enterprise, as well as a notification system that lets you know when action is required.
Reporter is intended for use by whoever is responsible for monitoring and reporting on compliance, gathering statistics about document usage, and investigating any suspected incidents of information mishandling. This may include administrators, IT staff, managers, executives, and auditors, or any other authorized personnel.
User permissions are defined in the Administrator application (another component of Control Center installed in Section 7), by creating a new User and assigning one of the four available roles to it. By default, all roles include permission to open and use the reporting functionality of Reporter.
9.2.1. Opening Reporter¶
On the server where NextLabs Control Center was installed, open a web browser (i.e., SQL Server in this build).
Enter the URL and press Enter: https://<hostname>/reporter, i.e., https://localhost/reporter
At the Reporter login screen, enter valid credentials, such as the Control Center Administrator account created in Section 7. Click Login.
In your browser, the Reporter opening view defaults to the Dashboard tab. The Dashboard tab, Reports tab, and Monitoring tab will be discussed more thoroughly in subsequent sections of this How-To Guide.
9.3. Introduction to Reporter Dashboard¶
The Reporter Dashboard is divided into panes, each displaying a predefined statistical view of data that provides a snapshot of policy enforcement trends. In the default configuration of Reporter, these panes display data in the following graphs (from the NextLabs Control Center Reporter User Guide, available only to customers at this time):
Graph | Description | May Indicate |
---|---|---|
Top Five Deny Policies (Month) | Pie chart representing the five Deny policies that were most frequently enforced over the previous thirty days. |
|
Top Ten Denied Users (Month) | Bar chart representing the ten users who have had the most instances of any Deny policy enforced against them. |
|
Top Five Deny Resources (Week) | Bar chart representing the five resources that any users have most frequently attempted to access and been blocked by an active policy, over the previous seven days. |
|
Top Five Allow Resources (Week) | Bar chart representing the five resources that users have most frequently attempted to access and been allowed by an active policy, over the previous seven days. |
|
Deny Policy Enforcement Trends (Month) | Bar chart representing the trend, over the previous 30 days, of the daily total instances of any deny policy being enforced on any user, for any resource. |
|
Recent Allows | List of details about the most recent ten instances of any allow policy being enforced against any user, for any resource. Details listed include:
|
|
Recent Denys | List of details about the most recent ten instances of any deny policy being enforced against any user, for any resource. Details listed include:
|
|
Alerts this Week: Group by Tags | Treemap representing volume of alerts in the current week. Alerts are grouped by monitor tags. |
|
Today’s Alerts: Details | List of details about the alerts raised in the current day. Details include:
|
|
These panels are configurable such that an administrator can choose which panels and data are visible and how they are laid out within the Dashboard according to the business’s business logic, policies, and priorities.
The data displayed in all panes of the dashboard is refreshed from the Activity Journal each time you open the Dashboard tab. This means that data is updated on demand; for example, if a pane shows some statistic for the past week, that reflects not the last seven whole calendar days, but the last seven 24-hour periods starting from the top of the current hour.
9.3.1. Exploring the Dashboard¶
On the server where NextLabs Control Center was installed, open a web browser, i.e., SQL Server in this build
Enter the URL and press Enter: , i.e., https://localhost/reporter
At the Reporter login screen, enter valid credentials such as the Control Center Administrator account created in Section 7. Click Login.
In your browser, the Reporter will default to the Dashboard tab.
The charts and graphs on the Dashboard are interactive. When you move your cursor over a bar in a bar chart or a slice in the pie chart, a tooltip displays information about that value series.
Example seen in the image below: 36.4% of the Deny policies evaluated in the last 30 days belonged to the SharePoint Protection – Department policy set.
Another example from this build seen in the image below: in the Deny Policies trend in the last 30 days, June 26, 2015 saw an unusually large number of Deny Policies relative to other days.
9.4. Introduction to Defining and Running Custom Reports in Reporter¶
In Reporter, you can define and run reports in the Reports tab. This tab is divided into two panes, Saved Reports on the left side of the Reports tab window and Report Details on the right.
The Saved Reports pane provides a list of all saved reports available to you. This includes all reports you create and save, all reports saved by other users and marked as Shared, and the sample reports used to generate data that is displayed in the Dashboard tab. When you click on any item in Saved Reports, the details of that report are displayed in Report Details on the right. This is also where you work when you create a new report.
In the Report Details pane, define the following:
- the time period of the policy activity data to cover in the report
- the criteria, or filters, that determine what policy activity data to include in the report
- the output format of the report
The default settings in Report Details display when you click the Reports tab or when you click New in the Saved Reports pane. By default, the time period for the report is the current day, all policy activity data at the user level is included, and the data is presented in table format.
After defining a new report or editing an existing report, click Run at the bottom of the Report Details pane to view the results, which we will illustrate in the following two subsections.
9.4.1. Defining a Custom Report¶
In this subsection, we will list the standard steps for creating a custom report. In Section 9.5 of this How-To Guide we will illustrate some example custom report sections that demonstrate Reporter’s report capabilities.
9.4.1.1. Logging into Reporter¶
Before being able to define a custom report, you must first log in to Reporter and click on the Reports tab as seen in the steps below:
On the server where NextLabs Control Center was installed in Section 7, open a web browser, i.e., SQL Server in this build.
Enter the URL and press Enter: https://<hostname>/reporter, i.e., https://localhost/reporter
At the Reporter login screen, enter valid credentials, such as the Control Center Administrator account created in Section 7. Click Login.
In your browser, the Reporter user interface will default to the Dashboard tab. The Dashboard tab, Reports tab, and Monitoring tab will be discussed more thoroughly in subsequent sections of this How-To Guide.
Click on the Reports tab to open the Reports tab window.
9.4.1.2. Defining the Custom Report¶
In order to define a custom or new report, you must specify filters and change default settings within the Report Details – Report Query pane. If you don’t specify any filters or change any of the default settings, the report retrieves all policy activity data categorized as user-level events for the current day.
In the Report Details - Report Query pane, define the report query by filling in data or using drop-down menus to define your desired report.
Note: Many of the fields are optional. Required fields contain default values.
In the From and To fields, specify the start date and time, and end date and time, respectively, of the time period you want the report to cover. Click in the field to choose a date and time from the calendar. When specifying a report period, be sure to consider the time zone where Control Center is installed, and the time period of data stored in the Activity Journal.
In Event Level, select the level of event verbosity the report contains:
User Events (default): Logged in the Activity Journal as Level 1
Application Events (application and user-level events): Logged in the Activity Journal as Level 2
All System Events (system, application, and user-level events): Logged in the Activity Journal as Level 3
Note: As a rule, you should leave this setting at User Events. This setting significantly reduces the amount of system noise. Application- or system-level events generally are not useful in monitoring policy or user activities.
In Decision, select the type of enforcement effect to include in this report:
- Allow: Instances when the policy permitted the user to perform the action covered by the policy. Note that the report results always depend on what information is logged. If the policy does not have any On Allow logging obligation specified, this report will not return any On Allow data whether or not you select this option.
- Deny: Instances when the policy did not allow the user to perform the action. Deny decisions are always logged.
- Both: All instances when the policy was enforced, with either Allow or Deny effect.
In Action, select the user action or actions to include in this report. The list shows all currently defined actions.
To select multiple actions, hold Ctrl and click each action. If you do not make any selections, all actions are included.
Note: Policies involving Paste actions do not support logging obligations, therefore, instances of their enforcement are not included in reports.
In User, specify one or more users on which to filter the activity data, or leave this field blank to include all users. Use the User Lookup window (magnifying glass icon) to browse through all users currently defined in your Information Network Directory, and select the users you want.
In User Criteria, specify additional user criteria by creating one or more conditions. Each condition consists of a user attribute, an operator, and a value. You must click the + button to add a condition to the query.
In Resource Path, type the network path of the resource on which to filter, or leave this field blank to include all resources.
In Resource Criteria, specify additional resource criteria by creating one or more conditions. Each condition consists of a resource attribute, an operator, and a value. Click the + button to add a condition to the query.
In Policy Name, specify one or more policies on which to filter, or leave this field blank to include all policies. Use the Policy Lookup window to browse through and select which policies you want to include.
In Policy Criteria, specify additional policy criteria by creating one or more conditions. Each condition consists of a policy attribute, an operator, and a value. Click the + button to add a condition to the query.
In Other Criteria, specify additional criteria by creating one or more conditions. Each condition consists of a general attribute (for example, host name, host IP, and application name), an operator, and a value. Click the + button to add a condition to the query.
9.4.1.3. Setting the Custom Report Display Options¶
Within the Report Details – Report Query pane, directly below the Other Criteria filter, continue with these steps to set the display options for your custom report:
In Report Type, select the output format in which to display the data: Table, Bar Chart, Horizontal Bar Chart, or Pie Chart. Use a table to display policy activity details in a row-and-column format. Use a chart to display a summary of policy activities.
If you selected one of the charts in Report Type, in Show, select a grouping option. Grouping is not available to a table.
- Group by User: The chart shows the number of enforcement events for each user covered by the report.
- Group by Resource: The chart shows the number of enforcement events for each resource covered by the report.
- Group by Policy: The chart shows the number of enforcement events for each policy covered by the report.
- Group by Month: The chart shows the number of enforcement events for each month covered by the report. Select this option only if the time period you specified spans more than one month.
- Group by Day: The chart shows the number of enforcement events for each day covered by the report.
In Sort By, select a field on which to sort the data, then select Asc to sort in ascending order or Desc to sort in descending order. If the report is a table, you can sort the data by any attribute. If the report is a chart, you can sort either by the grouping item (user, resource, policy, month, or day) or by Result Count (the number of enforcement events for each user, resource, policy, month, or day).
In Max Results, specify the maximum number of results to display in the table or chart. For charts, this number represents the maximum number of bars in a bar chart, or slices in a pie chart. For readability reasons, charts should display a limited number of bars or slices. For a table, the number represents the maximum number of rows (each row represents an event). Tables that show a large number of rows present the data on multiple pages.
In Display Columns, select the columns to display in a table. This setting applies to tables only. USER_NAME, POLICY_FULLNAME, POLICY_DECISION, HOST_NAME, and APPLICATION_NAME are selected by default. To remove any of those columns or to add other columns, click and use the arrow icons to move columns out of, or into, the Selected pane.
9.4.2. Running a Custom Report¶
Directly beneath the filters and data fields for defining the report and setting its display settings, do the following in order to run the report and/or save it for the future:
At the bottom of the Report Details – Report Query pane, click Run to generate the new report.
If you want to run this report again in the future, save the report. Click Options, and select Save.
9.5. Example Custom Report and Available Formats¶
In this section, we will present examples of different report formats, all representing a small set of event data, returned by the same custom report from our build. By comparing the example formats, you will gain a better understanding of the way the different formats can be used to highlight different aspects of the same data depending on your business rules or priorities.
The custom report used in this section will result from a query that requests all events by users on all resources for one week (June 7, 2015 to June 13, 2015). We include columns that are relevant for our example business logic and the ABAC policies we put in place in Section 8. For example, we chose to include the “Department” and “Sensitivity” columns, which were custom attributes in the metadata we added to the documents uploaded to the RP’s SharePoint sites.
9.5.1. Defining the Example Custom Report¶
9.5.1.1. Customizing Report Query Fields for this Report¶
In the Report Query pane, change the fields for the From and To date to match the desired query for the week of June 7, 2015 to June 13, 2015.
In the Report Query pane, click on the Max Results field to open the drop-down menu. We chose 11 for demonstration purposes.
In the Report Query pane, leave the rest of the fields in the default query settings.
9.5.1.2. Editing the Columns for Custom Views¶
Toward the bottom of the Report Query pane, click on the columns icon at the end of the Display Columns line of text to open the Select Display Column window.
In the Select Display Column window, in the Available attribute list, review standard attributes (i.e. Action, Log_Level, Host_IP, etc) and custom attributes (department, sensitivity).
Click on any available attribute of interest to highlight it, then click the single right arrow button to add it to the list of Selected attributes.
9.5.1.3. Running the Report Query¶
At the bottom of the Report Query pane, click Run to run the query. (Tip: You can click on Options and Save or Save As to save the query for future use.)
Scroll down in your browser window to see the Results pane illustrated in the following section.
9.5.2. Format: Table of Event Data¶
The default results pane with the display columns you selected displays showing the query results. This is illustrated in the following image.
This excerpt from the query results shows that:
13 pages of policy enforcement events were logged.
All events in this excerpt occurred on June 12, 2015 (as illustrated in the Date column).
Each event from this excerpt was triggered by the same user, who had logged in with a federated identity from the IdP (Sections 2 through 5)
Each event corresponds to one of three policies: SharePoint Protection – Sensitivity, SharePoint Protection – Maintenance Denied 5am-5pm, or SharePoint Protection – Department.
Five resources were involved:
- The first row shows that the resource was an .rtf document from the Internet Technology department’s SharePoint sub-site, marked at sensitivity level 3.
- The second through fourth rows show that the resource was the Internet Technology department site.
- The fifth through seventh rows show that the resources were the underlying .css style sheet and logo used on the SharePoint site.
- The seventh through tenth rows (up to the second to last) show that the resources were the underlying .css style sheet and logo used on the SharePoint site.
- The eleventh and final row from this excerpt shows that the resource was another .rtf document from the Internet Technology department SharePoint sub-site, marked at sensitivity level 1.
In the case of three out of the five resources, the enforcement decision was Allow, as shown in the fourth column (second through tenth rows).
In the case of two out of the five resources, the enforcement decision was Deny, as shown in the fourth column (first and last rows).
Keep these details in mind as you analyze the data in the following charts.
9.5.3. Format: Bar Chart Grouped by Policy Chart¶
Grouping events by policy is useful for identifying policies that are being triggered with unexpected frequency, which may be an indication that they are improperly designed and cover users, resources or actions that they should not. It can also indicate concentrated efforts at unauthorized data access. To examine the latter possibility, it is often helpful to switch to the Group by User option in order to focus on who is performing the activity, as seen in Section 9.5.2.
9.5.3.1. Customizing the Display Settings¶
Using the Report Details – Report Query window from Section 9.5.2 for displaying the results in Table format, make the following edits to display results in a Bar Chart grouped by Policy:
From the Report Type list, select Bar Chart.
From the Show list, select Group by Policy
From the Sort By list, select Policy.
From the Max Results list, choose a number or type one in the field.
Example: The value 6 means that our bar chart will display up to six policies, including but not limited to the number of policies displayed in the Table format.
Click on the Asc (Ascending) radio button to set the sorting order.
9.5.3.2. Running the Report Query¶
At the bottom of the Report Query pane, click Run to run the query
9.5.3.3. Viewing the Results as a Bar Chart Grouped by Policy¶
In the same browser window, scroll down if necessary. Under the Run button, review the resulting Bar Chart Grouped by Policy.
As illustrated below, hundreds of enforcement decisions were logged during the week, and the three most commonly evaluated policies include two that were included in the table from Section 9.5.2, formatting results by Table.
9.5.4. Format: Bar Chart Grouped by User Chart¶
When the same data is grouped by user, and the bar chart is selected, the following chart is generated. As noted previously, the four policies were each triggered by a different user, so the graph shows four bars—each representing one user. Each is labeled with a user name. In this example, the bars are the same height, since each of the four users triggered a policy once.
9.5.4.1. Customizing the display settings¶
Using the same Report Details – Report Query window from the previous subsection, make the following edits to display results in a Bar Chart Grouped by Policy.
From the Report Type list, select Bar Chart.
From the Show list, select Group by User.
From the Sort By list, select User.
From the Max Results list, choose a number or type one in the field.
Example: The value 6 indicates that this will be the maximum number of users reflected in our Bar Chart.
Leave Asc selected.
9.5.4.2. Running the Report Query¶
At the bottom of the Report Query pane, click Run to run the query.
9.5.4.3. Viewing the Results as a Bar Chart Grouped by User¶
In the same browser window, scroll down if necessary. Under the Run button, review the resulting Bar Chart Grouped by User:
As illustrated below, only five users were accessing the protected RP SharePoint resources during this week period, and all logged in via federated identity from the IdP.
- Two users had very minimal activity logged during this week: schen@abac.test and sharepointadmin@abac.test
- Two users had relatively similar activity logged during this week: jdoe@abac.test and jgonzalez@abac.test
- One user had an extremely large amount of activity logged during this week: lsmith@abac.test
9.5.5. Format: Pie Chart Grouped by Resource¶
The Group by Resource option shows the extent of specified events—in this case, policies being triggered—per individual resource covered by the report.
Because policies often cover large numbers of individual documents or other resources, grouping by resource is only helpful when the number of events has already been narrowed down to a smaller set by various report filters, such as policies or users. A pie charts is ideal here, because in the context of resource use, the relative access activity regarding some single file or other resource as compared to all others is generally of more interest than any absolute number of instances of access.
9.5.5.1. Customizing the Display Settings¶
Using the same Report Details – Report Query window from the previous subsection, make the following edits to display results in a Bar Chart grouped by Policy
From the Report Type list, select Pie Chart.
From the Show list, select Group by Resource.
From the Sort By list, select Resource.
From the Max Results list, select a number or type one.
Example: The value 10 means that will be the maximum number of resources displayed in our Pie Chart.
Leave Asc selected.
9.5.5.2. Running the Report Query¶
- At the bottom of the Report Query pane, click Run to run the query.
9.5.5.3. Viewing the Results as a Bar Chart Grouped by User¶
In the same browser window, scroll down if necessary. Under the Run button, review the resulting Bar Chart Grouped by Policy:
As illustrated below, the maximum of ten resources are displayed in the pie chart.
- The most commonly accessed resource during this week period (69.5%) was our build’s SharePoint home page.
- The two second-most accessed resources during this week period were the ABAC IT department and its forms sub-site (where documents are stored).
- The remaining seven most-accessed resources during this week after the top three have relatively very minimal access, and the majority of those are documents that belong to specific department sub-sites, such as Finance Dept Quarterly Reports, IT Dept System Configuration documents, etc.
9.6. Further Example Custom Reports from Our Build¶
In this section, we will illustrate how to define custom reports that will provide a graphical representation of particular kinds of activity that could be of interest to our RP business.
For our first additional example, we will use a fictitious user from our build’s IdP and check her activity on the RP SharePoint site within a specific time period. The report we define will focus on the user Lucy Smith (username: lsmith) and all of her Allowed and Denied access during a specific timeframe, such as May 1, 2015 – June 30, 2015.
For our second additional example, we will use a document on the RP SharePoint site that has been marked with a metadata attribute called sensitivity. The document’s sensitivity value is set to 3, which according to our example ABAC policies requires that 1) the user accessing the document belongs to the same or appropriate department for accessing it, 2) the access occurs during regular business hours Monday-Friday, and 3) the user has a clearance attribute value of Top Secret. The report we define will focus on the access attempts on that document for the months of May and June 2015.
9.6.1. Custom Report Illustrating All Access for One User During a Two-Month Period¶
Follow the steps for Section 9.5.4, Format: Bar Chart Grouped by User, and change the From field to May 1, 2015 and the To field to June 30, 2015.
Within the browser, in the results area at the bottom of the Report Details window, click on the vertical bar that represents the user lsmith@abac.test or abac\lsmith (light green, the far-right bar in our chart below).
Within the browser window, scroll up to Report Details and verify that the User: field was automatically populated with abac\lsmith.
Within the browser window, scroll back down to the resulting Table to review its data. See the excerpt below.
9.6.2. Viewing Access Attempts on Individual Resources¶
This section provides instructions for creating a custom report that shows the access attempts of a single resource for a period of two months.
Follow the steps for Section 9.5.5, Format: Pie Chart Grouped by Resource, and change the From field to May 1, 2015 and the To field to June 30, 2015.
From the resulting list of resources under the pie chart, find the color of a resource with a name including level 3, which according to our schema means in SharePoint metadata the sensitivity level attribute is equal to 3.
Click on that resource in the pie chart (example: light pink area of 2.3% is for a Sales Dept document called sales document 2015 – level 3.txt).
Within the browser window, scroll up to Report Details and verify that the Resource Name: field was automatically populated with the name Sales document 2015 – level 3.txt.
Within the browser window, scroll back down to the resulting table to review its data. See the excerpt below.
10. Configuring a Secondary Attribute Provider¶
10.1. Introduction¶
This section provides a description of the architecture, compilation, and deployment instructions for a secondary attribute provider and its components, which we describe as a custom Policy information point (PIP), to be included as part of the ABAC infrastructure. We also demonstrate how to configure the Relying Party server to accommodate the custom PIP and its component JIT provisioning mechanism.
The secondary attribute provider comes into the picture when a user tries to access a resource at the Relying Party’s Resource Provider, and the Policy decision point (PDP) finds that an essential attribute needed to make the access control decision is missing from the initial set of attributes sent from the Identity Provider. In our build, this would mean a user with a federated identity (via PingFederate Identity Provider, IdP, augmented with two-factor authentication by RSA AA) has already logged into Microsoft SharePoint (Relying Party’s Resource Provider), but when trying to open a particular resource on the site, the NextLabs Policy Controller (PDP) makes a run-time decision that additional subject attributes are needed before the access decision can be made. The PDP determines this while evaluating the existing ABAC policies (created in the NextLabs Policy Studio, PAP in our ABAC build) against the user, resource, and environmental attributes at play at the time of requested access.
Providing the secondary attribute collection capability in our build required the implementation of new components and related features, which we will describe more in detail later in the section:
- NextLabs Policy Information Point (PIP) Plugin to extend the NextLabs Policy Controller (PDP) when additional attribute(s) are needed
- Protocol broker to initiate and receive a SAML attribute query and SAML response
- Custom data store plugin for PingFederate on the Relying Party (RP) server which will cache attributes in order to limit the number of secondary requests to the PingFederate Identity Provider (IdP) server
- Apache Directory Server (ApacheDS), an LDAP in which PingFederate can create and update local user accounts and associated attributes based on the attributes contained in SAML assertions received after authentication from IdP
- PingFederate RP configuration must be modified so that it can serve as an IdP as needed, such as when checking its JIT cache (Apache DS LDAP) before sending requests to the IdP
In later sub-sections of this section we will discuss in detail the purpose of each of these new components and features, and how they are developed, configured, compiled, and deployed.
Note: The custom PIP we have developed involves new custom components, open source components, and commercially available components. For open source and commercial components, the related descriptions in this section have been limited to installation and relevant configuration required for the desired functionality of our build. If you are interested in other details or additional capabilities of this software, explore the referenced product literature or contact that organization.
10.1.1. Pre-Requisites¶
In order to follow the instructions of this How-To section, it is necessary that seven of the previous How-To sections have been successfully completed. The required components that must be installed and configured before continuing in this How-To section include:
- Installation and Configuration of Active Directory (Section 2)
- Installation and Configuration of RSA AA (Section 2)
- Installation and Configuration of RSA AA Plugin (Section 2)
- Installation and Configuration of PingFederate on both the RP and IdP federation servers (Section 2 and Section 3),
- Installation and Configuration of Microsoft SharePoint (Section 4 and Section 5)
- Configuration of the attribute flow (Section 6)
- Installation and Configuration of NextLabs Control Center, Policy Studio, Policy Controller, and Entitlement Manager for SharePoint Server (Section 7)
10.1.2. Criteria for Secondary Attribute Collection¶
At the time of ABAC policy evaluation, required attributes may not be available or the system may not find it appropriate to use for various reasons, including, but not limited to:
- For security and privacy purposes it is not ideal to acquire all known attributes for a subject when the session is created. Some attributes maybe PII or of higher sensitivity and should not be sent to the relying party until an access request made by the user requires those attributes.
- Depending on the longevity of a session, attributes risk becoming stale. Because of this potential for staleness, it is essential to procure attributes as needed, depending on the freshness criteria established by the system. The freshness of attributes is sometimes guided by the policies established for a local cache.
- The attribute needed for a specific attribute request may not an attributed owned by the Identity provider but rather may need to be acquired from an external party attribute provider.
10.1.3. Components¶
The custom PIP described in this section is composed of four new components and mechanisms which interact or integrate with different existing components in our ABAC build as extensions, plugins, or web applications:
- NextLabs Plugin: This plugin extends the NextLabs Policy Controller to make attributes available based on the criteria mentioned in Section 10.1.2, when the PDP determines that attribute values needed to evaluate an ABAC policy are insufficient or unavailable. Following the recommendation in the software development framework provided by NextLabs, the NCCoE implemented this PIP plugin in Java, and deployed the plugin within the NextLabs Policy Controller software architecture on the server we call SharePoint server in our build. Due to the requirements of the Policy Controller architecture, the plugin can request the values of multiple missing attributes sequentially, one at a time.
- Protocol Broker: This agent, in the form of servlet local to the NextLabs installation, is responsible for facilitating communication between the NextLabs PIP Plugin and the PingFederate RP server following an Assertion Query/Request SAML2 Profile. This web application is deployed on a tomcat server that listens on localhost( 127.0.0.1) and only communicates using https with mutual TLS. Similar to the NextLabs PIP Plugin, this component is also installed on the SharePoint server.
- Ping Custom Data store: This custom data store is an extension built using Ping SDK. It enables the RP server to query the IdP server and coordinates resulting attribute values back to the RP. When it is chained with a built-in data store to query JIT Cache (LDAP), it enables RP to provide data from and configuration to various data stores (JIT in this build). This helps the custom data store to query and coordinate the result from local JIT and remote Active Directory at the PingFederate IdP.
- Just-in-Time provisioning is a feature provided by PingFederate to store attributes of a subject for a limited time. We implemented JIT provisioning using ApacheDS. ApacheDS 2.0 is an embeddable, extendable, standards compliant, modern LDAP server written entirely in Java, and available under the Apache Software License. It also supports network protocols like Kerberos and NTP. PingFederate RP acts as an IdP for the secondary attribute provider. To fulfill in this role, the PingFederate administrative console provides mechanisms to configure SP and IdP connections. These configurations manage connection settings to support the exchange of federation-protocol messages. It also allows configuration of data stores within the connection and an attribute contract that acts as the medium to convey attribute mapping from one entity to another.
10.1.3.1. Sequence Diagram of Custom PIP Component Interactions¶
Figure 10‑1 Architecture
10.1.3.1.1. Description¶
Nextlabs PDP (Policy Controller) is the arbitrator for all access decisions at the SharePoint portal. It controls access to SharePoint URL(s) by evaluating rules against the attributes of the entities (subject and object), actions, and the environment relevant to a request. It may be possible that the attribute required for the decision is not available at run time. In that case, it looks for the registered plugin that will fetch the attribute using the following flow:
- When the policy controller does not receive the attributes required to make a decision, a secondary attribute request will be initiated by calling the PIP Plugin.
- PIP Plugin is a registered plugin with the NextLabs Policy Controller. It implements the interface dictated by the NextLabs software. By virtue of this implementation, it receives the subject and name of the attribute that is required for the policy decision.
- When the subject and attribute name are received, the PIP Plugin checks its local short-term cache (in this build, configured to hold values for two seconds) to see if the needed attribute for the subject was recently requested.
- If the attribute is still in cache, the value is returned to the Policy Controller. If the value is not in cache, the PIP Plugin initiates an HTTPS request to the Protocol Broker.
- The Protocol Broker receives the attribute name and subject from the HTTPS request and forwards them as a signed SAML 2.0 Attribute Query to PingFederate-RP on a channel protected by mutual TLS.
- Once PingFederate-RP receives the SAML 2.0 attribute query, it sends an LDAP request to the JIT cache to see if the attribute was previously queried in a secondary request.
- If the subject does not have the attribute value assigned in the JIT cache, PingFederate-RP will forward the subject and attribute name to the Custom Data Store plugin. The Custom Data Store plugin acts as a pointer back to the PingFederate-IdP. To do this, the Custom Data Store dispatches an HTTPS request to the PingFederate-RP with the PingFederate-IdP as the attribute query point.
- Ping Federate uses an HTTPS query to form a SAML 2.0 attribute query and dispatch it to the Ping Federate at the IdP.
- The Ping Federate at the IdP accepts the SAML 2.0 request, verifies if the user has the attribute of need, and replies back to the PingFederate-RP with a SAML 2.0 response.
- PingFederate-RP validates the SAML 2.0 response, retrieves attribute values, and responds to the original Custom Data Store HTTP request with the attribute values.
- The Custom Data Store then responds to the PingFederate-RP attribute request with an attribute response.
- The PingFederate-RP constructs a SAML 2.0 response and sends it to the Protocol Broker.
- The Protocol Broker retrieves the attribute or exception from the SAML 2.0 response and forwards it to the NextLabs plugin, which passes the attribute or exception back to the Policy Controller.
10.2. Component Software and Hardware Requirements¶
Component | **Server where component is installed ** | Compilation method | **Required software or hardware ** | Operating System | Optional Software |
---|---|---|---|---|---|
Ping Custom Data Store | PingFederate RP server | Ant 1.9.2 | PingFederate 7.3.2; Java version same as PingFederate installed | Windows Server 2012 | |
NextLabs Plugin | SharePoint server | Apache Maven 3.2.5 | SharePoint 2013; NextLabs Entitlement Manager for SharePoint Server, NextLabs Policy Controller, NextLabs Control Center, NextLabs Policy Studio; SQL Server 2012; Java version same as NextLabs Policy Controller installed (1.6) | Windows Server 2012 | BareTail (used here as a log file annotator) Copyright Bare Metal Software Pty Ltd. Download 05/22/2015. |
Protocol Broker | SharePoint server | Apache Maven 3.2.5 | PingFederate 7.3.2; SharePoint 2013; NextLabs Entitlement Manager for SharePoint Server, NextLabs Policy Controller, NextLabs Control Center, NextLabs Policy Studio; SQL Server 2012; | Windows Server 2012 | |
Apache Directory Server | N/A | PingFederate 7.3.2; Java 7.0 (recommended by Oracle’s JDK. Some issues have been reported with Java 8); 384 MB of memory by default, can be changed using Apache Directory Studio (included) | Windows Server 2012 |
10.3. Ping Custom Data Store¶
10.3.1. Functionality and Architecture¶
This data store was developed according to the guidelines from the Ping Identity provided here. It has three functionalities:
Configuration
- HttpConfig class is used to read in a configuration file for the custom data store. Configuration parameters, like truststore location, password and attribute names can be defined in a file and read in as a configuration by HttpConfig class. The structure of the HttpConfig class configuration is based on spring annotation.
- Other sets of configuration can be read via a web interface. A detailed description of these parameters is provided in step 9 of Section 10.3.4 in this how-to guide.
Communication
- Similarly, dispatching the http request relies on PingClient class. PingClient uses classes under the spring http package. PingClient sends an https query to Attribute Query End Point. All of the parameters for the https URL are provided by the web interface.
Custom Data Store
- CustomDataStore is a class that implements com.pingidentity.sources.CustomDataSourceDriver.
- It implements all methods specified by the contract, i.e.:
- boolean testConnection(): This method tests whether a host and port is reachable or not. It is assumed that if host and port is reachable, a URL will be available.
- java.util.List<java.lang.String> getAvailableFields():
- java.util.Map<java.lang.String,java.lang.Object> retrieveValues( java.util.Collection<java.lang.String> attributeNamesToFill, SimpleFieldList filterConfiguration)
The Class Structure and their interactions are provided in the Interaction Diagram and Class Diagram.
Figure 10‑2 Ping Custom Data Store Interaction Diagram
Figure 10‑3 Ping Custom Data Store Class Diagram
10.3.2. Deploying the Ping Custom Data Store¶
Note: PingFederate administrator’s manual provides detailed steps for every platform. In our build, we used the Windows Server 2012 platform.
Log on to the PingFederate RP server.
Click on the Windows icon and begin typing Services.
Double-click the Services application icon.
Click on the Name column to sort by alphabetical order, and look for PingFederateService.
If the status column reads running, right-click on PingFederateService and click Stop.
Prepare environment based on PingFederate documentation. This may involve going to ../pingfederate-7.3.0/pingfederate/sdk folder
Click on the Windows icon and begin typing Cmd.
Double-click the icon to open the Command Prompt.
In Command Prompt, navigate to your installation of PingFederate and its sdk folder by typing the following command and pressing Enter. Example:
cd C:/pingfederate-7.3.0/pingfederate/sdk/
Within the sdk folder, locate build.local.properties and open it with your default text editor. For example, enter the following command and press Enter: notepad build.local.properties
In your default text editor (Notepad in our example), set or update target-plugin.name to idp-query-data-store, i.e., # Please set the
target-plugin.name
property to the name of the directory (under plugin-src) that # contains the source code of the plugin you want to build.target-plugin.name=idp-query-data-store
Within the Command Prompt window, navigate to your idp-query-data-store folder by entering a cd command with a path to your idp_query_data_store and pressing Enter. Example:
cd C:/--path-to-your-idp_query_data_store
Within the Command Prompt window, copy idp-query-data-store along with all subfolders to your PingFederate installation’s sdk/plugin-src folder by entering a cp command and pressing Enter. Example:
cp –rf idp_query_data_store C:/pingfederate-7.3.0/pingfederate/sdk/plugin-src
Within the Command Prompt window, run the following command and press enter in order to make sure all relevant subfolders exist:
ls -ltr ./idp-query-data-store/
Example results from the above command:
total 4 drwxrw-r--. 3 t… t…. 16 Apr 29 11:34 java drwxrw-r--. 2 t… t…. 4096 Apr 29 12:59 lib drwxrwxr-x. 4 t… t…. 30 May 15 17:52 build drwxrw-r--. 2 t… t….51 May 29 09:26 conf
10.3.3. Compilation¶
The Building and Deploying with Ant section of the SDK Developer’s Guide by Ping provides a detailed description of compiling and deploying the project using Apache Ant. For current deployment, it may be sufficient.
Click on the Windows icon and begin typing the word Cmd.
Double-click the icon to open the Command Prompt.
It is essential to know about the attributes that this data store will return. PingFederate calls the getAvailableFields() method to determine the available fields that could be returned from a query of this data source. These fields are displayed to the PingFederate administrator during the configuration of a data source lookup. The administrator can then select the attributes from the data source and map them to the adapter or attribute contract. PingFederate requires at least one field returned from this method.
To change it, go to your ping installation directory. From that directory, navigate to ..\pingfederate-7.3.0\pingfederate\sdk\plugin-src\idp-query-data-store\conf. Open .\config.properties with your favorite editor. Change the value for the attribute called NameOfAttributes:
NameOfAttributes=fullname,username,stafflevel,role,division,employer,clearance
Use a comma to separate attribute names. More attributes can be added by adding subsequent commas and attribute names.
Navigate to your PingFederate sdk folder, i.e.,
cd C:/pingfederate-7.3.0/pingfederate/sdk/
Within the Command prompt window, type the following compilation command and press Enter:
ant deploy-plugin
10.3.4. Configuration within PingFederate Administrative Console¶
The end of successful execution of ant deploy-plugin signals the installation of the data-store driver. Its configuration is provided in detail by Ping documentation. In summary, it spans the following process:
Logon to the Ping RP server.
Open an internet browser.
Enter the following URL and press Enter: https://localhost:9999/pingfederate/app
Enter your PingFederate administrator username and password, then click Login.
In the browser window, under the main menu area, find Server Configuration > System Settings > Data Stores. Double-click on Data Stores.
At the bottom of the browser window, click Add New Data Store.
On the Data Store Type screen, select Custom and click Next.
On the Custom Data Store Type screen, specify Data Store Instance Name and Data Store Type. The name can be arbitrary, but you must select IDP Attribute Query from the Data Store Type drop-down. Click Next.
To configure the data store, the following parameters must be configured. These parameters are guided by the requirements of the end point (/sp/startAttributeQuery.ping) defined by Ping documentation here:
https://10.33.7.5:9031/sp/startAttributeQuery.ping?AppId=appid&SharedSecret=3Federate&PartnerIdpId=https://idp.abac.test:9031&Subject=lsmith@abac.test
Attribute Query URL: the URL specifying the endpoint inside RP (Relying Party) that will query the IDP, i.e., https://rp.abac.test:9031/sp/startAttributeQuery.ping
AppId field used in query: the unique identity of the initiating application, i.e., appid
Shared Secret field used in query: used to authenticate the initiating application. The AppId and SharedSecret must both match the application authentication settings within the PingFederate server, i.e. !23234Federate
Partner IDP ID: used to identify the specific IdP partner to which the Attribute Query should be sent. If this parameter is not present, the Subject and Issuer are used to determine the correct IdP, i.e., https://idp.abac.test:9031
10.4. NextLabs PIP Plugin¶
10.4.1. Architecture¶
The NextLabs Control Center can support custom PIP plugin extensions for dynamic user and resource attribute retrieval during runtime. In order to install and deploy a PIP plugin such as the one described in this section, it is necessary to have previously installed and deployed the NextLabs Control Center, Policy Controller, Policy Studio, and the NextLabs Entitlement Manager (Section 7).
According to the NextLabs PDP Policy Extension documentation, which is only available to NextLabs customers at this time, one method for leveraging this PIP extension capability is by way of a getAttribute() function within a UserAttrProviderMod class. The PIP Plugin implements methods defined by the ISubjectAttributeProvider interface. The ISubjectAttributeProvider interface declares the method getAttribute() function which enables querying for a single subject attribute sequentially until all missing required attributes have been requested.
10.4.1.1. Required classes of the NextLabs PIP Plugin:¶
UserAttrProviderMod class must exist and must contain a getAttribute() function.
- The getAttribute() function must accept two arguments (IDSubject and String) and return an EvalValue. The EvalValue is created using its build() function and the attribute value ultimately returned from the Protocol Broker (see Section 10.5).
HTTPSTransmitter class
- makes an HTTPS request to the Protocol Broker using a doPost() function
CacheKey class, implementing a local Ehcache
- The CacheKey class constructor takes two parameters, the subjectId and the attributeName, which serve as a compound cache key for storing and retrieving the value of a given user’s attribute within the plugin’s local Ehcache.
10.4.1.2. Other Required Files or Deployment Notes:¶
The three above classes must be compiled into a .jar file.
Our method of compilation in this build was using Apache Maven 3.2.5. Maven compilations are directed by a pom.xml (“Project Object Model”), which is an XML representation of a Maven project. More information about Apache Maven and its pom file requirements can be found here: https://maven.apache.org/pom.html
According to NextLabs support, be sure to include within the pom.xml file configuration a statement that specifies the Provider-Class. The Provider-Class is the UserAttrProviderMod class that contains the getAttribute() method. Example pom.xml excerpt from the pom.xml file in this implementation:
<configuration> <archive> <manifest> <mainClass>nist.pdpplugin.UserAttrProviderMod</mainClass> </manifest> <manifestEntries> <Provider-Class>nist.pdpplugin.UserAttrProviderMod</Provider-Class> </manifestEntries> </archive> </configuration>
Also required per NextLabs support documentation, for any custom plugin you must include a properties file.
The configuration file should end with the “.properties” file extension. Example from this implementation: nlsamlpluginService.properties
Contents should be similar to our example copied below. You must include a category = ADVANCED CONDITION statement per NextLabs deployment and loading requirements:
name = NLSAMLPlugin_Service jar-path = [NextLabs]/Policy Controller/jservice/jar/nlsamlplugin/NLSAMLPlugin-0.0.1-SNAPSHOT-jar-with-dependencies.jar friendly_name = NLSAMLPlugin Service description = NLSAMLPlugin Service
10.4.1.3. Notes on Jar and Properties File Deployment within NextLabs Policy Controller Software Architecture:¶
The jar file containing the three classes must be deployed on the SharePoint server within the NextLabs Policy Controller software architecture in a specific location. Under the C:/Program Files/NextLabs/Policy Controller/jservice/jar folder you must create a folder specifically for your custom jar, i.e., C:/Program Files/NextLabs/Policy Controller/jservice/jar/custom_jar_folder_you_create
Any other required supporting jars can be compiled within the same jar as the UserAttrProviderMod class and other classes deployed as described in the previous step.
- Otherwise, any additional required supporting jars can be compiled into a separate jar which is deployed elsewhere within the NextLabs Policy Controller software architecture on the SharePoint server, i.e., C:/Program Files/NextLabs/Policy Controller/jre/lib/ext/
The properties file must be deployed on the SharePoint server within the NextLabs Policy Controller software architecture in a specific location, under the C:/Program Files/NextLabs/Policy Controller/jservice/config folder, i.e., C:/Program Files/NextLabs/Policy Controller/jservice/config/jarpropertiesfile.properties
10.4.2. Understanding How the NextLabs PIP Plugin Interacts with Build Components¶
When a policy is executed and the NextLabs Policy Controller PDP determines that attributes sent in the initial set up of the session are insufficient, the getAttribute() function in the UserAttrProviderMod within the NextLabs Plugin jar is automatically executed sequentially for each missing attribute.
As described above, when the initial set of attributes is insufficient, the NextLabs PIP Plugin first checks a local cache, implemented using the Ehcache library and a CacheKey class illustrated above. If the requested attribute exists within the local cache, the NextLabs PIP Plugin retrieves and returns it immediately for use during policy evaluation by the Policy Controller (PDP).
If the requested attribute does not exist within the local cache, the NextLabs PIP Plugin’s HTTPSTransmitter class makes an https request to the Protocol Broker using a doPost() function. The Protocol Broker performs its functions and returns either the desired attribute or an exception back to the NextLabs PIP Plugin, where the Policy Controller (PDP) can evaluate the relevant ABAC policy and determine an access decision. In the case that the requested attribute does not exist, the NextLabs Policy Controller PDP is configured to default to Deny access in our build. The NextLabs Policy Controller PDP is also configured to Deny Access whenever the Protocol Broker or the NextLabs PIP Plugin produces an exception.
Figure 10‑4 NextLabs PIP Plugin Class Diagram
Figure 10‑5 NextLabs PIP Plugin Interaction Diagram
10.4.3. Compilation and Deployment¶
10.4.3.1. Compiling the NextLabs PIP Plugin Jar¶
- Verify that you are on the server hosting your SharePoint instance, called the SharePoint server in our build.
- Click on the Windows icon and begin typing Cmd.
- Double-click the icon to open the Command Prompt.
- In the Command Prompt window, navigate to the folder where your pom.xml exists and click Enter, i.e., cd C:/software/java/plugin/
- In the Command Prompt window, run the following command and press Enter to compile your files and jar(s) into a single jar: mvn clean install
10.4.3.2. Stopping the NextLabs Policy Controller Service Before NextLabs PIP Plugin Jar Deployment¶
Still on the SharePoint server, click on the Windows icon and begin typing Services.
Double-click the icon to open the Services application.
In the Services application window, in the list of services, click on the Name column to sort by alphabetical order and look for Control Center Enforcer Service.
If the status of the Control Center Enforcer Service is running, stop it by following these steps:
10.4.3.3. Deploying the NextLabs PIP Plugin Jar and its Configuration File¶
- Still on the SharePoint server, Click on the Windows icon and begin typing Cmd.
- Double-click the icon to open the Command Prompt.
- In the Command Prompt window, navigate to the folder where your NextLabs Policy Controller installation exists, and into its /jservices/jar folder where custom plugins are required to be stored, then press Enter. i.e., cd C:/Program Files/NextLabs/Policy Controller/jservice/jar/
- In the Command Prompt window, enter a command similar to the following and press Enter to create an empty folder named after your plugin: mkdir nlsamlplugin
- In the Command Prompt window, enter a command similar to the following and press Enter to copy your plugin jar from its existing location (example C:/software/java/plugin/target/) to the new plugin folder you just created: copy “C:/software/java/plugin/target/plugin.jar” “nlsamlplugin/”
- In the Command Prompt window, enter a command to navigate to the folder where your NextLabs Policy Controller installation exists, and into its jservices folder which contains the config folder where custom plugin .properties files are required to be stored, then press Enter. i.e., cd C:/Program Files/NextLabs/Policy Controller/jservice/
- In the Command Prompt window, enter a command similar to the following and press Enter to copy your plugin .properties file from its existing location (example C:/software/java/plugin/) to the config folder: copy “C:/software/java/plugin/nlsamlpluginService.properties” “config/”
10.4.3.4. Resetting IIS and Restarting the NextLabs Policy Controller Service¶
Click on the Windows icon and begin typing PowerShell.
Double-click the icon to open Windows PowerShell.
In the Windows PowerShell window, type in this command and press Enter to reset Internet Information Services: iisreset
Click on the Windows icon and begin typing Services.
Double-click the icon to open the Services application.
Within the Services application window, in the list of services, click on the Name column to sort by alphabetical order and look for Control Center Enforcer Service.
Right-click Control Center Enforcer Service and click Start.
It may be necessary to click the Refresh icon in order to see the Control Center Enforcer Service status change to running.
10.5. Protocol Broker¶
10.5.1. Architecture¶
The Protocol Broker decouples communication between the NextLabs Plugin and PingFederate RP. As noted earlier, the Protocol Broker is a web application hosted on a tomcat server installed on the SharePoint server. It communicates using mutual TLS and listens on the localhost. This ensures that the service provided by Protocol Broker is not available on the network, and the requester must be authenticated during each request.
SAMLProxy extends the HttpServlet class, which is an abstract class. This enables SAMLProxy class to read/write the http request/response, and determines the http method of the request (i.e. HTTP GET, POST, PUT, DELETE, HEAD etc) and calls one of the corresponding methods. The SAMLProxy class only implements the POST method.
The SAMLProxy class constructs an object of the SoapHTTPTransmitter class. This class reads abacClient.jks and truststore.jks which are used for mutual TLS communication initiated by the SoapHTTPTransmitter with PingFederate. It also reads abacSigningClient.jks, which is used to sign the SAML AttributeQuery, and metadata to verify the SAML Response signature. The jks extension stands for Java Key store, which is a storage facility for cryptographic keys and certificates.
The Protocol Broker facilitates secure communication between the NextLabs PIP Plugin and PingFederate RP. This coordination consists of two parts:
- Communication between the NextLabs PIP Plugin and the Protocol Broker
- Communication between the Protocol Broker and the PingFederate RP server
10.5.1.1. Communication Between NextLabs PIP Plugin and Protocol Broker¶
The Protocol Broker’s doPost() method expects the following parameters:
- Requester
- SubjectId
- AttributeName
On successful receipt of a request, SAMLProxy uses the SoapHTTPTransmitter class to transmit the request to the PingFederate RP server. The response received from SOAPHTTPTransmitter is dispatched back to the NextLabs PIP Plugin, which then hands the result off to the PDP for policy evaluation and access decision making.
10.5.1.2. Communication Between Protocol Broker and PingFederate RP Server¶
The PingFederateRP and ProtocolBroker communicate using Assertion Query/Request Profile. As shown in Figure 10‑6, Protocol Broker initiates the secured communication on a mutual TLS channel with the Relying Party, and sends a signed SAML2 AttributeQuery. The message format and structure of the AttributeQuery is defined by SAMLCore Section 3.3.2.3. Binding for the profile is defined by SAMLBind Section 3.2.3. Processing rules governing the profile are provided by Section 3.3 of SAMLCore. In response, Protocol Broker expects a SAML response back.
OpenSAML is used to implement an Assertion Query/Request Profile. OpenSAML is a set of open source libraries meant to support developers working with Security Assertion Markup Language (SAML). The configuration required to use the OpenSAML library is provided in Section 10.5.2.2.
Figure 10‑6 Communication Between Plugin and Relying Party
Based on keystores and configuration read during initialization, SoapHTTPTransmitter creates a SAML2AttributeQuerBuilder class to build a Signed SAML 2.0 Attribute Query. Attribute names received earlier in the doPost() method are used to build the AttributeQuery. A SOAPSAML2 object is used to provide SOAP parameters for the SAML message created earlier. It reads SAML 2.0 metadata to find the location of the Attribute Authority end point. It uses HttpSOAPClient to dispatch the request to the end point using mutual TLS.
HTTPSoapClient is also responsible for receiving the Attribute response, verifying the signature and sending the attributes back to the Nextlab Plugin.
Figure 10‑7 Protocol Broker Interaction Diagram
Figure 10‑8 Protocol Broker Class Diagram
10.5.2. Deployment¶
10.5.2.1. System and Environment Requirements¶
The Protocol Broker is deployed on tomcat 8.0.22 on the SharePoint server, and uses OpenSAML 2.6.4.
10.5.2.2. Configuration¶
In order to accept traffic only on the channel protected by mutual TLS:
Install tomcat on the SharePoint server. The tomcat installation procedure is provided here.
Open the configuration file server.xml inside the configuration directory of the tomcat installation. Comment out the section:
<!-- <Connector port="8080" protocol="HTTP/1.1" connectionTimeout="20000" redirectPort="8443" /> -->
Update/insert the following line:
<Connector port="8443" protocol="org.apache.coyote.http11.Http11NioProtocol" maxThreads="150" SSLEnabled="true" scheme="https" secure="true" keystoreFile="C:\Users\<name>\Documents\softwares\tomcat\apache-tomcat-8.0.22\conf\abacTomcat.jks" keystorePass="…..password" clientAuth="true" sslProtocol="TLS" truststoreFile="C:\Users\sjha\Documents\softwares\tomcat\apache-tomcat-8.0.22\conf\truststore.jks" truststoreType="JKS" truststorePass="…password"/>
The configuration details for OpenSAML are provided here. In this demonstration, a folder called endorsed is created inside the lib directory of tomcat installation.
Add the following libraries to the endorsed folder created in the above step:
- xml-apis-2.10.0.jar
- xml-resolver-1.2.jar
- xercesImpl-2.10.0.jar
- xalan-2.7.1.jar
- serializer-2.10.0.jar
10.5.2.3. Preparation and Compilation¶
In our build, we used Apache Maven for Protocol Broker compilation. In order to prepare and compile the Protocol Broker, follow these steps:
10.5.2.3.1. Preparation¶
On the SharePoint server, click on the Windows icon and begin typing Cmd.
Double-click the icon to open the Command Prompt.
In the Command Prompt window, navigate to the folder where your pom.xml for the Protocol Broker exists, and press Enter. i.e., cd C:/software/java/samlNewPlugin/
Type the following command, then press Enter to prepare for compilation of the new Protocol Broker: .war file: mvn clean
Verify that your results are similar to the following, including the Build Success statement:
[INFO] Scanning for projects... [INFO] [INFO] ------------------------------------------------------------------------ [INFO] Building SAMLProxy 0.0.1-SNAPSHOT [INFO] ------------------------------------------------------------------------ [INFO] [INFO] --- maven-clean-plugin:2.5:clean (default-clean) @ SAMLProxy --- [INFO] Deleting /home/sjha/pdpPlugins/SAMLProxy/target [INFO] ------------------------------------------------------------------------ [INFO] BUILD SUCCESS [INFO] ------------------------------------------------------------------------ [INFO] Total time: 1.333 s [INFO] Finished at: 2015-06-29T10:24:27-04:00 [INFO] Final Memory: 5M/15M [INFO] ------------------------------------------------------------------------
10.5.2.3.2. Compiling the .war File¶
After following the instructions above to prepare for compiling, within the Command Prompt window, enter the following command and press Enter to create the Protocol Broker: .war file: mvn package
Verify that your results are similar to the following, including the Failures: 0 and Build Success portions:
[INFO] Scanning for projects... [INFO] [INFO] ------------------------------------------------------------------------ [INFO] Building SAMLProxy 0.0.1-SNAPSHOT [INFO] ------------------------------------------------------------------------ [INFO] [INFO] --- maven-resources-plugin:2.6:resources (default-resources) @ SAMLProxy --- [INFO] Using 'UTF-8' encoding to copy filtered resources. [INFO] Copying 9 resources [INFO] [INFO] --- maven-compiler-plugin:3.1:compile (default-compile) @ SAMLProxy --- [INFO] Nothing to compile - all classes are up to date [INFO] [INFO] --- maven-resources-plugin:2.6:testResources (default-testResources) @ SAMLProxy --- [INFO] Using 'UTF-8' encoding to copy filtered resources. [INFO] skip non existing resourceDirectory /home/sjha/pdpPlugins/SAMLProxy/src/test/resources [INFO] [INFO] --- maven-compiler-plugin:3.1:testCompile (default-testCompile) @ SAMLProxy --- [INFO] Nothing to compile - all classes are up to date [INFO] [INFO] --- maven-surefire-plugin:2.12.4:test (default-test) @ SAMLProxy --- [INFO] Surefire report directory: /home/sjha/pdpPlugins/SAMLProxy/target/surefire-reports ------------------------------------------------------- T E S T S ------------------------------------------------------- Running nist.pdpplugin.AppTest Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.03 sec Results : Tests run: 1, Failures: 0, Errors: 0, Skipped: 0 [INFO] [INFO] --- maven-war-plugin:2.6:war (default-war) @ SAMLProxy --- [INFO] Packaging webapp [INFO] Assembling webapp [SAMLProxy] in [/home/sjha/pdpPlugins/SAMLProxy/target/SAMLProxy-0.0.1-SNAPSHOT] [INFO] Processing war project [INFO] Copying webapp resources [/home/sjha/pdpPlugins/SAMLProxy/WebContent] [INFO] Webapp assembled in [440 msecs] [INFO] Building war: /home/sjha/pdpPlugins/SAMLProxy/target/SAMLProxy-0.0.1-SNAPSHOT.war [INFO] ------------------------------------------------------------------------ [INFO] BUILD SUCCESS [INFO] ------------------------------------------------------------------------ [INFO] Total time: 6.281 s [INFO] Finished at: 2015-06-29T10:27:14-04:00 [INFO] Final Memory: 11M/26M [INFO] ------------------------------------------------------------------------
10.5.3. Example SAML Request and Response Output¶
10.5.3.1. Example of Tomcat Output from our Build that Illustrates a SAML Request¶
<saml2p:AttributeQuery ID="_7a41be2e3d0d1abea13e857a80b3cfbc" IssueInstant="2015-05-26T18:14:39.405Z" Version="2.0" xmlns:saml2p="urn:oasis:names:tc:SAML:2.0:protocol" xmlns:soap11="http://schemas.xmlsoap.org/soap/envelope/">
<saml2:Issuer xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">urn:nccoe:abac:plugin</saml2:Issuer>
<ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
<ds:SignedInfo>
<ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
<ds:SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/>
<ds:Reference URI="#_7a41be2e3d0d1abea13e857a80b3cfbc">
<ds:Transforms>
<ds:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
<ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
</ds:Transforms>
<ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
<ds:DigestValue>hz3JxkkIsCL/BVlkRCrgUykjbho=</ds:DigestValue>
</ds:Reference>
</ds:SignedInfo>
<ds:SignatureValue>O8Gc8CSVKeYoNsR8bWaiExEpumeO2bLaMwlWC6LNaqf9ydvMPw/gcZbAEATCgK/RXVYgTe7ikYKKC80/GiO7NrUKZPO86ln5LINX5Gw5iTOeb6S4zUTWEfp2PQTfMSTB6rZe5OBuUDEpWfJ4T/3E1KpI4H7sxoaYhcZ3J2i1ZxPheMEJ0l4zvicAzlsefiirftn1vWirOdjub9VE0SicCl11FJB13Wla+c8JA5Nbbsnc3H6h5oDeapEOD9bX41KZtj2sGbh6k+F3vunYpd3m69KW6z8CJQeBWOcGCmDtt4Dyf/avG6Iz7o0PYjPYxFIvwslOYYU2QzLtOpHT8e/RRQ==</ds:SignatureValue>
<ds:KeyInfo>
<ds:KeyValue>
<ds:RSAKeyValue>
<ds:Modulus>uzxrL5iAIpNyEXHmGTDW1mzx7YJal/c9Ruxag3sifjzuUdBjEznFJJxaagM2pzTUI5JCaLzgm71V SBmuVL+6PzTxReM3i5XzWjpgRMIizadnQT0wmCryKuNaQiBIFLoMbi+ySdBvu+M/xhHlRxuFjY9N PSE1MHL8YaLoKW2SFIm/3bhJ/xF7q7FGHMcJH4Zzr2QpQmBEryozJJV3z4ZvVro/MfyLg1VER0pu
36e32hIyzsf2gKizv00qY2ecDlBCNTITsA2HWSTf50kpvT4qupCnXVKVqzDPZON0XCsJJcwWsUi9 pRvkGtVBXqhh282ODyzcl3nkpgsl5F8hR7kOjQ==</ds:Modulus>
<ds:Exponent>AQAB</ds:Exponent>
</ds:RSAKeyValue>
</ds:KeyValue>
</ds:KeyInfo>
</ds:Signature>
<saml2:Subject xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">
<saml2:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified">jdoe</saml2:NameID>
</saml2:Subject>
<saml2:Attribute Name="firstname" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion"/>
</saml2p:AttributeQuery>
10.5.3.2. Example of Tomcat Output from our Build that Illustrates a SAML Response¶
<?xml version="1.0" encoding="UTF-8"?>
<S11:Envelope xmlns:S11="http://schemas.xmlsoap.org/soap/envelo
pe/">
<S11:Body>
<samlp:Response xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" ID="LkF9NevJONpgbE56hszqbo2V
FZH" InResponseTo="_13caab0c0aa8b70946be278ff32376ad" IssueInstant="2015-06-29T14:46:35.617Z" Version="2.0">
<saml:Issuer xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">https://rp.abac.test:9031</saml:Issuer>
<samlp:Status>
<samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success"/>
</samlp:Status>
<saml:Assertion xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" ID="P-nmuwJENgb_aVjhd5DpY
dfN2IU" IssueInstant="2015-06-29T14:46:35.945Z" Version="2.0">
<saml:Issuer>https://rp.abac.test:9031</saml:Issuer>
<saml2:Subject xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion" xmlns:saml2p="urn:oasi
s:names:tc:SAML:2.0:protocol" xmlns:soap11="http://schemas.xmlsoap.org/soap/envelope/">
<saml2:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified">lsmith@ab ac.test</saml2:NameID>
</saml2:Subject>
<saml:Conditions NotBefore="2015-06-29T14:41:35.945Z" NotOnOrAfter="2015-06-29T14:51:35.9
45Z">
<saml:AudienceRestriction>
<saml:Audience>https://nextlabs-rp</saml:Audience>
</saml:AudienceRestriction>
</saml:Conditions>
<saml:AttributeStatement>
<saml:Attribute Name="stafflevel" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-for
mat:basic">
<saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://
www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">Junior</saml:AttributeValue>
</saml:Attribute>
</saml:AttributeStatement>
</saml:Assertion>
</samlp:Response>
</S11:Body>
</S11:Envelope>
10.6. Apache Directory Service (ApacheDS)¶
ApacheDS is included in Apache Directory Studio, which has multiple functionalities with ApacheDS Server, i.e., LDAP Browser, Schema Editor, Apache Configurator, LDIF Editor, Embedded ApacheDS, and ACI Editor.
10.6.1. Layout¶
Before installation, it is important to consider system needs and match them with the installation layout. The general layout for ApacheDS consists of two major concepts:
- Installation Layout: The installation is where all files essential to ApacheDS are stored, i.e., launch script, libraries, and a service wrapper (depending on the kind of installer used).
- Instance Layout: ApacheDS is built to run multiple instances of the server at the same time, which means that an optional instances folder can be found in the installation layout (or elsewhere on the disk, depending on the platform). In that folder you will find one or multiple directories, all sharing the same layout, corresponding to all ApacheDS instances (one directory per instance, with names corresponding to the ID of the instance).
A detailed discussion of these concepts can be found here.
10.6.2. Download¶
ApacheDS can be downloaded as binary or as source, and compiled on a given platform. Source can be downloaded here.
In this project, ApacheDS was downloaded as a packaged Windows installer from this location. Native installers are available in the following formats, and their download links are available at following site.
Platform | Installer Format |
---|---|
Window | Exe |
Mac OS X | Dmg |
Debian | Deb |
Linux | Rpm,bin |
- At the download location, you will see a URL as shown in the example below. Click the link above to download Apache Directory Server for Windows.
Figure 10‑9 ApacheDS Download
During the software download, different installation graphics will be displayed depending on which browser you use. Example from Windows Internet Explorer:
10.6.2.1. Verify the Integrity of the Downloaded File¶
It is essential to verify the integrity of the file when the download completes.
The file’s integrity can be verified with PGP signatures using PGP or GPG. First, download the KEYS and the *asc* signature file for the relevant distribution. Both KEYS and asc can be found to the right of the download link, as shown in Figure 10‑9 above.
Verify the signatures using the following commands in the Command Prompt:
$ pgpk -a KEYS
$ pgpv apacheds-2.0.0-M20.exe.asc
or
$ pgp -ka KEYS
$ pgp apacheds-2.0.0-M20.exe.asc
or
$ gpg --import KEYS
$ gpg --verify apacheds-2.0.0-M20.exe.asc
Alternatively, you can verify the MD5 signature on the files. A Unix program called md5 or md5sum is included in many Unix distributions. It is also available as part of GNU Textutils. Windows users can get binary md5 programs from here, here, or here.
10.6.3. Installation¶
Note: To install ApacheDS as a Windows service, you need administrative privileges. We installed ApacheDS on Windows Server 2012. The ApacheDS installation procedure for other operating systems can be found here.
Once ApacheDS is downloaded and verified, double-click the installer to open it. Note: It may have already been opened by your web browser.
When the following screen appears, click Next.
Review the License agreement and click I Agree.
The next screen prompts you for the install path. In our build, we left the default install path. Specify an install path of your choosing, and click Next.
Specify a location for storing ApacheDS instances, then click Next.
The next screen asks for the location of your java run time. It is assumed, based on the earlier description in Section 10.8.2, that users will have the proper java environment prior to attempting to install ApacheDS. Users who have no JRE installed should abandon the install by clicking Cancel. Install the JRE and re-run the ApacheDS install. We accepted the default as shown.
Click Install. Once the installation is complete, you will receive the following prompt:
10.6.3.1. Functional Test of the ApacheDS Installation¶
Click Show Details in above diagram to see details of installation. Make sure all of the folders exist, then click Next.
Click Finish to end the installation.
Click Yes to start the ApacheDS server. Instructions are provided in Section 10.6.2.
10.6.4. Starting and Stopping the Server¶
The server can be started and stopped with the Windows Services manager (Control Panel > Administrative Tools > Services). The user must have administrative privileges.
From here, ApacheDS can be started, stopped, or restarted.
The process for starting and stopping ApacheDS on other operating systems is described here.
10.7. PingFederate - Apache Integration¶
This section requires knowledge of the following pieces of information:
- Server IP address or hostname
- Server port where it is listening on
- Server credentials (i.e., private key and certificate) to be provisioned on directory server
10.7.1. Provisioning of Server Credential¶
Start Apache Directory Server Studio and open a new connection.
10.7.1.1. Creation of Server Connection¶
To create a new LDAPS connection, complete the following steps:
Once a new connection is opened, the following screen appears. Fill in Hostname and Port. Select the encryption method Use SSL encryption(ldaps://), then click Next.
Option | Description | Default |
---|---|---|
Connection name | The name of the connection. In the Connections view, the connection is listed with this name. The name must be unique. | empty |
Hostname | The hostname or IP address of the LDAP server. A history of recently used hostnames is available through the drop-down list. | empty |
Port | The port of the LDAP server. The default port for non-encyrpted connections is 389. The default port for ldaps:// connections is 636. A history of recently used ports is available through the drop-down list. | 10636 |
Encryption method | The encryption to use. Possible values are: No encryption, ldaps:// and StartTLS extension. | No encryption |
Provider | Option to choose either JNDI or Apache Directory LDAP client API | |
Check network parameter | Use this function if you want validate that the entered information is correct, and the server is reachable. | |
Read-Only | If this option is chosen, any attempts to modify will return an error. |
Option | Description | Default |
---|---|---|
Authentication Method | Select your authentication method:
|
Simple Authentication |
Bind DN or user | The distinguished name or user ID used to bind. Previously entered DNs can be selected from drop-down list. | empty |
Bind Password | The password used to bind. | empty |
Save password | If checked, the password will be saved in configuration. If not checked, you must enter the password whenever you connect to the server. Warning: The password is saved as plain text. | checked |
Check Authentication | Use this function to attempt a connection plus a bind to the host upon completion of the wizard. It will validate that the entered information is correct. |
Option | Description | Default |
---|---|---|
Get base DNs from Root DSE | If checked, the base DNs are fetched from the namingContexts attribute of the Root DSE. | checked |
Fetch Base DNs | Use this function to get the namingContext values from the Root DSE. The returned values will appear in the Base DN drop-down list. | |
Base DN | The Base DN to use. You may enter a DN manually or select one from the drop-down list. This field is only enabled if the option Get base DNs from root DSE is off. | empty |
Count Limit | Maximum number of entries returned from the server when browsing the directory. It is also used as default value when searching the directory. A value of 0 means no count limit. Note that this value is a client-side value. It is also possible to use a server-side limit. | 1000 |
Time Limit | The maximum time in seconds the server searches for results. This is used as default value when browsing or searching the directory. A value of 0 means no limit. Note that this value is a client-side value. It is also possible to use a server-side limit. | 0 |
Alias Dereferencing | Specifies whether aliases should be dereferenced while finding the search base entry, when performing the search, or both. To manage (create, modify, delete) alias objects you must uncheck both options. | Both finding and searching |
Referrals Handling | Specifies the referral handling.
|
Follow Referrals manually |
Use ManageDsaIT control while browsing | If enabled, the ManageDsaIT control is sent to the server in each request. This signals the directory server not to send referrals and search continuations, but return the special referral objects. Note: This is only applicable if the directory server supports the ManageDsaIT control. | unchecked |
Fetch subentries while browsing | If enabled, both normal and subentries according to RFC 3672 are fetched. This causes additional search requests while browsing the directory. | unchecked |
Paged Search | If enabled, the simple paged result control is used while browsing the directory. With page size you can define how many entries should be retrieved in one request. If Scroll Mode is enabled, only one page is fetched from the server at a time. While browsing, you can scroll through the pages by using next page and top page. If disabled, all entries are fetched from the server. The paged result control is only used in the background to avoid server-side limits. | unchecked |
Fetch operational attributes while browsing | If enabled, both user attributes and operational attributes are retrieved while browsing. If the server supports the feature All Operational Attributes, use + to retrieve operational attributes. Otherwise, all operational attributes defined in the schema are requested. | unchecked |
Option | Description | Default |
---|---|---|
Modify Mode | Specify the modify mode for attributes with an equality matching rule. Options:
|
Optimized Modify Operations |
Modify Mode (no equality matching rule) | Specify the modify mode for attributes with no equality matching rule. Options:
Recommended values for various LDAP servers:
|
Optimized Modify Operations |
Modify Order | Specify the modify order when using add and delete operations. | Delete first |
Go to Open Configuration for the newly created connection.
Property | Default Value | Description |
---|---|---|
keystoreFile | none | Path of the X509 (or JKS) certificate file for LDAPS |
certificatePassword | changeit | Password used to load the LDAPS certificate file |
port | 10636 | LDAPS TCP/IP port number to listen to |
enableSSL | true | Sets if SSL is enabled or not |
- Make sure Enable LDAPS Server is checked, and Port is the same as provided during creation of the connection.
- Go to SSL/Start TLS Keystore.
- Provide the location of the Keystore file and the password for the certificate.
- Save the configuration.
- Restart the server.
10.7.1.2. Verification¶
OpenSSL was used to acquire the server public certificate.
>openssl s_client -showcerts -connect 10.33.7.8:10636 < /dev/null | openssl x509 -outform PEM > dir.pem
depth=0 C = US, O = ASF, OU = Directory, CN = battlefield.bb-abac-bb1.nccoe.lab
verify error:num=20:unable to get local issuer certificate
verify return:1
depth=0 C = US, O = ASF, OU = Directory, CN = battlefield.bb-abac-bb1.nccoe.lab
verify error:num=27:certificate not trusted
verify return:1
depth=0 C = US, O = ASF, OU = Directory, CN = battlefield.bb-abac-bb1.nccoe.lab
verify error:num=21:unable to verify the first certificate
verify return:1
DONE
[sjha@battlefield ~]$ more dir.pem
-----BEGIN CERTIFICATE-----
MIIBjDCCATYCBgFMlJE24DANBgkqhkiG9w0BAQUFADBCMQswCQYDVQQGEwJVUzEM
MAoGA1UEChMDQVNGMRIwEAYDVQQLEwlEaXJlY3RvcnkxETAPBgNVBAMTCEFwYWNo
ZURTMB4XDTE1MDQwNzE1NDgwN1oXDTE2MDQwNjE1NDgwN1owWzELMAkGA1UEBhMC
VVMxDDAKBgNVBAoTA0FTRjESMBAGA1UECxMJRGlyZWN0b3J5MSowKAYDVQQDEyFi
YXR0bGVmaWVsZC5iYi1hYmFjLWJiMS5uY2NvZS5sYWIwXDANBgkqhkiG9w0BAQEF
AANLADBIAkEAlLYJY8PJgMS82IqrW4uTVobkNqi2oJBoFAvOGMF7olPCQ4x5vrgS
6GEq9gUHk1ZZzymIIq6BMxoEb80l6lPY/wIDAQABMA0GCSqGSIb3DQEBBQUAA0EA
hXNpaGfF2Aboemwzt6U/fvSNyl+KRdeKFm0liWbseBk8OPvdOEmW96HVLvlbxSlc
JpSznkLFhFOe0fimwB6GEg==
-----END CERTIFICATE-----
- Verify the certificate received from the directory server against the certificate that was loaded earlier.
10.7.1.3. Configuration Steps on PingFederate RP Server¶
The following screen will appear, displaying all certificates on the server’s global trust list.
Select Import Certificate.
Choose a file to import.
Once your chosen file appears in the Filename field, click Next.
View the Summary of the imported certificate.
Click Done. The main screen will display a list of certificates. Click Save.
10.7.1.3.1. Creation of Data Store to Connect to ApacheDS¶
Click on Data Stores.
In the Manage Data Stores window, click Add New Data Store.
Choose LDAP, and click Next.
Provide a Hostname and Ldaptype.
It may be necessary to configure connection pooling. It is important to select Verify LDAPS Hostname if the directory server certificate is bound to a hostname, and this hostname can be verified.
If there is any binary data, enter it in the Binary Attribute Name Field, and click Add.
A summary of the LDAP configuration will appear.
A Summary of the connection will appear as following. Click Save. You will then return to the Main Admin console.
10.8. Configuration of PingFederate to Query the JIT Cache when Responding to Secondary Attribute Requests¶
10.8.1. Introduction¶
This section will cover all the configuration steps required to enable PingFederate RP to communicate with the Secondary attribute Provider and respond to its queries. The SP connection section will cover communication channel protection and message protection. To fulfill the query request from the NextLabs PIP Plugin and Protocol Broker, PingFederate queries its local LDAP server called Just in Time (JIT) cache. Note that PingFederate RP may not have data to fulfill the query. In that case, PingFederate RP extends the query to PingFederate IdP using a unique method (Ping Data source).
A Data Store is any type of source for digitized data, i.e., database, file, stream, etc. PingFederate administration console uses this term for system settings. In the Java software platform, data source is a factory for connections to the physical data source that this data source object represents. Thus, data source is the logical manifestation of a physical data store in a java application. Due to this, the terms will be used interchangeably below.
This section provides the configuration needed to query JIT cache, i.e., creation of the data source for the LDAP Server. We have already discussed the configuration of Ping Data Source in Custom Data Store section. SP connection describes how both of these data stores are chained together to fetch the result of the attribute query.
10.8.2. Prerequisites¶
Before starting this configuration, the following steps must have already been completed:
10.8.2.1. SP Connection¶
As described above, PingFederate (RP) acts as an IdP for the Secondary attribute provider. In order to enable support for exchange of federation-protocol messages and provide channel protection, it is essential to configure the SP (Service Provider) connection. Note: Ping Identity’s documentation uses the term Service Provider and SP where the rest of our ABAC documentation uses the term Relying Party and RP. In this document, please consider these terms interchangeable.
The following goals are achieved by configuration of the SP connection:
- Specification of connection and associated security protocol (i.e., TLS/SSL)
- Specification of SAML profile t including detailed security specifications (the use of digital signatures, signature verification, XML encryption)
- Specification of Attributes that may be sent using the SAML2 Attribute Query profile
- Specification of Data Store(s), if agreement between Idp and SP includes sending a SAML response containing attribute values from a local data store
10.8.2.1.1. Specification of Profile¶
Instructions on how to create a new connection can be found here.
Click on Manage on All SP in the first column on the left hand side.
The following screen will appear. Click on Create Connection.
Check the box for Browser SSO Profiles and select SAML 2.0 as protocol from the drop-down menu.
Uncheck Browser SSO, check Attribute Query, and click Next.
Choose a metadata file and click Next.
SAML2 metadata has its own specification. As per this specification, KeyDescriptor is an optional sequence of elements that provides information about the cryptographic keys that the entity uses when acting in this role. However, for message authentication and integrity, it is essential to provide the certificate so that signed messages coming from the secondary attribute provider can be verified. A relevant part of metadata is shown here:
<md:KeyDescriptor use="signing">
<ds:KeyInfo>
<ds:X509Data>
<ds:X509Certificate>
MIIE4jCCAsqgAwIBAgICEAMwDQYJKoZIhvcNAQELBQAwYjELMAkGA1UEBhMCVVMx ETAPBgNVBAgMCE1hcnlsYW5kMRIwEAYDVQQHDAlSb2NrdmlsbGUxDjAMBgNVBAoM BU5DQ29FMQ0wCwYDVQQLDARBQkFDMQ0wCwYDVQQDDARBQkFDMB4XDTE1MDQwMTE4
MTA1NloXDTE2MDMzMTE4MTA1NlowejELMAkGA1UEBhMCVVMxETAPBgNVBAgMCE1h cnlsYW5kMQ4wDAYDVQQKDAVOQ0NvRTENMAsGA1UECwwEQUJBQzEUMBIGA1UEAwwL TU0xOTU1OTItUEMxIzAhBgkqhkiG9w0BCQEWFHNqaGFATU0xOTU1OTItUEMub3Jn
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAuzxrL5iAIpNyEXHmGTDW 1mzx7YJal/c9Ruxag3sifjzuUdBjEznFJJxaagM2pzTUI5JCaLzgm71VSBmuVL+6 PzTxReM3i5XzWjpgRMIizadnQT0wmCryKuNaQiBIFLoMbi+ySdBvu+M/xhHlRxuF
jY9NPSE1MHL8YaLoKW2SFIm/3bhJ/xF7q7FGHMcJH4Zzr2QpQmBEryozJJV3z4Zv Vro/MfyLg1VER0pu36e32hIyzsf2gKizv00qY2ecDlBCNTITsA2HWSTf50kpvT4q upCnXVKVqzDPZON0XCsJJcwWsUi9pRvkGtVBXqhh282ODyzcl3nkpgsl5F8hR7kO
jQIDAQABo4GJMIGGMAkGA1UdEwQCMAAwCwYDVR0PBAQDAgXgMCwGCWCGSAGG+EIB DQQfFh1PcGVuU1NMIEdlbmVyYXRlZCBDZXJ0aWZpY2F0ZTAdBgNVHQ4EFgQURPRr 8BNghnDip40B1sy6AWpWJmcwHwYDVR0jBBgwFoAUyZ5WFPtCW/BOjVxvof8eNcBo
5c8wDQYJKoZIhvcNAQELBQADggIBAGhVMd47uFNi1z8oEYgwDInZDAtfujvkfTu2 Dtr7dvkvB2x6uW481ffIKDKb48yKVBMO0kSwU4esPHgMWowJJs37XFo9PYJ1kaE/ NCD7e8V4p3xhzXux6JqKpaho1xHifzEsdKqOyNj00ZXqmRMstbw6UC+IFCNUWJZQ
zJ+Dwciaxa9kq/huv8BMbYzcL8r1fE3x9nUwwwuFuXudpnED0B+Rmmod1G5fVG1j agMWakXscGJ9rpT8wgfJGjU4Sct3Eocp5roRGopUVBrW6jljZD4dYEu1eJ1LJqcW mDiYdZIvu0z393HApNpwC4XSaMoTN7xq4Z+Xwe0zdt1HVM0aeAiglrDB3XKuiYQT
Ab899WBgK/TixTLJ+Nf6FkAl2apkVkaxxl+35DZrkDOHo3HQTORQFNYcb1LlrsfP A5r0PPVi6XE6h4k9/CgO03Q6fzpgl7avCrw8s1m/WnmQjfc0K+op7l7zsYrnsxdB wQsnaT6GX2csy99jOpfLKlSh6jaIuFdRPMEwjhNyqTy2xoLfuYK5bxMzlpfaoZEs
sVURPCFiC0G97xn8ffjjhv5Kby8JIRWV2QhXicf5FsWoiWZIHtHo0L9WEQXKPTO1 +831OxJDW6bosdNww8IbRft1MYqGWYCTnwmBshURCXSJrjpE/MInE5nw/7QWA/OR U3r4Pv6s
</ds:X509Certificate>
</ds:X509Data>
</ds:KeyInfo>
</md:KeyDescriptor>
Verify the metadata content.
Click on Configure Attribute Query Profile.
Specify the list of attributes that may be returned to the SP in response to an attribute request.
10.8.2.1.2. Specify a series of data stores.¶
In the Attribute Source Id field, specify JIT (LDAP).
Specify Attributes for the JIT Cache.
Specify LDAP Filter.
Verify that your data is correct.
Specify a custom Data Store.
Define a filter for extracting data from this data store.
Based on the data elements available from this data store, select the ones pertinent to this connection. Note that these are the attributes you previously selected to return from Ping Custom Data.
Click Retrieve.
Click on Attribute Mapping Fulfillment.
Issuance Criteria: PingFederate can evaluate various criteria to determine whether to issue an attribute query response. Use this optional screen to configure the criteria for use with this conditional authorization.
Click on Security Policy.
Check the Summary.
Provide Credentials for the back channel attribute request.
Specify Inbound Back-Channel Authentication and Digital Signature on the message.
10.8.2.1.3. Back Channel Authentication Configuration¶
Use the default Transport Layer Authentication with SSL Client Certificate.
It is encouraged to use the Anchored verification method.
You will be prompted to select an SSL Verification Certificate. In our build, a certificate has not been previously imported. Click on Manage Certificate.
Click Import.
Click Choose File.
Select your certificate file from the Explorer window.
The file name will appear in the Filename field.
Click Next. This will display details of parts of certificate.
Check Make this the active certificate and click Done.
Verify the certificate.
Under Action, select Activate.
View a Summary of the verification.
Return to the Back Channel Authentication tab.
Select Digital Signature Settings for outgoing messages, then click Next.
Go to Digital Signature settings. Click Configure.
Select Digital Signature Settings on incoming messages.
Click on Manage Signature Verification Settings.
Select the certificate(s) to use when verifying these digital signatures. When multiple certificates are chosen, each certificate is tried from the top of the list down until the signature is verified. It is assumed that signed certificates have already been imported. If not, click on Manage Certificate and complete the steps detailed earlier for importing a certificate.
Verify the Summary.
This completes the signature verification credential settings.
Verify the Summary.
Activate the connection and Save.
Save again.
10.8.2.2. IDP Connection¶
As an SP, you are making a connection to a partner IdP. Follow these steps to select the type of connection needed for this IdP:
On the right hand side of the administrative console, click Manage All IdP under IdP Connections.
Open the connection that was created in Section 6. Click on Connection Option. It my default to Browser SSO. Additionally, select Attribute Query and JIT Provisioning.
Click Next. Verify that the information in the General Info tab is correct.
Click Next.
Click on Configure Attribute Query Profile.
Specify an Attribute Authority Service URL.
Attributes requested by your application may not match exactly the attributes supplied by the IdP. Specify the mapping between these sets of attributes.
Select Sign the Attribute Query.
Verify that the Summary is correct, then click Done.
When the following screen appears, click Next.
JIT provisioning details have been provided by PingFederate here.
Save the configuration.
Select Application Authentication.
Enter appid in the ID field, and use the shared secret that you input during custom data store configuration, then save the configuration.
Select Browser SSO and Attribute Query.
10.9. ApacheDS Schema Extension¶
At a high level, LDAP Schema is the collection of attribute type definitions, object class definitions, and other information which a server uses to determine how to match a filter or attribute value assertion (in a compare operation) against the attributes of an entry, and whether to permit add and modify operations. For a more formal definition, look into Section 4.1 of RFC 4512.
ApacheDS comes with a comprehensive set of predefined, standardized schema elements. Specification of many of these elements can be found in RFC 4519. Generally, these predefined schema satisfy most of the needs of a project. However, you may sometimes be required to define additional attributes or object classes that are not included in the server provided schema.
Each attribute and object class has an associated unique Object Identifier. Generally, An Object Identifier is a tree of nodes where each node is simply a sequence of digits. The rules roughly state that once an entity is assigned a node in the Object Identifier (OID) tree, it has sole discretion to further delegate sub-trees off of that node. Some examples of OIDs include: 1.3.6.1 - the Internet OID, 1.3.6.1.4.1 - IANA-assigned company OIDs. It is formally defined using the ITU-T’s ASN.1 standard, X.690.
The IANA OID registry contains a list of registered entities that use OIDs to reference internal structures. In this section, we have used OIDs that are not registered anywhere. For this reason, we are using the subtree 2.25, as per recommendation by ITU. UUID is generated by the program found here.
In the following section, we will demonstrate how to create an attribute. Similar procedures can be used to create many attributes and object classes.
10.9.1. Pre-Requisites¶
For Schema extension, this project used ApacheDS studio. ApacheDS installation and configuration is detailed in Section 10.6 of this guide.
10.9.2. Procedure¶
Start ApacheDS Studio from the Start menu.
The following screen will appear:
Select File > New.
Select the New Schema Project wizard.
Specify a Project name, i.e., nist.nccoe.abac in our build.
Select Offline Schema, then click Next. On the next screen, Choose the ‘core’ schemas to include.
Click File > New and select New Schema.
Specify a Schema name, i.e., nist.nccoe.abac in our build.
The following screen will appear:
Select Attribute Types > New > New Attribute Type.
In the new window, choose the OID from the previous instructions.
Click Next to choose the superior type of this attribute.
Specify Matching Rules. Since it is a string, case insensitivity is chosen in our build.
The following screen will appear:
You can create other attributes by following process described above.
Export the schema by selecting Export > Schemas for ApacheDS. It will create an LDIF file.
LDIF files are specified by their own RFC. In a text editor, it displays as following:
To import the file, first select Window > Open Perspective > LDAP.
Click on the left bottom corner of the window and select New Connection.
Fill in the network parameters and click Next.
Provide credentials and click Finish.
Open Schema Editor Browser and import the LDIF file created in
10.10. Functional Tests¶
Once all requirements have been met and all steps in this How-To Guide have been executed, a few functional tests will ensure that the key components of this How-To Guide were correctly deployed and are communicating with other ABAC components as desired.
The first functional test will check the ready state of the NextLabs Policy Controller (ensures that it is running after being paused for plugin deployment).
The second test will check that the plugin was successfully loaded into the NextLabs software architecture, that an attribute request is sent to the Protocol Broker from the NextLabs PIP plugin’s getAttribute() function, and that the Protocol Broker responds with an expected attribute value.
The second functional test will ensure that the Protocol Broker is successfully loaded and deployed within the tomcat server instance.
Both of these functional tests can be done on the SharePoint server.
10.10.1. Testing the Ready State of the NextLabs Policy Controller Service¶
Click on the Windows icon and begin typing the word Services.
When the Services application icon appears, double-click to open the Services application.
Within the Services application window, click on the Name column and look for Control Center Enforcer Service.
Verify that the status column reads Running.
10.10.2. Test the Successful Loading of the Custom Plugin Within the NextLabs Policy Controller Software Architecture¶
Click on the Windows icon.
Begin typing Windows Explorer.
Click on the Windows Explorer application icon.
Navigate to C:/Program Files/NextLabs/Policy Controller/agentLog/.
Within the agentLog folder, note the Agentlog0.0 file.
Within the agentLog folder, copy and paste the locked file Agentlog0.log0 to open it for review.
- Left-click on the file name, and hold down Ctrl+C.
- Left-click anywhere in the agentLog folder, right-click and hold down Ctrl+V.
Double-click the Agent0.log-Copy.0 file to open it in your default text editor.
Within your default text editor, use a search function to search for standard NextLabs logging terminology to verify that the plugin was loaded correctly. Example:
Jul 13, 2015 4:59:21 PM com.bluejungle.pf.domain.destiny.serviceprovider.c A FINE: Loading C:\Program Files\NextLabs\Policy Controller\.\jservice\config\nlsamlpluginService.properties Jul 13, 2015 4:59:21 PM com.bluejungle.pf.domain.destiny.serviceprovider.c A FINE: Loading C:\Program Files\NextLabs/Policy Controller/jservice/jar/nlsamlplugin/NLSAMLPlugin-0.0.1-SNAPSHOT-jar-with-dependencies.jar Jul 13, 2015 4:59:22 PM com.bluejungle.pf.domain.destiny.serviceprovider.ServiceProviderManager register INFO: A new Service 'NLSAMLPlugin_Service' is registered.
Within your default text editor, use a search function to search for logging statements you included in your plugin code to verify that the init() methods are called while the jar is loaded within NextLabs (standard according to NextLabs support). Example:
Jul 13, 2015 4:59:21 PM gov.nist.NLSAMLPlugin.UserAttrProviderMod init INFO: NLSAMLPlugin UserAttrProviderMod code -- init method Jul 13, 2015 4:59:21 PM gov.nist.NLSAMLPlugin.HTTPSTransmitter init You can copy and paste the locked file, or keep a live annotating tool open that will display the contents of Agent0.log0 as new log statements are recorded. Example from this implementation: **BareTail by Bare Metal Software Pty Ltd.** Example screenshot using BareTail to open the **Agent0.log0** file, with optional highlighting illustrating evaluated policies in yellow: |image859|
10.10.3. Testing That the Protocol Broker .war File Loads Correctly in Tomcat Server¶
On the SharePoint Server, open Services, and ensure that the Control Center Enforcer Service is listed as Running.
Using Windows Explorer, navigate to your Apache tomcat installation within the Windows file structure. Example: C: /software/apache-tomcat-7.0.61
Double-click to open the bin folder. Example: C:/software/apache-tomcat-7.0.61/bin
Double-click startup.bat to start the bat, and wait for startup to complete.
From any computer connected to this network, open an internet browser.
In the address field, type https://sharepoint.abac.test/ and press Enter.
Choose Federated Logon from the drop-down menu.
At the login screen, enter the credentials of a user that exists in your IdP Active Directory (Section 2), and click Sign On.
Verify that the user was able to access the main page of the RP’s SharePoint. Example:
In the SharePoint site, double-click on an object for which you know the user will be missing an attribute in order to be granted access, but that can be retrieved via a secondary attribute request using the NextLabs PIP plugin, Protocol broker, and Ping custom data store.
Follow the remaining steps 15-18 to verify through standard and custom logging that the Protocol Broker was loaded, that the getAttribute() from the NextLabs PIP plugin was sent, and an expected attribute value was returned.
In Windows Explorer, navigate to your installation of Apache tomcat and locate its log files, i.e., C:/software/apache-tomcat-7.0.61/logs
Open a catalina.___.log file using your default text editor and use a search function to find standard Apache tomcat logging that indicates the .war file was correctly deployed and loads without error. For example, in C:/software/apache-tomcat-7.0.61/logs/catalina.2015-06-29.log:
Jun 29, 2015 1:49:16 PM org.apache.catalina.startup.VersionLoggerListener log INFO: Server version: Apache Tomcat/7.0.61 Jun 29, 2015 1:49:16 PM org.apache.catalina.startup.VersionLoggerListener log Jun 29, 2015 1:49:16 PM org.apache.catalina.startup.VersionLoggerListener log INFO: CATALINA_BASE: C:\software\java\samlNewPlugin\apache-tomcat-7.0.61 Jun 29, 2015 1:49:16 PM org.apache.catalina.startup.VersionLoggerListener log INFO: CATALINA_HOME: C:\software\java\samlNewPlugin\apache-tomcat-7.0.61 Jun 29, 2015 1:49:16 PM org.apache.catalina.startup.VersionLoggerListener log INFO: Command line argument: -Djava.util.logging.config.file=C:\software\java\samlNewPlugin\apache-tomcat-7.0.61\conf\logging.properties Jun 29, 2015 1:49:16 PM org.apache.catalina.startup.VersionLoggerListener log INFO: Command line argument: -Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManager Jun 29, 2015 1:49:16 PM org.apache.catalina.startup.VersionLoggerListener log INFO: Command line argument: -Djava.endorsed.dirs=C:\software\java\samlNewPlugin\apache-tomcat-7.0.61\endorsed Jun 29, 2015 1:49:17 PM org.apache.catalina.startup.HostConfig deployWAR INFO: Deploying web application archive C:\software\java\samlNewPlugin\apache-tomcat-7.0.61\webapps\SAMLProxy-0.0.1-SNAPSHOT.war Jun 29, 2015 1:49:22 PM org.apache.catalina.startup.HostConfig deployWAR INFO: Deployment of web application archive C:\software\java\samlNewPlugin\apache-tomcat-7.0.61\webapps\SAMLProxy-0.0.1-SNAPSHOT.war has finished in 4,953 ms Jun 29, 2015 1:49:22 PM org.apache.catalina.startup.HostConfig deployDirectory INFO: Deploying web application directory C:\software\java\samlNewPlugin\apache-tomcat-7.0.61\webapps\docs Jun 29, 2015 1:49:22 PM org.apache.catalina.startup.HostConfig deployDirectory INFO: Deployment of web application directory C:\software\java\samlNewPlugin\apache-tomcat-7.0.61\webapps\docs has finished in 78 ms Jun 29, 2015 1:49:22 PM org.apache.catalina.startup.HostConfig deployDirectory INFO: Deploying web application directory C:\software\java\samlNewPlugin\apache-tomcat-7.0.61\webapps\examples Jun 29, 2015 1:49:22 PM org.apache.catalina.startup.HostConfig deployDirectory INFO: Deployment of web application directory C:\software\java\samlNewPlugin\apache-tomcat-7.0.61\webapps\examples has finished in 547 ms Jun 29, 2015 1:49:22 PM org.apache.catalina.startup.HostConfig deployDirectory INFO: Deploying web application directory C:\software\java\samlNewPlugin\apache-tomcat-7.0.61\webapps\host-manager Jun 29, 2015 1:49:23 PM org.apache.catalina.startup.HostConfig deployDirectory INFO: Deployment of web application directory C:\software\java\samlNewPlugin\apache-tomcat-7.0.61\webapps\host-manager has finished in 141 ms
While the same file is open, use another search function to find custom logging that indicates that the Protocol Broker was used for a SAML Attribute query request and response. Example custom log files from this build:
Jun 29, 2015 1:59:00 PM nist.pdpplugin.transport.SoapHTTPTransmitter transmit INFO: START SoapHTTPTransmitter method. Start time: 1435600740151 Jun 29, 2015 1:59:08 PM nist.pdpplugin.transport.SoapHTTPTransmitter transmit INFO: START SoapHTTPTransmitter method. Start time: 1435600748229 Jun 29, 2015 1:59:11 PM nist.pdpplugin.transport.SoapHTTPTransmitter transmit INFO: END SoapHTTPTransmitter transmit Method: 1435600751682 Jun 29, 2015 1:59:11 PM nist.pdpplugin.transport.SoapHTTPTransmitter transmit INFO: END SoapHTTPTransmitter transmit Method. Total Execution time: 11531
Within the Agent0.log0, another search function to find custom logging statements that verify from within the NextLabs Policy Controller software execution side that the plugin’s getAttribute() function was called and that the requested attribute was returned.
Example from this build:
- user: schen@abac.test
- requested attribute: clearance
- expected returned value: Secret
- actual returned value: Secret
Jun 3, 2015 11:39:17 AM gov.nist.NLSAMLPlugin.UserAttrProviderMod getAttribute INFO: NLSAMLPlugin UserAttrProviderMod getAttribute() function called. Jun 3, 2015 11:39:17 AM gov.nist.NLSAMLPlugin.UserAttrProviderMod getAttribute INFO: START getAttribute method. Start time: 1433345957517 Jun 3, 2015 11:39:17 AM gov.nist.NLSAMLPlugin.UserAttrProviderMod getAttribute INFO: NLSAMLPlugin UserAttrProviderMod getAttribute Line00-72 - subjectID param: schen@abac.test Jun 3, 2015 11:39:17 AM gov.nist.NLSAMLPlugin.UserAttrProviderMod getAttribute INFO: NLSAMLPlugin UserAttrProviderMod getAttribute Line00-73 - attributeName param: clearance Jun 3, 2015 11:39:17 AM gov.nist.NLSAMLPlugin.UserAttrProviderMod getAttribute INFO: NLSAMLPlugin Trying to check if there exist a prior entry in cache. -- UserAttrProviderMod Line00-79 Jun 3, 2015 11:39:17 AM gov.nist.NLSAMLPlugin.UserAttrProviderMod getAttribute INFO: NLSAMLPlugin Using soapHTTPTransmitter object and calling its transmit() function. Jun 3, 2015 11:39:22 AM gov.nist.NLSAMLPlugin.UserAttrProviderMod getAttribute INFO: NLSAMLPlugin UserAttrProviderMod getAttribute() Line00-114 -- attributeValue returned: Secret