ClearPass Extension Universal Authentication Proxy TechNote ClearPass Extension Universal Authentication Proxy ClearPass TechNote ClearPass Extension Universal Authentication Proxy - TechNote 1
ClearPass Extension Universal Authentication Proxy TechNote Change Log Version Date Modified By Comments 0.1 Mar 2017 Danny Jump Initial Draft Version for internal review 0.2 May 2017 Robert Filer Wordsmith and minor edits 1.0 May 2017 Danny Jump First Published Version Copyright Copyright 2017 Hewlett Packard Enterprise Development LP. Open Source Code This product includes code licensed under the GNU General Public License, the GNU Lesser General Public License, and/or certain other open source licenses. A complete machine-readable copy of the source code corresponding to such code is available upon request. This offer is valid to anyone in receipt of this information and shall expire three years following the date of the final distribution of this product version by Hewlett- Packard Company. To obtain such source code, send a check or money order in the amount of US $10.00 to: Hewlett-Packard Company Attn: General Counsel 3000 Hanover Street Palo Alto, CA 94304 USA Please specify the product and version for which you are requesting source code. You may also request a copy of this source code free of charge at HPE-Aruba-gplquery@hpe.com. ClearPass Extension Universal Authentication Proxy - TechNote 2
ClearPass Extension Universal Authentication Proxy TechNote Contents Introduction and Overview... 5 Software Requirements... 5 ClearPass Installation and Deployment Guide... 5 ClearPass Extensions... 5 Pictorial View of the Integration... 6 UAP Extension Installation and Configuration... 7 Create an Extension API Operator Profile... 7 Create an API Client... 8 Generate an Access Token... 9 Go to the Extension APIs... 10 Install the Extension... 12 Query Extension after Installation... 13 Configure the Extension... 15 Example of an OAuth2 Configuration ClearPass to ClearPass... 17 Install UAP Extension... 17 Configure UAP Extension... 17 ClearPass Extension Universal Authentication Proxy - TechNote 3
Figures Figure 1: Context-Server with Basic HTTP authn support... 6 Figure 2: Context-Server adding support for JWT/OAuth 2 with UAP an Extension... 6 Figure 3: Duplicate API Guest Operator profile... 7 Figure 4: Modifying Operator Profile permissions for extensions... 8 Figure 5: Creating an API Client... 9 Figure 6: Generate the Access Token... 9 Figure 7: API Explorer UI... 10 Figure 8: Accessing the Store API... 10 Figure 9: Checking the Extension store for a particular Extension ID... 11 Figure 10: Details of the Extension... 11 Figure 11: Installing the Extension directly from the Extension store... 12 Figure 12: Extension Status... 13 Figure 13: Checking Extension Installation Progress... 14 Figure 14: Response to check on progress of Extension installation... 14 Figure 15: Get Extension Configuration... 15 Figure 16: Response to a request for the current Extension configuration... 15 Figure 17: Example of UAP Default Extension... 16 Figure 18: Adding a HTTP Generic Context Server -> Extension... 18 Figure 19: API Explorer /endpoint... 19 Figure 20: Building the Context Server Action (Action Tab)... 19 Figure 21: Building the Context Server Action (Header Tab)... 20 Figure 22: Building the Context Server Action (Content Tab)... 20 Figure 23: Triggering the Context Server Action from a HTTP Enforcement Profile... 20 www.arubanetworks.com 3333 Scott Blvd Santa Clara, CA 95054 Phone: 1-800-WIFI-LAN (+800-943-4526) 2017 Hewlett Packard Enterprise Development LP. All Rights Reserved. Fax 408.227.4550 ClearPass Extension Universal Authentication Proxy - TechNote 4
Introduction and Overview This TechNote describes how to use the ClearPass Universal Authentication Proxy [UAP] to supplement the existing Context-Servers and Context-Server-Actions. Extending the reach of the ClearPass Exchange framework to interoperate with additional third-party systems that do not authenticate sessions over basichttp is key to enhancing the framework s usefulness. At this time UAP adds support for two new tokenbased authentication methods: JSON Web Tokens [JWT] and OAuth2. Supporting these additional authentication methods provides support for a multitude of additional third-party vendors. Software Requirements The minimum software version required is ClearPass 6.6.1. At the time of writing, ClearPass 6.6.5 is the latest available and recommended release. Any subsequent ClearPass software release will support this integration. ClearPass runs on either hardware appliances with pre-installed software, or as a Virtual Machine on the hypervisors shown below. Hypervisors that run on a client computer such as VMware Player are not supported. VMware ESXi 5.0, 5.1, 5.5, 6.0, 6.5 or higher Microsoft Hyper-V Server 2012 or 2016 R2 Hyper-V on Microsoft Windows Server 2012 or 2016 R2 KVM on CentOS 6.6, 6.7, or 6.8. ClearPass Installation and Deployment Guide This document assumes your ClearPass environment is already configured and operational. If assistance with basic deployment is required, refer to the following deployment guide: http://www.arubanetworks.com/techdocs/clearpass/aruba_deploygd_html/default.htm ClearPass Extensions The integration between ClearPass Policy Manager and UAP is driven through a ClearPass capability known as Extensions, a sub-component of the ClearPass Exchange Integration framework. ClearPass Extensions are micro-services running on top of the base ClearPass platform. These micro-services enable Aruba to deliver new features outside of the main software release cycle and facilitate a faster time to market for specific features and integrations. Configuration and control of ClearPass Extensions is accomplished through the ClearPass REST APIs which are covered later in this document. ClearPass Extension Universal Authentication Proxy - TechNote 5
Pictorial View of the Integration Below is a pictorial view of the support for HTTP Generic Servers using basichttp Authentication. This was the limit to the authentication-type before the introduction of the new UAP Extension. The HTTP payloads are defined in the context server actions, the remote 3rd party system is the context-server. Figure 1: Context-Server with Basic HTTP authn support With the introduction of the UAP Extension to the workflow, the capabilities of the Generic HTTP context server are enhanced. In its simplest form, the UAP Extension proxies the authentication request from HTTP to either JWT or OAuth 2. The interaction between the context server actions and the context-server is the same, however the context-server now points to the UAP Extension which wraps the HTTP payload from the context serer action with a new Authentication header. Figure 2: Context-Server adding support for JWT/OAuth 2 with UAP an Extension Additional tokenization methods can be added to UAP in the future if required. ClearPass Extension Universal Authentication Proxy - TechNote 6
UAP Extension Installation and Configuration Installation of the UAP ClearPass Extension is performed via the REST API interface as it is for any Extension. ClearPass REST APIs were initially introduced in CPPM 6.5 and have continued to be enhanced in subsequent releases. Access to the APIs is through the following URL: https://<clearpass_ip>/api-docs. Admin credentials are required to access the API interface. The APIs to support ClearPass Extensions were initially released in ClearPass version 6.6. Several components, and multiple steps, are required to complete the ClearPass configuration: Extension Installation and Configuration Context Server Configuration Context Server Actions Configuration The ClearPass extension installation is shown below. This TechNote does not document in detail any one integration with a third-party system However, you can find an detailed example using of UAP in the BMC Remedy TechNote located at the following URL: https://support.arubanetworks.com/documentation/tabid/77/dmxmodule/512/command/core_download/ Default.aspx?EntryId=24200 Within the above BMC Remedy TechNote, the authentication between ClearPass and BMC requires JSON Web Tokens to supplement the exposed REST-based API in Remedy. Using a Context-Server and Context Server Actions in conjunction with UAP, it is very easy to build out additional 3 rd party integrations. Create an Extension API Operator Profile Before setting up the API access, configure an Operator Profile that will be associated with the configured API client. This new Operator Profile will be used in the next section when creating the API Client. Login to Guest and go to Administration > Operator Logins > Profiles. Next, click on API Guest Operator and select Duplicate. Figure 3: Duplicate API Guest Operator profile ClearPass will copy the profile and name it API Guest Operator (2). Click Edit on the new profile and rename it to be API Extension Profile. For the Platform privilege, change No Access to Custom and then ClearPass Extension Universal Authentication Proxy - TechNote 7
set all the Extension options as shown below (furthest option to the right). Scroll to the bottom of the page and click Save. Figure 4: Modifying Operator Profile permissions for extensions In the next step, this profile will be used as the Operator Profile when generating the API Client. The following is a copy of the API Client and Extension Installation taken from the BMC Remedy TechNote. Where reference to the BMC Remedy Extension is made, think of this as the UAP Extension install/config. Create an API Client The first step in installing and enabling the UAP ClearPass Extension is to create an API Client. An API Client provides authentication and authorization for the REST APIs. Authentication is performed using OAuth2, which is an authorization framework that enables applications to obtain limited access to data over a HTTP service without sharing their private credentials. Log into ClearPass Guest at https://<your-clearpass- Server>/guest. Navigate to Guest > Administration > API Services > API Clients and create an API Client by entering the following: 1. Client ID: Free choice 2. Operator Profile: API Extension Profile [just created] 3. Grant Type: Client credentials ClearPass Extension Universal Authentication Proxy - TechNote 8
Figure 5: Creating an API Client Click on Create API Client to save and create the API Client. Generate an Access Token Click Generate Access Token and then launch the API Explorer, as highlighted below at the bottom of the image. Figure 6: Generate the Access Token This will pre-populate the Authorization header in the API Explorer and permit commands to be run directly from the ClearPass UI. ClearPass Extension Universal Authentication Proxy - TechNote 9
Go to the Extension APIs Next check whether ClearPass can communicate with the Extension store. Click on Extension > Store. Figure 7: API Explorer UI Under Store, click GET /extension/store/{id} Figure 8: Accessing the Store API Notice that the Authorization header is populated. This is populated from creating the token in the previous step. Next expand the GET /extension/store/{id} and paste in the extension's store ID. As an example let s use the store ID for the BMC Remedy extension. It s a fixed value of: 0c1b4206-b633-4a13-82c9-013b18d38d4e. Click Try it out! ClearPass Extension Universal Authentication Proxy - TechNote 10
Figure 9: Checking the Extension store for a particular Extension ID Remember that the store ID of 0c1b4206-b633-4a13-82c9-013b18d38d4e is unique to this version of the BMC Remedy Extension. The store ID will change as new versions of the Extension are published. This will return details for the BMC Remedy Extension. This provides assurance that the correct authority is set to gain access to the Store, and that this is the correct ID for the extension to be installed. Figure 10: Details of the Extension Notice the name of the extension above, auth-proxy. ClearPass Extension Universal Authentication Proxy - TechNote 11
Install the Extension After checking for extension visibility, the next step is to install it. Under Instance > POST /extension/instance, paste in the body as shown below: {"state": "stopped", "store_id":"0c1b4206-b633-4a13-82c9-013b18d38d4e"} And then click Try it out! Figure 11: Installing the Extension directly from the Extension store This returns an ID (Note: this is different from the store ID, let s call it the run-time ID). Make a copy of this ID as it will be required later. The below shows the state of the Extension as preparing. This indicates the extension is in the process of being downloaded. A typical installation should take just a few seconds to complete. ClearPass Extension Universal Authentication Proxy - TechNote 12
Figure 12: Extension Status From the above, you can see the ID is b3f019cf-b9d1-408b-97e5-879e000eb9c1.this ID will be used to query and configure the extension, again we will call this the run-time ID. Your Extension ID will differ from the one used here. It is generated per installation and is unique to each and every installation. Query Extension after Installation Under Instance > GET /extension/instance/{id} paste in the ID from the previous step: b3f019cf-b9d1-408b-97e5-879e000eb9c1 and click Try it out!, remember this ID will be unique for every installation. ClearPass Extension Universal Authentication Proxy - TechNote 13
Figure 13: Checking Extension Installation Progress Within the Body Response from this GET observe the following: Figure 14: Response to check on progress of Extension installation The details of the extension will be displayed (could be downloading, etc.). Eventually the state will change to either stopped or failed. In this example it is clear the that the installation is created and stopped. ClearPass Extension Universal Authentication Proxy - TechNote 14
Configure the Extension The previous few pages cover the extension installation. Even though we refer to BMC Remedy, you re actually installing the UAP Extension if you use the Store ID 0c1b4206-b633-4a13-82c9-013b18d38d4e To complete the configuration of the UAP extension, you need to understand a little bit more about the 3 rd - party system ClearPass is communicating with. BMC Remedy uses JWT, other systems may use OAuth2. Below is an example of how to retrieve the current configuration of the extension. Under InstanceConfig > GET /extension/instance/{id}/config, paste in the extension ID b3f019cf-b9d1-408b-97e5-879e000eb9c1 and click Try it out! to return a copy of the current Extension configuration. Figure 15: Get Extension Configuration Figure 16: Response to a request for the current Extension configuration ClearPass Extension Universal Authentication Proxy - TechNote 15
The above example shows the default shipping configuration of the UAP extension. This will need to be modified depending on your chosen authentication method (JWT or OAuth 2). The following is the list of supported attributes, some are particular to JWT, others for OAuth2. tokenendpoint apiendpoint customauthmethod grant_type client_id client_secret otherparams localprefix authtype localprefix verifysslcerts loglevel As an example, here is the JWT configuration used for BMC Remedy Figure 17: Example of UAP Default Extension { } "verifysslcerts": false, "loglevel": "INFO", "configs": [ { "localprefix": "/bmc", "authtype": "JWT", "JWT": { "tokenendpoint": "http://10.10.10.10:8008/api/jwt/login", "apiendpoint": "http://10.10.10.10:8008/api/arsys/v1", "customauthmethod" : "AR-JWT", "authparams" : { "username": "apiuser", "password": "password" } } } ] ClearPass Extension Universal Authentication Proxy - TechNote 16
Example of an OAuth2 Configuration ClearPass to ClearPass As an example of utilizing ClearPass and the new UAP Extension, there has long been the need to support the ability of one ClearPass Node to call the exposed REST API s on a totally separate ClearPass node. With the source ClearPass not being able to make calls in Policy Manager using OAuth2, this was never an option. Using the UAP Extension, this workflow can now be supported. An example of the setup is shown below. Install UAP Extension The first step is to install the UAP Extension. Follow the installation procedure described in the preceding section to complete the installation of the UAP Extension. Configure UAP Extension Once the UAP extension is installed, it needs to be configured. This involves updating multiple parameters including the Remote CPPM IP address, the Client ID and the Client Secret. Utilizing the API Explorer, update the configuration for the UAP Extension as appropriate. Below is a sample configuration, yours should be very similar. When updating the configuration of the UAP extension, make a note of the IP address the Extension is running with. This will be used later to configure the context server. { } "verifysslcerts": false, "loglevel": "DEBUG", "configs": [ { "localprefix": "/oauth2", "authtype": "OAuth2", "OAuth2": { "tokenendpoint": "https://10.2.100.172/api/oauth", "apiendpoint": "https://10.2.100.172/api", "grant_type": "client_credentials", "client_id": "CPPM-TEST", "client_secret": "Pj0ROxtU7w24TO6JxWmG1P2DIpaPrEafxXg7jZ+Iv", "otherparams": { "redirect_uri": "" } } } ] ClearPass Extension Universal Authentication Proxy - TechNote 17
Here s a description of each attribute in the above configuration: "localprefix": "/oauth2" [This is free format, and is really just a label] "authtype": "OAuth2" [This is very important, valid values are OAuth2 or JWT] "OAuth2": [Based upon the previous setting in the authtype, build the Oauth config] "tokenendpoint": https://10.2.100.172/api/oauth [This is the IP address of the remote CPPM node] "apiendpoint": https://10.2.100.172/api [This is the CPPM node, set the IP address accordingly] "grant_type": "client_credentials" [This must match the grant type defined in the API Key] "client_id": "CPPM-TEST" [This must match the API Key Name] "client_secret": "Pj0ROxtU7w24TO6JxWmG1P2DIpaPrEafxXg7jZ+Iv" [Client Secret from API Key] Once the above has been defined, the next step is to define a context-server. Above you were asked to record the IP address of the UAP Extension. In the next step add a Context-Server and use the IP address recorded previously. From Administration -> External Servers -> Endpoint Context Servers [Add a Generic HTTP] Figure 18: Adding a HTTP Generic Context Server -> Extension Next you need to build a Context Server Action that effectively will call the ClearPass REST API s on the remote system. As very a simple example, the below creates a new endpoint. For the sake of the example, the configuration is hardcoded but you can use dynamic namespaces and attributes as appropriate. The first thing to note is that you must collect information about the API you want to use. Use the API Explorer to find information on the Create Endpoint API. ClearPass Extension Universal Authentication Proxy - TechNote 18
Figure 19: API Explorer /endpoint In the API Explorer shown above, note this is a POST action to the /endpoint API. See below how this matches the base URL in the configured in the Context Server Action. Figure 20: Building the Context Server Action (Action Tab) ClearPass Extension Universal Authentication Proxy - TechNote 19
Next configure the Header, adding the appropriate HTTP headers. Figure 21: Building the Context Server Action (Header Tab) Finally, configure the payload. In this example the payload is a defined set of attributes in a JSON Body. Figure 22: Building the Context Server Action (Content Tab) The trigger for the Context Server Action is an Enforcement Profile attached to an Enforcement Policy. Figure 23: Triggering the Context Server Action from a HTTP Enforcement Profile The net outcome of this is an Endpoint being created on the CPPM Node 10.2.100.172. ClearPass Extension Universal Authentication Proxy - TechNote 20