SmartPatch. Configuration Reference Version 6.x

Transcription

1 SmartPatch Configuration Reference Version 6.x

2 Copyright Copyright 2017 Brand-Rex Ltd. All rights reserved. No part of this publication or of the SmartPatch software, in source code or object code form, may be reproduced, stored in a retrieval system, or transmitted in any form or by any means, electronic, mechanical, photocopying, recording or otherwise, without the prior written consent of Brand-Rex or technology partners of Brand-Rex Ltd. Contact information is available on request Disclaimer These materials are subject to change without notice and for informational purposes only, without representation of warranty of any kind. Document history History table: Version Date Author Description Edeeben Logo and style update 6.x Edeeben Version 6 updates 2

3 Contents Copyright... 2 Disclaimer... 2 Document history... 2 Introduction... 4 Server Configuration... 4 Server Configuration File Database Configuration... 4 Authentication Configuration... 5 Password Policy Configuration... 6 LDAP Authentication Configuration... 6 LDAP Interface Test Tool... 9 SAML 2.0 Single Sign-On (SSO) Authentication Configuration... 9 Enable the Spring Security SAML Extension Identity Provider (IdP) Metadata Identity Provider (IdP) Metadata for File Based Metadata Identity Provider (IdP) Metadata for URL Based Metadata Service Provider (SP) Metadata Configuring the Identity Provider (IdP) Verifying the SSO Configuration SSL Configuration Logging Configuration Miscellaneous Configuration Client-Server Compression

4 Introduction The purpose of this document is to describe the available configuration options for the SmartPatch Server and SmartPatch Client software. Server Configuration Server Configuration File. SmartPatch Server is configured using the file server.properties, which can be found in the installation folder of the software. The following sections describe the configuration properties in detail. Note that the Database Configuration (described in section 4) is a mandatory configuration. All other configurations are optional. Note that applying any changes to the server.properties file should be done while the Apache Tomcat process is stopped. Database Configuration The properties that specify the database that SmartPatch Server should connect to are described in Table 1. Please refer to the database specific installation manual supplement for a description and example of the correct property values for each of the supported DBMS types. These installation manual supplements are: SmartPatch Installation Manual MySQL Supplement.pdf SmartPatch Installation Manual Oracle Supplement.pdf SmartPatch Installation Manual SQL Server Supplement.pdf SmartPatch Installation Manual PostgreSQL Supplement.pdf Property 0-dbms 0-dbhost 0-dbport 0-dbproperties 0-dbinstance 0-login 0-password Description The type of database used for the specified project. Possible values are Firebird, HSQLDB, MSSQLServer, MySQL, Oracle, IBM DB2 and PostgreSQL The host name of the machine hosting the database server for the specified project. The network port that should be used to contact the database server for the specified project Option database connection string properties The instance name of the database that should be used for the specified project. The user name for the database that should be used for the specified project The password for the database that should be used for the specified project. Table 1: Database Properties 4

5 Authentication Configuration The method by which SmartPatch users are authenticated is controlled by the authentication-methods property. The supported methods are: BASIC, in which case authentication is performed against user credentials in the SmartPatch database. Section 6 provides details of the properties available for controlling password policies. LDAP, in which case authentication is performed against user credentials in an external directory such as Windows Active Directory. Section 6 provides details on how to configure LDAP authentication. SAML, in which case authentication will be handled by a SAML 2.0 Identity Provider and SmartPatch will operate as a SAML 2.0 Service Provider to the Identity Provider. Section 9 provides details on how to configure SAML authentication. Table 3 describes the authentication-methods property. Property Description Default Authentication-methods The methods of authentication that SmartPatch should Basic use. The supported methods are BASIC LDAP SAML BASIC indicates that authentication will take place against user credentials stored in the SmartPatch database. LDAP indicates that authentication will be handled by an LDAP server. Note that both LDAP and BASIC methods of authentication can be specified in conjunction by separating them with a comma, for example: LDAP,BASIC In this case, fail-over authentication will take place in the order that the methods are specified. SAML indicates that authentication will be handled by a SAML 2.0 Identity Provider and SmartPatch will operate as a SAML 2.0 Service Provider to the Identity Provider. See section 9 for details 5

6 Password Policy Configuration The properties described in Table 2 determine the password policies for users when the authentication method is configured to be BASIC (see section 5 for details on how to configure authentication methods). Property Description Default password-max-days If a password was set more than password-max-days ago then the user is requested to change their password. password-max-days-allow-all-policy If a password was set more than password-max-daysallow-all-policy ago then the users who have the allow- all policy are requested to change their password. previous-passwords-to-remember New passwords should be different than the previous 0 previous-passwords-to-remember ones. password-min-length Passwords must be at least password-min-length 0 characters long. password-min-non-letters Passwords must contain at least password-min-nonletters 0 characters that are not letters. password-min-upper-case-letters Passwords must contain at least password-min-uppercase-letters 0 upper case letters. password-min-lower-case-letters Passwords must contain at least password-min-lowercase-letters 0 upper case letters. password-min-numeric-characters Passwords must contain at least password-min-numericcharacters 0 numeric characters. password-min-non-alphanumericcharacteralphanumeric-characters Passwords must contain at least password-min-non- 0 characters that are not alphanumeric (i.e. $, %, etc.). failed-attempts-before-lockout Locks the user for this amount of time in minutes if an incorrect password is entered failed-attempts-beforelockout times. 60 Table 2: Password Expiration and Content Properties LDAP Authentication Configuration The steps to configure SmartPatch to use LDAP authentication are: 1. Configure SmartPatch user groups so that the names of the groups match with corresponding groups in the LDAP directory. Group names are case sensitive. Users that are members of the LDAP groups will belong to the SmartPatch group of the same name. Multiple groups are honored. For example: SmartPatch groups: Patchers, EquipmentMaintainers LDAP groups: Administrators, Patchers, EquipmentMaintainers LDAP users and group memberships: Joe: Administrators, Patchers Bob: Administrators, Patchers, EquipmentMaintainers Eric: Administrators James: Patchers Fred: Patchers Peter: Patchers, EquipmentMaintainers Martin: EquipmentMaintainers 6

7 The Patchers group will contain Joe, Bob, James, Fred, and Peter. The EquipmentMaintainers group will contain Bob, Peter, and Martin. Finally, because there is no SmartPatch group named Administrators, Eric will not be associated with any user groups (and will not have any privileges to enter the application). 2. Configure the appropriate properties in the server.properties file to specify the interface between SmartPatch and the LDAP directory. A complete description of the available properties is provided in Table 3. Typical property values are provided in Table 4. Note that these values are only intended as examples and may differ from the values required by your LDAP directory. Note that to assist in configuring the appropriate server properties, an offline interface test tool is available. This tool is described in section 9. Property Description Default ldap-enabled Set to true to enable LDAP functionality in false SMARTPATCHServer. ldap-provider URL for the LDAP server. Should include the protocol and port, e.g. ldap://server.address:389. Ensure that the LDAP server DNS name in the URL matches the SPN (Service Principal Name) of the server. ldap-auth-mechanism Authentication method for LDAP. Note that Active simple Directory can use DIGEST-MD5 whereas linux slapd should use simple with protocol ldaps:// or ldap:// ldap-search-context The base user DN. This is the root node in LDAP from which to search for users, e.g. dc=patchmanager,dc=com ldap-search-user-name The user used to create the initial search context. For Windows Active Directory, the value that should be specified for this property depends on the value that is specified for ldap-user-result: If ldap-user-result = samaccountname then the value specified should represent the user name of the LDAP search account. If ldap-user-result = dn then the value specified should represent the DN(=Distinguished Name) of the LDAP search account. ldap-search-user-password ldap-groups-search-context ldap-group-objectclass ldap-group-name-attribute ldap-member-attribute For Linux/Unix based LDAP servers, the value specified for ldap-user-result should always be dn, so the value specified for ldap-search-user-name should always represent the DN(=Distinguished Name) of the LDAP search account. The password for the initial LDAP search. The base group DN. This is the node in LDAP below which to search for groups, e.g. dc=patchmanager,dc=com LDAP object class for groups of users. The name of the attribute in a group that contains the name of the group. The name of the attribute in a group that contains the members of the group. Default value for both Active Directory and slapd is member. Member 7

8 ldap-user-objectclass The object class that represents a user. Active Directory: Person slapd: posixaccount. Other commonly used values are person, organizationalperson, inetorgperson. ldap-user-lookup The name of the attribute in a user object that contains the username. Active Directory: samaccountname slapd: uid ldap-user-result The name of the attribute in a user object that contains the login name. Active Directory: samaccountname slapd: dn Table 3: LDAP Authentication Properties Common LDAP properties: For Windows Active Directory, add the following additional properties: For Linux/Unix based LDAP servers, add the following additional properties: Table 4: Example LDAP properties authentication-methods=ldap ldap-enabled=true ldap-provider=ldap://localhost:389 ldap-search-user-password=abc123 ldap-search-context=dc=example,dc=com ldap-groups-search-context=dc=example,dc=com ldap-member-attribute=member ldap-search-user-name=johnsmith ldap-auth-mechanism=digest-md5 ldap-group-name-attribute=name ldap-group-objectclass=group ldap-user-lookup=samaccountname ldap-user-objectclass=person ldap-user-result=samaccountname ldap-search-user-name=cn=john Smith,ou=Users,ou=Accounts,dc=example,dc=com ldap-auth-mechanism=simple ldap-group-name-attribute=displayname ldap-group-objectclass=posixgroup ldap-user-lookup=uid ldap-user-objectclass=posixaccount ldap-user-result=dn 8

9 LDAP Interface Test Tool The LDAP Interface Test Tool is an offline tool that provides a mechanism for validating the properties required to interface to your LDAP Directory server. Valid properties will lead to the tool establishing a connection to the LDAP directory, successfully authenticating a specified user and retrieving the group membership of that user, thus simulating the actions taken by SmartPatch Server when authenticating/authorizing the user. When the properties have been validated, they can then be entered into the SmartPatch Server server.properties file. Note that the tool does not require that SmartPatch Server is running, but it is recommended that it is executed on the SmartPatch Server machine. The tool is distributed in the archive 'ldap-interface-testing-tool-<rev>.zip', where <rev> is the software revision number of the tool. The archive contains two files: 'ldap-interface-testing-tool-<rev>.jar', where <rev> is the software revision number of the tool 'ldap.properties', which contains an example set of input properties. The tool should be executed by Java from the command line and requires a single parameter to indicate the path to the file containing the input properties: -c <the file containing the input properties to validate> An example command line to run the tool is: java -jar ldap-interface-testing-tool jar -c ldap.properties Upon execution of the tool, prompts will appear for entering the user name and password of the user whose authentication and group membership will be validated. Logging output will be generated at each step of the process. If the tool logs the successful authentication of the user and the retrieval of the appropriate group membership of the user, then the properties are set correctly and can be used in the server.properties file of SmartPatch Server. SAML 2.0 Single Sign-On (SSO) Authentication Configuration SmartPatch supports being configured as a SAML 2.0 Service Provider (SP) to facilitate SAML 2.0 Single Sign-On (SSO). The mechanism with which SmartPatch implements SAML 2.0 SSO is via the Spring Security SAML Extension. This section is intended to serve as a guideline for enabling SAML 2.0 SP SSO support in SmartPatch. Note that the detail of the configuration steps may vary depending on your specific Identity Provider (IdP) implementation, but in all cases, the configuration steps will be similar to those described in this section. In order to configure SMARTPATCHas a SAML 2.0 SP, prior knowledge of the SAML 2.0 protocol and of the appropriate configuration of your IdP is recommended. The following sections assume that SmartPatch has been deployed to the 'ROOT' web application context of Apache Tomcat. If SmartPatch has instead been deployed to a different web application context, then any references in the sections to the 'ROOT' web application context should be interpreted accordingly. 9

10 Enable the Spring Security SAML Extension In the file '<Apache Tomcat Installation Directory>/webapps/ROOT/WEB-INF/web.xml' ensure that the XML elements below are uncommented (by removing the character sequences '<!--' and '-->' that enclose the XML elements): <context-param> <param-name>contextconfiglocation</param-name> <param-value> /WEB-INF/securityContext.xml <servlet> <servlet-name>saml</servlet-name> <servlet-class>org.springframework.web.servlet.dispatcherservlet</servlet-class> <load-on-startup>1</load-on-startup> </servlet> <servlet-mapping> <servlet-name>saml</servlet-name> <url-pattern>/saml/web/*</url-pattern> </servlet-mapping> <filter> <filter-name>springsecurityfilterchain</filter-name> <filter-class>org.springframework.web.filter.delegatingfilterproxy</filter-class> </filter> <filter-mapping> <filter-name>springsecurityfilterchain</filter-name> <url-pattern>/*</url-pattern> </filter-mapping> <listener> <listener-class>org.springframework.web.context.contextloaderlistener</listener-class> </listener> 10

11 Identity Provider (IdP) Metadata Identity Provider (IdP) Metadata for File Based Metadata If your IdP metadata is available as a file, the following steps describe how to configure this metadata in SmartPatch. 1. Create a directory named 'metadata' in the directory: '<Apache Tomcat Installation Directory>/webapps/ROOT/WEB-INF/classes' 2. Copy your IdP metadata file into the newly created 'metadata' directory and (if necessary) rename it to be 'idp.xml'. 3. In the file '<Apache Tomcat Installation Directory>/webapps/ROOT/WEB-INF/securityContext.xml', after the tag '<!-- add Identity Provider metadata here -->', add the following contents: <bean class="org.springframework.security.saml.metadata.extendedmetadatadelegate"> <property name="metadatatrustcheck" value="false"/> <constructor-arg> <bean class="org.opensaml.saml2.metadata.provider.filesystemmetadataprovider"> <constructor-arg> <value type="java.io.file">classpath:metadata/idp.xml</value> </constructor-arg> <property name="parserpool" ref="parserpool"/> </bean> </constructor-arg> <constructor-arg> <bean class="org.springframework.security.saml.metadata.extendedmetadata"> </bean> </constructor-arg> </bean> 11

12 Identity Provider (IdP) Metadata for URL Based Metadata If your IdP offers its metadata as a URL, add the following contents in the file '<Apache Tomcat Installation Directory>/webapps/ROOT/WEB-INF/securityContext.xml', after the tag '<!-- add Identity Provider metadata here ->', replacing the text '{idp-metadata-url}' with the URL of the IdP metadata: <bean class="org.opensaml.saml2.metadata.provider.httpmetadataprovider"> <constructor-arg> <value type="java.lang.string">{idp-metadata-url}</value> </constructor-arg> <constructor-arg> <value type="int">5000</value> </constructor-arg> <property name="parserpool" ref="parserpool"/> </bean> 12

13 Service Provider (SP) Metadata Ensure that SmartPatch Server is running. Using your browser, browse to 'http(s)://<serveraddress:port>/saml/web/metadata', where '<serveraddress:port>' is the network address and port that SmartPatch Server is running on. Log in to the metadata administration page with the following login credentials: User name: Password: pmadmin pmadmin-pa$$ Upon successful login, the Metadata administration page will appear. Click on the 'Generate new service provider metadata' button. The 'Metadata generation' page will appear. In the 'Metadata generation' page, configure the following fields, leaving the remaining fields with their default values: 1. Entity ID = http(s)://<serveraddress>, where <serveraddress> is the network address of SmartPatch Server. Note that Entity ID is a unique identifier for an identity or service provider, and the value is included in the generated metadata. Note also that with some ID Providers the Entity ID should be the same as the Audience Restriction field on the IdP side. 2. Entity base URL = where <serveraddress:port> is the network address and port that SMARTPATCHServer is running on. Click the 'Generate metadata' button. The 'Metadata detail' page will appear. You will see two blocks of generated data: Metadata and Configuration, with instructions at the foot of the page. Follow the instructions, and at the third bullet-point of the instructions, note: - the location within the file '<Apache Tomcat Installation Directory>/webapps/ROOT/WEB- INF/securityContext.xml' to paste the generated Configuration is marked in the file with the tag '<!-- add Service Provider metadata here- ->'. - ensure that idpdiscovery is disabled in the generated Configuration that you pasted into the 'securitycontext.xml' file: <property name="idpdiscoveryenabled" value="false"/> 3. Stop Apache Tomcat 4. In the configuration file 'server.properties' in the SMARTPATCHServer working directory, configure the following properties: authentication-methods=saml Note that applying any changes to the 'server.properties' file should be done while the Apache Tomcat process is stopped. The 'saml-user-key' property should be specified as the name of the attribute (for example, ' Address', 'userid', etc.) which is returned with the SAML assertion as a part of the authentication process. This attribute should be set on the IdP side. During the SmartPatch login process, the value of the attribute will be matched to a user name in SmartPatch, in which case the user will be automatically logged in. Note that it is necessary that such a matching user name exists in the SmartPatch database, otherwise the login attempt will be rejected. 5. Start Apache Tomcat 13

14 Configuring the Identity Provider (IdP) Configuring the IdP will vary depending on the IdP vendor / application. The following information specifies a typical set of parameters required for the IdP configuration: Single sign on URL = http(s)://<serveraddress>/saml/sso, where <serveraddress> is the network address of SmartPatch Server Audience URI (SP Entity ID) = <serveraddress> is the network address of SmartPatch Server. Note that this value should be the same as the Entity ID value used when creating the Service Provider metadata in step 2) of section 13. Define attributes that will be returned with the SAML assertion. For example, in step 4) of section 13, if you specified saml-user-key= address you should define an attribute entry with Name = Address and Value = ${user. } Verifying the SSO Configuration 1. Clear your browser cache. 2. Browse to 'http(s)://<serveraddress:port>', where <serveraddress:port> is the network address and port that SmartPatch Server is running on. Note that the form of the <serveraddress> should be as specified in the Entity base URL parameter (see step 2) of section 13). 3. You will be redirected to the IdP login page. 4. Log in to the IdP using your SSO credentials. After a successful login you will be redirected to the SmartPatch start page. 5. On the SmartPatch start page, click the link "Start SmartPatch" and execute the jnlp file. 6. You will be automatically logged into the application with the user name supplied in the SAML assertion attribute. Once the SSO configuration has been verified, it is recommended to disable access to the metadata administration by commenting out the following servlet mapping in the file '<Apache Tomcat Installation Directory>/webapps/ROOT/WEB-INF/web.xml': <servlet-mapping> <servlet-name>saml</servlet-name> <url-pattern>/saml/web/*</url-pattern> </servlet-mapping> 14

15 SSL Configuration To enable SSL communication on SmartPatch Server, the ssl-enabled property should be set to have the value true. Note that in addition to setting this property, SSL communication is also required to be configured at the Apache Tomcat level (or Apache Web Server level if Apache Web Server is a front-end to Apache Tomcat). Please refer to the Apache Tomcat or Apache Web Server documentation for details on how to configure SSL on these platforms. Note also that client-server communication requires that the server SSL certificate is trusted by Java on the client machines. If the SSL certificate was issued by a recognized certification authority, then no further action is required to establish the trust. If the server SSL certificate is not trusted (for example if it is selfsigned or was not issued by a recognized certification authority), the certificate will be required to be imported into the Java 'cacerts' trust store on each client machine. Property Description Default ssl-enabled When set to true, SSL communication is enabled. false Table 5: SSL Properties 15

16 Logging Configuration The properties described in Table 6 specify parameters relating to server-side application level logging. Property Description Default logging-level log-remove-delay log-remove-action log-remove-archivefile Table 6: Logging Properties Specifies the details of the server logs. When set to debug,the logging is more detailed. Possible values are info and debug. Specifies the number of days logs should be stored. -1 means that logs are never deleted / archived automatically. Specifies the action to perform on logs that are older than the number of days specified in log-remove-delay. Possible values are archive and delete. Specifies the file to which logs older than the number of days specified in log-remove-delay are archived. info -1 archive logs/logs.old.zip Miscellaneous Configuration Table 7 describes miscellaneous properties that have not been described in other sections of this guide. Property Description Default session-expiry If a client session has been inactive for the time (in 480 minutes) specified by this property, then the server will expire the client session. languages file-types server-poll-interval dir-file-cache Specifies the enabled user interface language packs. Users can select from these user interface languages in a list box on the login screen. The value should be a comma-separated list of languages. The available languages are NL (Dutch), EN (English), DE (German), FR (French), ES (Spanish) and IT (Italian). A comma-separated list of file types that are allowed to be uploaded to the server as file uploads using the File Management function in the user interface. An empty or missing property indicates that all file types are allowed. The refresh rate in seconds that SmartPATCH Client will use for polling SmartPatch Server to retrieve any pending updates. Specifies the directory where application files are cached on the client machine. NL,EN,DE,FR,ES, IT 30 '.patchmanager /file-cache' in the operating system user home folder on the client machine. 16

17 dir-image-cache download-cache google-maps-key google-maps-client google-maps-private-key google-maps-language server-type show-server-type-in-gui server-type-gui-color start-page-footer Table 7: Miscellaneous Properties Specifies the directory where application images are cached on the client machine. When set to false, the client cache of application images and files is not synchronized with the server at client start up. In this case, any stale images or files will be synchronized on-demand by the client at the moment that they are needed by the application. The API key for the Google Static Maps API. Applicable when integrating Google Maps images into location overview backgrounds. The client ID for the Google Static Maps API. Applicable when integrating Google Maps images into location overview backgrounds. The private key for signing communication with the Google Static Maps API. Applicable when integrating Google Maps images into location overview backgrounds. Optional property for specifying the language code when communicating with the Google Static Maps API. Applicable when integrating Google Maps images into location overview backgrounds. Property for specifying the server usage type for example to distinguish between Production, Backup and Development server instances. The specified value for server-type will appear in the home page below the 'Start' section. If a value for the server-type property has been specified, then setting this property to true will result in the server type also being displayed in the log-in dialog, in the toolbar of the main window of the GUI, and in the title of the main window of the GUI. If a value for the server-type property has been specified and the show-server-type-in-gui property has been set to true, then this property specifies the text color for the server type in the toolbar of the main window of the GUI. The value should take the form of an RGB color specified in the format 'rgb(r,g,b)'. Property for specifying text that appears as a footer in the home page. '.SmartPatch/im age-cache' in the operating system user home folder on the client machine. true false rgb(255,255,255 ) 17

18 Client-Server Compression In a network scenario where the latency between SmartPatch Client and SmartPatch Server is significant or the bandwidth is limited, compressing the HTTP(S) traffic between SmartPatch Client and SmartPatch Server can be advantageous. Please refer to the Apache Tomcat or Apache Web Server documentation for details on how to configure compression on these platforms. Note that the MIME type of traffic between SmartPatch Client and SmartPatch Server is 'application/x-java-serialized-object', therefore this MIME type should be explicitly included in the compression configuration. 18