CloudPortal Services Manager 11.5 - Product … · CloudPortal Services Manager 11.5.5 ... What’s new in this Release ... Lanch the Microsoft ADFS web service configure program

© 2016 Citrix Systems, Inc. All rights reserved.

CloudPortal Services Manager 11.5.5

Microsoft ADFS Service 11.5.5

Version: 1.0

Last Updated: April 12, 2016


Page 2 © 2016 Citrix Systems, Inc. All rights reserved.



Contents

Copyright and Trademarks ....................................................................................................................... 4

Welcome to Microsoft ADFS Service 11.5.5 ............................................................................................. 5

What’s new in this Release ................................................................................................................... 5

Documentation and support for CloudPortal Services Manager ........................................................... 5

How to deploy and manage Microsoft ADFS Service 11.5.5 .................................................................... 6

Prepare ADFS infrastructure ..................................................................................................................... 7

Install and configure Microsoft ADFS web serivce .................................................................................... 7

Import and configure Microsoft ADFS service ........................................................................................ 11

View ADFS server status managed by Microsoft ADFS service ............................................................. 12

Common configuration problems and troubleshooting ........................................................................... 14

Known Issues .......................................................................................................................................... 18



Copyright and Trademarks Use of the product documented herein is subject to your prior acceptance of the End User License Agreement. A printable copy of the End User License Agreement is included with your installation media.

Information in this document is subject to change without notice. Companies, names, and data used in examples herein are fictitious unless otherwise noted. No part of this document may be reproduced or transmitted in any form or by any means, electronic or mechanical, for any purpose, without the express written permission of Citrix Systems, Inc.

© 2016 Citrix Systems, Inc. All rights reserved.

The following are trademarks of Citrix Systems, Inc. and/or one or more of its subsidiaries, and may be registered in the United States Patent and Trademark Office and in other countries:

Citrix®, Citrix Access Gateway™, Citrix App Orchestration™, Citrix Receiver™, Citrix XenApp™, CloudPlatform™, CloudPortal™, ICA®, NetScaler®, NetScaler App Delivery Controller™, NetScaler Gateway™, XenApp®, XenDesktop™, XenServer™

All other trademarks and registered trademarks are the property of their respective owners.



Welcome to Microsoft ADFS Service 11.5.5 Thank you for choosing CloudPortal Services Manager. This document includes information and instructions to help you learn more about deploying and managing your Microsoft ADFS service.

What’s new in this Release • Support Both ADFS 2.0 and ADFS 3.0: Microsoft ADFS service supports configuration and

management of both ADFS 2.0 and ADFS 3.0 servers.

• Configure Relying Party Trust: Microsoft ADFS service greatly simplifies procedures to create / modify / delete Relying Party Trusts in ADFS server when ADFS is required to provide authentication for other services (ShareFile service has been alredy supported).

• Support to Monitor ADFS Status: Single portal (control panel of CPSM) to view and monitor ADFS status, like certificates and properties. It not only saves the administrative effort, but also provides better user experience.

Documentation and support for CloudPortal Services Manager • CloudPortal Services Manager Discussion Forum: Use this Citrix Discussions site to ask questions

and contribute your knowledge about CloudPortal Services Manager.

http://discussions.citrix.com/forum/319-cloudportal-services-manager/



How to deploy and manage Microsoft ADFS Service 11.5.5 To deploy and use Microsoft ADFS service, the following extra steps are required:

• Prepare ADFS infrastructure

• Install and configure Microsoft ADFS web serivce

• Import and configure Microsoft ADFS service

After deploying the Microsoft ADFS service, use the following topic to view the status of ADFS servers,.

• View ADFS server status managed by Microsoft ADFS service



Prepare ADFS infrastructure To use Microsoft ADFS service, you need to prepare your ADFS infrastructure first, then install ADFS server and the ADFS proxy server and do the necessary configuration. Please refer to Windows Server 2012 R2 AD FS Deployment Guide provided by Microsoft for more details.

Install and configure Microsoft ADFS web serivce Microsoft ADFS web service should be installed on the ADFS server. It will be invoked remotely by Provision Engine to configure ADFS server.

1. Launch the Setup.exe from Microsoft ADFS web service installation folder

2. Check prerequisites, click Next, and follow the steps to finish the installation

3. Click the Configure button to configure the service

4. Create or specify a service account for Microsoft ADFS service

https://technet.microsoft.com/en-us/library/dn486820.aspx

https://technet.microsoft.com/en-us/library/dn486820.aspx



5. Before step 6, please install or import a domain certificate on Microsoft ADFS web service server to enable Provision Engine server to trust the certificate installed on Microsoft ADFS web service server. The root Certificate Authority(CA) for this certificate must reside within the Trusted Root Certificate Authorities node on Provision Engine Server, The following illustration shows the certificates in Provsion Engine server. the CA for the certificate on the Microsoft ADFS web service server, called “ca”, which is located in the Trusted Root Certificate Authorities path.

6. Specify Port and imported SSL Certificate used by Microsoft ADFS web service,then click ‘Next’ . This web service only uses HTTPS.



Important: By default 443 port has been used in ADFS server, please specify an available port.

7. In the Summary page, click Next to start the installation

8. Click Finish to complete the configuration.

9. Click Finish again to complete the installation.

10. To test the Web service working or not, in your browser, input https://<yourhost>:<port_in_step 6>/MicrosoftAdfs/MicrosoftAdfs.asmx, it should show below content



Install Microsoft ADFS web service through the command line When you install the Microsoft ADFS web service from the command line, you perform two actions:

• Install the web service and create the required Services Manager directory where the web service resides.

• Perform initial configuration of the web service using the Configuration Tool.

Follow the following steps to install and configure this service:

1. On the ADFS server, log on as an administrator.

2. Open a command line window and navigate to the dvd\bin directory on the Microsoft ADFS unzipped package.

3. At the command prompt, enter one of the following commands:

• CortexSetupConsole.exe /Install:MicrosoftAdfs • CortexSetupConsole.exe /Install:MicrosoftAdfs /logfile:<log_path>

The Setup Tool installs the web service and returns the command prompt.

4. Lanch the Microsoft ADFS web service configure program by default, the full path is:

C:\Program Files (x86)\Citrix\Cortex\Services\MicrosoftAdfs\Configuration\MicrosoftAdfsConfigConsole.exe

and specify the following properties:

Property Description

/UserName:username User name for the Lync service account. This parameter is optional if you are using /GenerateCredentials.

/Password:password Password for the Lync service account. This parameter is optional if you are using /GenerateCredentials.

/CertFriendlyName:friendly name

The user friendly name of the server comunication certificate used by Microsoft ADFS web service site.

/AutoCreateUser:True | False Optional. Create the service account in Active Directory.

/GenerateCredentials: True | False

Optional. Generate a password for the service account.

/ServicePort: port number Optional, Inbound port to be used and added to the CortexServices web site. Default = 8095

/UseSSL: True | False Optional, whether or not enable 40-bit SSL



Examples:

The following command perform the initial configuration of the web service.

& “C:\Program Files (x86)\Citrix\Cortex\Services\MicrosoftAdfs\Configuration\MicrosoftAdfsConfigConsole.exe” /Username:csm_microadfs_svc /Password:P@ssword! /CertFriendlyName:Wildcard /ServicePort:8095

Import and configure Microsoft ADFS service Before using Microsoft ADFS service, you need to import the package of Microsoft ADFS service from the control panel of CPSM.

Note: in each location, only one ADFS server will be used and shared with all customers in this location. If multiple ADFS servers exist in a location, only the first one will be used.

1. Login as service provider administrator, from Configuration->System Manager->Service Schema, click Import a Service, locate the .package file of Microsoft ADFS service and follow wizard to import the service.

2. After importing complete, on the Services Manager provisioning server, either restart the CortexQueueMonitor service or restart the machine

3. In the control panel, enable the service at the top level:

a. Under Service Filter, select Top Environment Services

b. From the Services Manager menu bar in the control panel, choose Configuration > System Manager > Service Deployment and then expand Microsoft ADFS Click Save

4. Enable the service at the location level

a. Under Service Filter, select Active Directory Location Services and choose a Location Filter if applicable

b. From the Services Manager menu bar in the control panel, choose Configuration > System Manager > Service Deployment and then expand Microsoft ADFS Click Save

5. Verify credentials:

a. From the Services Manager menu bar, choose Configuration > System Manager > Credentials.

b. Create the administrative impersonation account for the Microsoft ADFS service by clicking Add, and then entering a username, password, and domain (preferably in Fully Qualified Domain Name form).

6. Enable the server:

a. From the Services Manager menu bar, choose Configuration > System Manager > Servers.



b. If the server on which you installed the service is not listed, click Refresh Server List

c. Expand the entry for the server and verify that Server Enabled is selected

7. Assign the server roles:

a. From the Services Manager menu bar, choose Configuration > System Manager > Server Roles, and then expand the entry for the server

b. Under Server Connection Components, select Microsoft ADFS, and then click Save

8. Add a server connection:

a. From the Services Manager menu bar, choose Configuration > System Manager > Server Connections, select a Location Filter if applicable, click New Connection, and then select or type the following information for the web service.

Server Role: Microsoft ADFS

Server: Microsoft ADFS Web Service server name

Credentials:

URL Base: /MicrosoftAdfs/MicrosoftAdfs.asmx

Protocol: https

Port: <port your specify during configure Microsoft ADFS web service>

Timeout: 200000

b. On the Server Connections page, click the icon in the Test column for the server. The icon turns green for a successful connection. A red icon indicates an unsuccessful connection. Hover the icon to get more information about the failed connection.

View ADFS certificate status 1. From the Services > Microsoft ADFS, click Certificate Management

2. Click Location drop down list to select the location to be displayed or keep the default “All” to show certificates used by ADFS servers from all locations.

3. Or you can enter the customer name in the Search Certificate Subject search box to filter the specific certificate.

In this page, the following information can be found:


Status The status of the certificate, it can be:

• Invalid: expired certifcate

• Expired in 30 days

• OK: the cerficate is valid




Subject The subject field in certificate, which can be used to identify the certificate.

Location The location of Microsoft ADFS service serves

ADFS Server The ADFS server name

Type The certificate type, ADFS server uses three types:

• Service communication

• Token-decrypting

• Token-signing

Primary Only valid for Token-decrypting and Token-signing cerficates, the value can be:

• Primary

• Secondary

For these two types, more than one certificate can be imported at the same time but only the primary certificate is used.

Issuer The issuer of the certificate.

Effective Date The effective date of the certificate in UTC

Expiration Date The expiration date of the certificate in UTC

View configuration properties of ADFS 1. From the Services > Microsoft ADFS, click ADFS Property

2. Click Location drop down list to select the location to be displayed.

3. (Optional) enter the property name in the Search Property Name search box to filter the specific property.

In this page, the following information can be found:


AutoCertificateRollover Whether or not the “auto rollover” feature is enabled for token-signing certificate, if it is enabled, ADFS will automatically generate token-signing certificate and renew it when expired.




Hostname The hostname of ADFS server

FederationPassiveAddress The URL path of SAML 2.0/WS-Federation endpoint, which is used as Login URL by SP-Initiate SAML authentication.

How to collect trace for debug Besides of the existed trace functionality, log4net is integrated into CPSM web server, Microsfot ADFS web service to provide additional trace to help the debug.

Trace level and saved trace location can be configured by modify trace configuration file.

There are 7 levels of trace:

1. OFF – shutdown the trace functionality 2. FATAL – trace un-recoverable error 3. ERROR – trace errors which will not break the service 4. WARN – trace warnings 5. INFO – trace information such as what the application is doing 6. DEBUG – trace the function stacks which is used for debug purpose 7. ALL – open all trace option (FATAL, ERROR, WARN, INFO, DEBUG)

Following is the example of how to modify the trace level. Within the trace configuration file, find below info like:

<root> <level value="ALL"/> <appender-ref ref="RollingLogFileAppender"/>  

</root>

Current default level is “ALL”, user can customize the trace level. Note, please don’t change the appender info unless you are very familiar with log4net configuration

To change the trace location, it can be done by modify below info:

<appender name="RollingLogFileAppender" type="log4net.Appender.RollingFileAppender">

<file value="c:\Program Fils(x86)\Citrix\CortexWeb\CortexNonNet\Services\log\MirosoftAdfsWeblog_" />

<appendToFile value="true"/>

<maxSizeRollBackups value="5"/>

<maximumFileSize value="5000KB"/>

<DatePattern value="yyyy-MM-dd'.txt'" />

<rollingStyle value="Composite"/>



<staticLogFileName value="false"/>

<layout type="log4net.Layout.PatternLayout">

<header value="[Header]"/>

<footer value="[Footer]"/>

<conversionPattern value="%date [%thread] %-5level [%L] -- %message%newline"/>

</layout>

</appender>

Note: please do not modify other parts, unless you are very familiar with log4net configuration

Trace for CPSM web server For CPSM web server, the log configuration file is:

C:\inetpub\Cortex Management\CortexDotNet\Services\MirosoftAdfs\WebLog.config

The default trace log is stored within path of the machine which has CPSM web server deployed:

C:\ProgramFiles(x86)\Citrix\Cortex\CortexWeb\CortexDotNet\Services\log\

And the default trace level is “ALL”

Trace for Microsfot ADFS Web Service For Microsoft ADFS Web Service, the log configuration file can be found from the path of the machine which has Microsoft ADFS web service deployed:

C:\inetpub\CortexServices\MicrosoftAdfs\WebServiceLog.config

The default trace log is stored within:

C:\ProgramFiles(x86)\Citrix\Cortex\Services\log\

The default trace level is “ALL”



Common configuration problems and troubleshooting 1. Powershell cmdlets are not recognized.

Symptom: Provision or deprovision customer service failed with error message: The term Get-AdfsCertificate is not recognized as the name of a cmdlet, function, script file, or operable program. Check the spelling of the name, or if a path was included.

Root cause: ADFS is not installed successfully.

Remediation: Please reinstall and reconfigure ADFS server role and ensure it works properly.

2. Can not connect to the configuration service.

Symptom: Provision or deprovision customer service failed with error message: An exception occurred while connecting to the configuration service.

Root cause: ADFS is not configured successfully.


3. Can not get token-signing certificate.

Symptom Provision or deprovision customer service failed with error message: no Token-Signing certification can be found.

Root cause: ADFS is not configured successfully.


4. Can not browse Micrsoft ADFS Certificate Manage page.

Symptom: When browse the web page [Services->Microsoft ADFS->Certificate Manage] with error message: An error occurred while loading service data.

Root cause: Can not get data from ADFS server successfully.


5. Can not start CortexServices Web Site

Symptom: When configure ADFS web service on ADFS 2.0 server with an error message: can not start CortexServices Site.

Root cause: The port of CortexServices Web Site is used by other web site.

Remediation: Open Internet Information Services (IIS) Manager in the server where Microsof ADFS web service is installed, check if the binding port of other sites such as Default Web Site is duplicated



with the site of CortexServices Site, If yes,delete the CortexServices site and re-configure ADFS web service with other port.



Known Issues 1. If you’re using IE 11.x, and set the “IE Enhanced Security Configuration” to Off, make sure

IE->Tools->Compatibility View Settings, Display intranet sites in Compatibility View and Use Microsoft compatibility lists are unchecked, or you may encounter display error.

Documents

CloudPortal Services Manager 11.5 - Product … · CloudPortal Services Manager 11.5.5 ... What’s new in this Release ... Lanch the Microsoft ADFS web service configure program