Microsoft UAG Integration
From Swivel Knowledgebase Wiki
Contents |
Introduction
This configuration document outlines how to integrate PINsafe with Microsoft Forefront Unified Access Gateway using Active Directory authentication in addition to the PINsafe authentication.
If installing PINsafe on the UAG appliance it may be required to install PINsafe to use a different port than the default 8080.
Prerequisites
Microsoft Forefront Unified Access Gateway
UAG and URL rewriting documentation
PINsafe 3.x server with ChangePIN
ChangePIN configuration document
The following files are required to be uploaded to the UAG
images.asp
login.asp (Rename loginturingsms.asp as login.asp)
Portalname1postpostvalidate.inc
Token.inc
The files can be downloaded from here: UAG Files
UAG Update 1 requires a modified login page, this additional file can be downloaded here: UAG Update 1 Files
UAG SP1 requires modified login pages, the complete set of files can be downloaded here: UAG SP1 Files
UAG SP1 SMS only request button login also UAG SP1 TURing only request button login
Baseline
Microsoft Forefront Unified Access Gateway 1.0.1101.0
PINsafe 3.5
Architecture
The UAG makes authentication requests against the PINsafe server by RADIUS or XML.
Installation
Configure The PINsafe Server
Configure a RADIUS NAS entry
1. Ensure the RADIUS server is running on PINsafe
2. On the PINsafe Management Console select RADIUS NAS
3. Enter a name for the NAS
4. Enter the UAG internal IP address
5. Enter the shared secret
6. Click on Apply to save changes
Configure Single Channel Access
1. On the PINsafe Management Console select Server/Single Channel
2. Ensure ‘Allow session request by username’ is set to YES
Configure the UAG
Edit the UAG Configuration Files
Edit the file images.asp with the below URL to represent the PINsafe server IP address and PINsafe install name:
objWinHttp.Open "GET", "https://<hostname_of_pinsafe>:8443/proxy/SCImage?username=" & request.querystring("username"),false
Where <hostname_of_pinsafe> is your PINsafe hostname.
Then edit Token.inc with the required shared secret:
m_secret = "<secret>"
Where <secret> is your secret (do not enter the angle brackets).
Copy the Configuration files
Note: Ensure any existing files are backed up first.
1. Copy Token.inc and Portalname1postpostvalidate.inc to: <path to UAG install>\von\InternalSite\inc\CustomUpdate
2. Copy login.asp file to: <path to UAG install>\von\InternalSite\CustomUpdate
3. Copy images.asp to: <path to UAG install>\von\InternalSite\Images\CustomUpdate
Configure the TMG
Create a Threat Management Gateway rule to allow access from the UAG to the PINsafe server
On the TMG configuration select New Access Rule and create a rule to allow traffic from the UAG to the PINsafe server.
Port 8443 (or port 8080 for software installs, older appliances and when using XML authentication)
From Local Host (i.e. the UAG)
To PINsafe Server (or Internal Network)
Outbound Traffic
Configure Login Page
Select the UAG Configuration GUI, From the Advanced Trunk Configuration select Authentication and set the Login Page to customupdate\Login.asp. This can be changed to reflect a different install location or trunk.
RADIUS authentication Configuration
PINsafe can be configured as the Primary authentication server or more usually is configured as a secondary authentication server. When using PINsafe as a secondary authentication such as with Active Directory, ensure that the options for secondary authentication are selected.
To enable RADIUS authentication create a repository of type “RADIUS” on the UAG configuration.
To use RADIUS do the following-
1. Access the UAG configuration GUI.
2. Click on Admin Authentication Users/Group repository
3. Select New to create a new repository
4. In the drop down menu, select “RADIUS” and in the Name field enter PINsafe RADIUS
5. Enter the IP of the PINsafe server
6. Enter port 1812
7. If required enter a second IP/port
8. Enter a shared secret key of the same value as the PINsafe server
9. Click on Add and apply this repository to the relevant trunk.
10. Ensure User must enter credentials for each server is selected.
11. If AD password is to be entered ensure that an AD authentication server is specified.
12. Activate the configuration
13. Configure PINsafe as a RADIUS server
Configuring the URL rewriting rules
To allow access to the images.asp
1. Select the required Trunk
2. Select Configure from the Advanced Trunk Configuration
3. Select the ‘URL Set’ Tab
4. Add a rule to permit access to the images.asp
InternalSite_Rule100
Note: This must be named InternalSite_Rule, example: InternalSite_Rule100 (use a high number to prevent it being overwritten by updates)
With parameters of:
Action: Accept
URL: /internalsite/images/customupdate/images.asp
Note: You can use /internalsite/images/customupdate/* for testing, and add additional rules to check the input.
Parameter: Handle (i.e. handle any parameters. For troubleshooting it may be useful to set this to ignore).
Method: Get
To Allow access to PINsafe specific parameters:
Under Parameters select Add, add the following values:
Name: username
Name Type: String
Value: ‘[a-z0-9]’ (this is a basic regex and may need changing depending on the users username policy)
Value Type: String
Length: 1:100 (may need to up 100 depending on customer username length)
Existence: Mandatory
Occurrences: Single
Max total length: -1
Rejected values checking: on
Edit Rule to allow Access to the validate.asp
1. Select the validate.asp rule (Usually Internal_Rule2)
2. Under Parameters select Ignore
Alternatively add the following to the parameters list:
Turing
SMS
To Allow access to PINsafe specific parameters:
Select the InternalSite_Rule2
Under Parameters select Add, add the following values:
Name: swivel
Name Type: String
Value:
Value Type: String
Length: 1:100
Existence: Optional
Occurrences: Multiple
Max total length: -1
Rejected values checking: on
Also add a Parameter with the following values:
Name: orig_url
Name Type: String
Value:
Value Type: String
Length: 1:200
Existence: Optional
Occurrences: Multiple
Max total length: -1
Rejected values checking: on
To allow access to the ChangePIN application
- Select the required Trunk
- Under Applications select Add
- Click the Web Applications Radio App and Generic Web App then Next
- Enter Application name ChangePIN and Application Type: pinsafe then Next
- Enter the ChangePIN IP address, and under path the location of the ChangePIN install (normally changepin), set the port to 8443, then Next
- Select Next
- Check details are correct, specifically https://<IP Address>:8443/changepin and then Finish
NOTE: If changing the IP address then change the IP address in the Application Properties on the Web Servers and the Portal Applications tabs.
Verifying the Installation
Browse to the login page, select TURing and enter a username, the Turing image should appear. Test using the SMS option. Check for requests on the PINsafe server.
UAG Login Page
UAG login using SMS
UAG login using Turing Single Channel Image
Successful RADIUS authentication
The following user logged into trunk "test" (secure=0): User: admin; Source IP: 192.168.9.87; Authentication Server: PINsafe RADIUS; Session: B9FCC62A-B073-445D-9AAE-2FB1109EE5E6.
Troubleshooting
Check the PINsafe server logs and system event logs for any errors or lack of communication as well as the UAG logs under Admin/Web Monitor. Check the ISA server logs.
From a web browser on the UAG check to see if it is possible to generate a Turing image https://<IP address of PINsafe server>:8443/proxy/SCImage?username=test
If the changes made in the UAG are not reflected in the login page, allow sufficient time for the rules to be written on the TMG (wait 10 minutes).
Request failed, the URL contains an illegal path. Trunk: test; Secure=0; Application Name: Whale Internal Site; Application Type: InternalSite; Rule: Default rule; Source IP: 192.168.9.87; Method: GET; URL: /InternalSite/Images/customupdate/images.asp?username=admin
URL blocking by the UAG. Check that the image can be rendered and that the URL rewriting rules are correct
The URL /internalsite/images/customupdate/images\*.asp contains an illegal path. The rule applied is Default rule. The method is GET.
When the message The rule applied is Default rule is seen, it means that no rule has been matched and by default the URL is blocked. In the above example the path is incorrect to images.asp.
Http 500 error
If you get an http 500 error when using xml based integration you may need to edit the token.inc file so that
Set objWinHttp = Server.CreateObject("WinHttp.WinHttpRequest.5")
is replaced with
Set objWinHttp = Server.CreateObject("WinHttp.WinHttpRequest.5.1")
Ensure that the UAG can resolve the PINsafe server name when hostname is used for connecting by RADIUS. Try with the IP address of the PINsafe server.
Additional Configuration Options
RADIUS Challenge and Response
The UAG and PINsafe supports the use of Challenge and Response authentication.
On the PINsafe Administration Console ensure two-stage authentication is set to "Yes" for the RADIUS NAS definition. Secondly, under Server -> Dual Channel, ensure On demand authentication is set to "Yes".
In order to use two-stage authentication on PINsafe, all users have to have a password defined. There are two ways to manage this: either set a password for each user under user administration, or enable the option to check password with repository (under Policy -> Password), in which case PINsafe uses the AD password. Either way, you need to enter the password for PINsafe as well as the AD password. (It might be possible, using the repository password option, to have a custom page that copies the AD password to the PINsafe password, but this has not been tested).
If the PINsafe password is entered correctly, you will be sent a security string, and a second login page will be displayed, to enter your one-time code.
Button size and aspect ratio
The Button size and aspect ratio is controlled by the settings in the login page:
document.all.otp.innerHTML = '<img src="/InternalSite/customupdate/FetchTuring.asp? username=' + otpusername +'" height="81" width="300">'; }
change the height and width settings to the value that is appropriate.
XML Authentication
Configuring XML authentication (when not using RADIUS)
XML authentication has not been tested with the current version of UAG and is supplied for reference if required, RADIUS authentication is the preferred method of authentication.
Note that when using a PINsafe appliance with a proxy configured, the XML requests need to be made to the https://<IP>:8080/pinsafe address rather than the proxy address. This applies currently to all PINsafe appliance versions.
This step is not required when RADIUS authentication is used. RADIUS authentication is the preferred method of authentication. To enable the token.inc file, create a repository of type “Other” on the UAG configuration. The repository you create must match the name of the file (ie, if the inc file is called Token.inc, the repository must be named Token).
Configure a PINsafe Agent (For XML Authentication)
1. On the PINsafe Management Console select Server/Agent
2. Enter a name for the Agent
3. Enter the UAG internal IP address
4. Enter the shared secret
5. Click on Apply to save changes
To create the repository, do the following-
1. Access the UAG configuration GUI.
2. Click on Admin Authentication Users/Group repository
3. Select New to create a new repository
4. In the drop down menu, select “Other” and in the Name field type in the name of the inc file (See screen shot below)
5. Click on Add and apply this repository to the relevant trunk.
6. Activate the configuration
Edit the file Token.inc with the required shared secret and to represent the PINsafe server IP address and PINsafe install name, Note for all PINsafe installs this needs to point to the PINsafe server on port 8080 and not the proxy port 8443.
m_secret = "secret"
objWinHttp.Open "GET", "https://192.168.1.1:8080/pinsafe/AgentXML?xml=" & m_request, false
Note If you get an http 500 error when using xml based integration you may need to edit the token.inc file so that
Set objWinHttp = Server.CreateObject("WinHttp.WinHttpRequest.5")
is replaced with
Set objWinHttp = Server.CreateObject("WinHttp.WinHttpRequest.5.1")
Edit the file Portalname1postpostvalidate.inc to represent the PINsafe server IP address and changePIN install name:
'response.redirect "https://192.168.1.1:8443/changepin" g_orig_url = "https://192.168.1.1:8443/changepin"
Known Issues and Limitations
If upgrading the UAG to a higher service pack, the configuration files, particularly login.asp may be overwritten. Verify the files after an upgrade. Also note that the URL rewriting rules may differ from version to version, so these should also be verified.
Upgrading from RTM Update 2, to SP1 will cause the InternalSite rules, on the UAG to be removed, or changed back to defaults.
Additional Information
For assistance in the PINsafe installation and configuration please firstly contact your reseller and then email Swivel Secure support at support@swivelsecure.com
