EUSurvey OSS OpenCas installation guide (LDAP & SSO)

Transcription

1 EUSurvey OSS OpenCas installation guide (LDAP & SSO) By default the OSS release has no access to any LDAP structure or to any Single Sign On solution. The only way is to use the internal login system. But with the new OSS version 1.3.1, a SSO and a LDAP solution are available. The only constraint is that only the Jasig SSO 4.1.x solution is supported ( By enabling these solutions you can use your own LDAP structure for the EUSurvey application. The installation and configuration of the Jasig SSO and the LDAP structure is not covered by this document. A. How is EUSurvey working EUSurvey uses the LDAP information for user authentication, to send invitations or to give privileges to a survey for users or a group of users. This was not possible with the previous OSS release. Virtual tree To send invitations or provide privileges to users, EUSurvey uses the LDAP information and renders it to a kind of tree building from the LDAP data. The root level is the "domain" level that can be compared to the institution level. Below the institution level you have the department level. Each department contains groups and each group can contain sub groups etc. The sub levels are split into departments and groups. 04/04/2016 1

2 In the print screen above you can see the kind of tree that can be rendered. To create this tree, EUSurvey uses the data mainly from 2 attributes that are related to the user node in LDAP. The first attribute is the "o" attribute from which we will extract the domain values. The second attribute is the "departmentnumber" attribute that will serve to build the tree with the department groups and sub groups values by splitting the value of the "departmentnumber"(see below for split syntax). This tree is used for the participant functionality as well as for the privilege functionality. B. Solutions for the OSS release We offer 4 solutions for the OSS release to integrate the LDAP data, depending on your requirements: 04/04/2016 2

3 1. Normal version: Choose this option if you have at least one "organization/institution" and multiple "departments/groups" 2. Semi static: You do not have any or only one "organization/institution" but you have multiple "departments/groups" 3. Fully static: You do not have any or only one "organization" and "department/group" but you still want to use your LDAP data 4. No LDAP: Same as the previous OSS version; in this case you do not have to configure anything All you need to do to apply one of these solutions is to configure the "spring.properties" file. B.1 Normal version (multiple domains/departments/groups) B.1.1 LDAP-Configuration of organizations First of all you have to configure your LDAP server to be compliant with the EUSurvey application. The application will get the list of organizations (top level) from the "AuthenticationDomains" entry. This entry corresponds to the root element of the virtual tree. 1. You must create an "ou" entry belonging to the root element of your LDAP structure; the name MUST be "AuthenticationDomains". 2. After that you have to create at least one entry of type "o" belonging to this AuthenticationDomains "ou". These "o" entries will be displayed in the EUSurvey application as the "Domain" values (see below). This "o" entry must also have the "description" attribute. 04/04/2016 3

4 As you can see below, those settings from LDAP are used for the invitation page when you will select the "EU institutions and other bodies" B.1.2 LDAP-Configuration of user entries The user entry MUST contain: An attribute that will link the user to a domain (organization). By default we use the "o" attribute An attribute that is used to build departments and groups of an organisation. By default you can use the "departmentnumber" attribute This means that each user MUST have a "departmentnumber" with a value, to make sure to retrieve them through the EUSurvey search capabilities. To create this virtual hierarchy we use the value that will be split either when find a "." or a "-" character. As example, the value "CORP.DPT1.GRP1-001" on the "departmentnumber" will be transformed into this virtual tree. CORP DPT1 GRP1 001 Here is the list of attributes used by the EUSurvey application. Some of them are required. Attribute Name Mandatory Description o Yes This attribute will store the value of the "domain" of the user and MUST match with one of the domain's values defined (see above) DepartmentNumber Yes The value of groups/department to which the user belongs Uid Yes Is the required field and should be equal to the login user value 04/04/2016 4

5 Sn Yes The last name of the user ecmoniker No recordstatus No Mail No givenname (cn) No The first name of the user telephonenumber No employeetype No B.2 Semi static version (one domain-multiple departments/groups) In this case you only have to adapt your LDAP environment to your user entries. B.2.1 LDAP-Configuration of organizations You have to configure the EUSurvey application to set a fictive organisation (see below). B.2.2 LDAP-Configuration of user entries You have to configure the user entry just as in the normal version (see above), except for the "o" attribute that MUST be empty and will be configured at the EUSurvey application level. B.3 Fully static version (one domain-one department/group) In this approach you don't have any organisation or departments/groups. You only have to adapt your LDAP environment to your user entries. B.3.1 LDAP-Configuration of organizations You have to configure the EUSurvey application to set a fictive organisation (static value; see below) B.3.2 LDAP-Configuration of user entries You have to configure the user entry just as in the normal version (see above), except for the "o" attribute that MUST be empty and will be configured at the EUSurvey application level. It should be the same for the "departmentnumbers" attribute. If you don't have this attribute you don't have to create it; if this attribute exists you MUST leave this value empty. B.4 No LDAP You do not have to configure anything; just let the default LDAP properties value. C. Configure EUSurvey to enable the functionalities Once you have adapted your LDAP environment to fit the EUSurvey application, you have to configure EUSurvey to map your LDAP attributes with the attributes needed by the application. Using the Jasig SSO with EUSurvey To use the SSO solution you have to adapt the spring.properties files by using these properties: ecashost= ecaslogout= ecasvalidationhost= 04/04/2016 5

6 showecas=true casoss=true Property name Ecashost Ecaslogout Ecasvalidationhost Description The address of the login form of the Open Cas (Jasig) application. You also have to include the port number (default is 8443; see example above) The address of the Jasig Cas application that will call the logout method to remove the credential The full address where the Jasig Cas solution is available Do not forget to allow the EUSurvey application to have access to the Cas application. If not, you will not be permitted to use the Jasig login with the EUSurvey application (you have to register the EUSurvey application with the Open Cas solution). For more information on how to register EUSurvey with the OpenCas application, see documentation at ( Adapting the LDAP server to the EUSurvey requirements If you want to use your own LDAP environment through the Jasig SSO solution ( please follow the steps below in order to get access to all EUSurvey functionalities (invitation, etc.) This has to be configured in the spring.properties file where you will find a section dedicated to the LDAP mapping. Below please find a version of the properties file: # ldap configuration LdapUrl=ldap://localhost:10389 LdapContextFactory=com.sun.jndi.ldap.LdapCtxFactory LdapSecurityPrincipal=uid\=admin,ou\=system LdapSecurityCredentials=mypassword LdapSecurityAuthentication=simple ldap.search.user.format=uid\=%s,ou\=users,dc\=example,dc\=com ldap.search.format=ou\=users,dc\=example,dc\=com #2 options # either you give the attribute name used in your own LDAP # either you can set a default value. To detect if it is a default value you must start the value with a $ (the $ that will not be taken into account, of course, for the value) ldap.mapping.user.sn=sn ldap.mapping.user.uid=uid ldap.mapping.user.ecmoniker=uid ldap.mapping.user.givenname=givenname ldap.mapping.user.mail=mail ldap.mapping.user.telephonenumber=telephonenumber ldap.mapping.user.employeetype=employeetype ldap.mapping.user.recordstatus=recordstatus 04/04/2016 6

7 ldap.mapping.user.recordstatus= ldap.mapping.user.modifytimstamp=modifytimestamp #Attribute that can be replaced by a constant value ldap.mapping.user.o=$my.company.org #if departementnumber is a constant ldap.mapping.user.o MUST also be a constant #ldap.mapping.user.departmentnumber=departmentnumber ldap.mapping.user.departmentnumber=$mydepartment #example: if you set $mydomain, we will get the value mydomain as constant value ldap.mapping.domain.o=$my.company.org ldap.mapping.domain.description=$my Company Organization #participant.default.domain=cec.eusurvey.int participant.default.domain=my.company.org # if you do not have a list of domains (root level), leave them empty # if empty, you have to take the mapping value as constant value ldap.search.domains.format=ou\=authenticationdomains Here is the explanation of the configuration file: Property Required Description LdapUrl Yes The path of your LDAP repository LdapSecurityPrincipal Yes The name of the user used to access the LDAP LdapSecurityCredentials Yes The password of the user ldap.search.user.format Yes The LDAP query string to retrieve one user entry ldap.search.format Yes The LDAP query string to retrieve multiple user entries (e.g.: to get all users belonging to a department/ groups, etc.) ldap.search.domains.format No The specific query string to retrieve the organizations. If you are on the semi or full static data (no organization at LDAP level), leave this field empty. In such a case the value of the organisation will be taken from the ldap.mapping.domain.o property ldap.mapping.user This is the mapping between the user entry of your LDAP environment and the application ldap.mapping.user.sn Yes ldap.mapping.user.uid Yes A unique identifier MUST be present in your LDAP environment. This is used during the logging time and when searching for a specific user. It will serve for the login of the application. If you don't have this "uid" attribute you can specify the "unique id" attribute that is used in your LDAP configuration ldap.mapping.user.ecmoniker Yes Another "uid" needed by the application. If your LDAP environment has nothing comparable then leave the default value which is the name of the "uid" attribute ldap.mapping.user.givenname No The last name of the user ldap.mapping.user.mail Yes The mail of the user, needed in case of invitation ldap.mapping.user.employeetype No Not used for the OSS release, you can leave this property to blank ldap.mapping.user.recordstatus No Not used for the OSS release, you can leave this property to blank ldap.mapping.user.modifytimstamp No Used to check if a user needs to be synchronized on the database due to some modifications after the last synchronize job 04/04/2016 7

8 ldap.mapping.user.o Yes This attribute contains the name of the domain that the user is belonging to. If you don't have such information (see upper) you can set a constant value. This constant value MUST start with the $ sign ex $MyDomain. Moreover, if the departmentnumber attribute is a constant then this attribute MUST also be a constant ldap.mapping.user.departmentnumber Yes See above for explanation. You can use a constant if you don't have such information or only one level for everybody. In this case the constant value MUST start with the $ sign ex $MyGroup ldap.mapping.domain.o Yes See above for explanation about the domain values. If you don't have such information you MUST set a constant value which is starting with the $ sign. If you are using a constant, it MUST have the same value as for the ldap.mapping.user.o property ldap.mapping.domain.description Yes If it is a constant value it MUST start with the $ sign participant.default.domain Yes Attribute containing the value used to select the domain on the participant page in the EUSurvey application. WARNING: if you have set a constant value for the domain (ldap.mapping.domain.o see upper) you have to set the same value here (without the $ sign). For example: if ldap.mapping.domain.o has a value $cec.eusurvey.int, the participant.default.domain MUST have the value cec.eusurvey.int ldap.search.domains.format No This is the query string to get the list of domain value. If you don't have this information (see above), leave this property empty If ldap.search.domains.format has no value, the properties ldap.mapping.domain.o and ldap.mapping.domain.description MUST be a constant value. Should you have further questions, please contact DIGIT_EUSURVEY_OSS@ec.europa.eu 04/04/2016 8