Wiki source code of Einmalanmeldung

Hide last authors

version	line-number	content
18.1	1	//Single sign-on// for {{smallcaps}}Ntlm{{/smallcaps}} and Kerberos is a {{formcycle/}} license module which is subject to additional costs.
2.1	2
1.1	3	{{content/}}
	4
12.1	5	{{warning}}
18.1	6	We would like to inform you that in future we will say goodbye to {{smallcaps}}Ntlm{{/smallcaps}} as an option for single sign-on. We are following a general recommendation from Microsoft, according to which {{smallcaps}}Ntlm{{/smallcaps}} should no longer be used by applications in the future due to insufficient security mechanisms ([[statement from Microsoft>>https://docs.microsoft.com/en-us/openspecs/windows_protocols/ms-nlmp/1e846608-4c5f-41f4-8454-1b91af8a755b?redirectedfrom=MSDN\|\|rel="noopener noreferrer" target="_blank"]] or [[statement in the forum>>https://answers.microsoft.com/en-us/msoffice/forum/all/ntlm-vs-kerberos/d8b139bf-6b5a-4a53-9a00-bb75d4e219eb\|\|rel="noopener noreferrer" target="_blank"]] under Chapter 3). Microsoft then published patches to improve security, but these will no longer work with the current {{smallcaps}}Ntlm{{/smallcaps}} implementation in FORMCYCLE. Since it is not recommended to continue using the module, we will stop further development of the module from FORMCYCLE version 7 onwards.
12.1	7
18.1	8	For existing customers we offer to switch to Kerberos for free. The activation for Kerberos is done automatically in the licence of V7, if {{smallcaps}}Ntlm{{/smallcaps}} has already been licensed.
12.1	9	{{/warning}}
	10
18.1	11	{{figure image="single_sign_on_ntlm_en.png" width="600"}}
	12	User interface for setting up {{smallcaps}}Ldap{{/smallcaps}} authentication via {{smallcaps}}Ntlm{{/smallcaps}}. Available only if the license allows it.
1.1	13	{{/figure}}
	14
18.1	15	{{smallcaps}}Ntlm{{/smallcaps}} (NT LAN Manager) can be used to authenticate users of a form.
1.1	16
18.1	17	A common use case are forms used internally by some company, and that may be accessed only by the employees of that company. The user data of the active directory can be accessed via {{smallcaps}}Ntlm{{/smallcaps}}.
	18
1.1	19	{{info}}
18.1	20	{{smallcaps}}Ntlm{{/smallcaps}} may not be available depending on your license.
1.1	21	{{/info}}
	22
18.1	23	== Using NTLM ==
1.1	24
18.1	25	Activate this option to use {{smallcaps}}Ntlm{{/smallcaps}}.
1.1	26
18.1	27	=== Synchronize with {{fserver/}} ===
1.1	28
18.1	29	Activate this option to transmit the current configuration to all connected and available {{fserver number="plural"/}} when saving these settings.
1.1	30
18.1	31	=== Domain controller host ===
1.1	32
18.1	33	The host (FQN) of the active directory controller used for authenticating users via {{smallcaps}}Ntlm{{/smallcaps}} and transmitting their data over {{smallcaps}}Ldap{{/smallcaps}}.
1.1	34
	35	{{code language="none"}}
18.1	36	Example: domain.example.com
1.1	37	{{/code}}
	38
18.1	39	Connection to the {{smallcaps}}Ldap{{/smallcaps}} server for the {{smallcaps}}Ldap{{/smallcaps}} search account has been established successfully
1.1	40
18.1	41	== NTLM authentication ==
1.1	42
18.1	43	The following settings are required for enabling users to authenticate via {{smallcaps}}Ntlm{{/smallcaps}}.
1.1	44
18.1	45	=== Host name of the domain controller host ===
1.1	46
18.1	47	The host name of the active directory controller.
	48
1.1	49	{{code language="none"}}
18.1	50	Example: domain
1.1	51	{{/code}}
	52
18.1	53	=== Windows domain name ===
1.1	54
18.1	55	Different forms of the domain name can be used depending on the active directory.
1.1	56
	57	{{code language="none"}}
18.1	58	Example: example.de oder example0
1.1	59	{{/code}}
	60
	61	{{info}}
18.1	62	Here you must specify the domain name to which the user accounts to be authenticated belong.
	63	This domain name may be different from the domain of the computer account (This is the computer's NetBIOS name, not the DNS / FQDN name).
1.1	64
18.1	65	The Windows domain name to be used can be determined, for example, by opening a Windows console (//Start / Run / cmd//) on a client logged into the domain and entering the following command:
1.1	66	echo %userdomain%
	67	{{/info}}
	68
18.1	69	=== Computer account ===
1.1	70
18.1	71	The computer account must have been granted permission to perform user verification. It must not be a regular user account.
1.1	72
	73	{{info}}
18.1	74	A computer account is recognizable by the '$' character in the domain name. e.g. example$@domain.de
1.1	75	{{/info}}
	76
18.1	77	We are currently unable to provide a description of the procedure for creating a computer account in the Active Directory server and this must be referred from external sources in the relevant documentation.
1.1	78
18.1	79	=== computer account password ===
1.1	80
18.1	81	Password of the computer account.
1.1	82
18.1	83	== LDAP user lookup ==
1.1	84
18.1	85	The following settings concern the user lookup after a successful {{smallcaps}}Ntlm{{/smallcaps}} authenication.
1.1	86
	87	=== Port ===
	88
18.1	89	The port for connecting to the {{smallcaps}}Ldap{{/smallcaps}} server for the user lookup.
1.1	90
18.1	91	=== SSL encryption ===
1.1	92
18.1	93	Enables SSL encryption when communicating the the {{smallcaps}}Ldap{{/smallcaps}} server.
1.1	94
18.1	95	=== Hop count ===
1.1	96
18.1	97	The number of hop counts or referrals. Setting this to 0 disables following references.
1.1	98
18.1	99	=== User account (with domain) ===
1.1	100
18.1	101	Account to be used for looking up users. It must have been granted permission to perform user lookup.
1.1	102
	103	{{code language="none"}}
18.1	104	Example: ldap@example.de
1.1	105	{{/code}}
	106
18.1	107	=== User account password ===
1.1	108
18.1	109	Password of the user account.
1.1	110
18.1	111	=== Base DN für user lookup ===
1.1	112
18.1	113	{{smallcaps}}Ldap{{/smallcaps}} base DN used for looking up authenticated users.
1.1	114
	115	{{code language="none"}}
18.1	116	Example: ou="users", dc="example", dc="de"
1.1	117	{{/code}}
	118
	119
18.1	120
	121	== Settings for Kerberos authentication ==
	122
	123	{{figure image="single_sign_on_kerberos_en.png" width="600"}}
	124	User interface for editing the settings for Kerberos authentication. Available only when the license includes this option.
1.1	125	{{/figure}}
	126
18.1	127	Kerberos can be used to authenticate form users. This is often used for internal forms meant only for the employees of a company. The data of the current user can be retrieved from an active directory as well.
1.1	128
18.1	129	Kerberos authentication is available only when the license includes this option.
1.1	130
18.1	131	=== Use Kerberos ===
1.1	132
18.1	133	Activate this switch to enable Kerberos authentication.
1.1	134
18.1	135	=== Synchronize with frontend server ===
1.1	136
18.1	137	When activated, all changes to the configuration will be sent to all available frontend servers.
1.1	138
18.1	139	=== Username ===
1.1	140
18.1	141	The Window Domain account required for accessing the Key Distribution Center (KDC) and beginning the authentication process.
1.1	142
18.1	143	Normally this is the user account of the active directory that is setup as a service account.
	144
1.1	145	{{info}}
18.1	146	When no //default_realm// has been specified in the section //[libdefaults]// of the file //krb5.conf//, you will need to enter the username with a domain (FQDN).
	147	Example: user@EXCAMPLE.COM
1.1	148	{{/info}}
	149
	150	{{info}}
18.1	151	To this user you must, in Active Directory for example, register the hosts of the urls and the computer name (computer name and FQDN inside the domain) to be used as ServicePrincipalName (SPN) beginning with the service class HTTP. You can find more information [[here>>https://social.technet.microsoft.com/wiki/contents/articles/717.service-principal-names-spn-setspn-syntax.aspx\|\|rel="noopener noreferrer" target="_blank"]] or [[here>>https://docs.microsoft.com/en-us/windows-server/networking/sdn/security/kerberos-with-spn\|\|rel="noopener noreferrer" target="_blank"]].
1.1	152	{{/info}}
	153
18.1	154	=== Password ===
1.1	155
18.1	156	Password of the service account.
1.1	157
18.1	158	=== File krb5.conf ===
1.1	159
18.1	160	Enter the content of the file //krb5.conf//, ie. the configuration file for Kerberos.
1.1	161
18.1	162	Among other settings, the available encryption methods, the current real and its mapping to a KDC should be set.
1.1	163
18.1	164	==== File structure ====
1.1	165
18.1	166	The file format is similar to Windows INI files. It contains of individual sections, introduced by their names in brackets. Each section may or may not contain several key-value pairs:
	167
	168	{{code language="javascript" title=""}}
1.1	169	foo = bar
	170	{{/code}}
	171
18.1	172	or
1.1	173
18.1	174	{{code language="javascript" title=""}}
1.1	175	foobar = {
	176	foo = bar
	177	some = input
	178	}
	179	{{/code}}
	180
18.1	181	==== Section names ====
1.1	182
18.1	183	* {{litem title="[libdefaults]"}} Contains settings used by the Kerberos library v5.{{/litem}}
	184	* {{litem title="[realms]~}~} Realm-specific settings and contact information.{{/litem~}~}
	185	* {{litem title="}}A list of supported session key encryption methods that should be requested by the client when performing an AS (authentication server) request. The priority of each method is given by the order in which they have been specified, the first one being the method with the highest priority. Several methods can be separated with commas or spaces.{{/litem}}
	186	* ~{~{litem title="default_tgs_enctypes}}A list of supported session key encryption methods that should be requested by the client when performing a TGS (ticket granting server) request. The priority of each method is given by the order in which they have been specified, the first one being the method with the highest priority. Several methods can be separated with commas or spaces.~{~{/litem}}
	187	* {{litem title="permitted_enctypes"}}: A list of all allowed session key encryption methods.{{/litem}}
1.1	188
18.1	189	A simple configuration for the //[libdefaults]// section might look as follows:
1.1	190
18.1	191	{{code language="javascript" title=""}}
1.1	192	[libdefaults]
	193	default_realm = EXAMPLE.COM
18.1	194	default_tkt_enctypes = aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 des3-cbc-sha1 arcfour-hmac-md5 camellia256-cts-cmac camellia128-cts-cmac des-cbc-crc des-cbc-md5 des-cbc-md4
	195	default_tgs_enctypes = aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 des3-cbc-sha1 arcfour-hmac-md5 camellia256-cts-cmac camellia128-cts-cmac des-cbc-crc des-cbc-md5 des-cbc-md4
	196	permitted_enctypes = aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 des3-cbc-sha1 arcfour-hmac-md5 camellia256-cts-cmac camellia128-cts-cmac des-cbc-crc des-cbc-md5 des-cbc-md4
1.1	197	{{/code}}
	198
	199	===== [realms] =====
	200
18.1	201	Each key in the //[realms]// section represents the name of a Kerberos realm. The value is a list of mappings, defining the properties of each realm. The following properties can be set:
1.1	202
18.1	203	* kdc: The name or address of a server running a KDC (key distribution center) for this realm, usually the server with the active directory. When necessary, the port number can be specified by appending it separated by a column.
1.1	204
18.1	205	A simple configuration for the //[realms]// section might look as follows:
1.1	206
18.1	207	{{code language="javascript" title=""}}
1.1	208	[realms]
	209	EXAMPLE.COM = {
	210	kdc = domain.example.com
	211	}
	212	{{/code}}
	213
	214	===== [domain_realm] =====
	215
18.1	216	The section //[domain_realm]// contains a mapping from domain names or host names to Kerberos realm names. The key can be a host or domain name, but domain names must be prefixed with a period. The value must be the name of a Kerberos realm for this host or domain. Host and domain names should be spelled with lower case letters.
1.1	217
18.1	218	A simple configuration for the //[domain_realm]// section might look as follows:
1.1	219
18.1	220	{{code language="javascript" title=""}}
1.1	221	[domain_realm]
	222	.example.com = EXAMPLE.COM
	223	{{/code}}
	224
18.1	225	=== File login.conf ===
1.1	226
18.1	227	The content of the file //login.conf//, which contains login-related settings such as the authentication method between clients and servers.
1.1	228
18.1	229	A sample configuration might look as follows:
1.1	230
	231	{{code language="java" title=""}}
	232	spnego-client {
	233	com.sun.security.auth.module.Krb5LoginModule required;
	234	};
	235
	236	spnego-server {
	237	com.sun.security.auth.module.Krb5LoginModule required
	238	refreshKrb5Config=true
	239	storeKey=true
	240	isInitiator=false;
	241	};
	242	{{/code}}
	243
18.1	244	=== Client module name ===
1.1	245
18.1	246	The name in the //login.conf// file for the client to be used, eg. {{code language="none"}}spnego-client{{/code}}.
1.1	247
18.1	248	=== Server module name ===
1.1	249
18.1	250	The name in the //login.conf// file for the server to be used, eg. {{code language="none"}}spnego-server{{/code}}.
1.1	251
	252	{{error}}
18.1	253	When you keep getting a HTTP 400 error with Kerberos activated, the most likely cause is that the HTTP header size of the Kerberos ticket exceeds the default header size limit of the application server, eg. Tomcat of JBoss. See the help pages on [[changing the HTTP header size limit>>doc:Formcycle.SystemSettings.TomcatSettings.LimitHTTPHeader]].
1.1	254	{{/error}}
	255
18.1	256	== LDAP user search ==
1.1	257
18.1	258	The following settings are required to retrieve information about the authenticated user from an {{smallcaps}}Ldap{{/smallcaps}} (MS active directory). This data is then available in the form and can be accessed by JavaScript code.
1.1	259
18.1	260	=== Domain controller host ===
1.1	261
18.1	262	FQN (fully qualified name) and port of the active directory controller.
1.1	263
18.1	264	Example: {{code language="none"}}domain.example.com Port: 389{{/code}}
1.1	265
18.1	266	=== SSL connection ===
1.1	267
18.1	268	When activated, all communications with the LDAP server will be encrypted with SSL.
1.1	269
18.1	270	=== Referral hops ===
1.1	271
18.1	272	The maximum number of referral hops that may be performed on the LDAP server. Setting this to {{code language="none"}}0{{/code}} deactivates referral hops and no references will be followed.
1.1	273
18.1	274	=== User account (with domain) ===
1.1	275
18.1	276	This account must have been granted permission to send search queries to the active directory.
	277
1.1	278	{{info}}
18.1	279	This needs to be a username suffixed with the domain.
	280	Example: {{code language="none"}}user@EXCAMPLE.COM{{/code}}
1.1	281	{{/info}}
	282
18.1	283	=== User account password ===
1.1	284
18.1	285	Password for the user account.
1.1	286
18.1	287	=== Base DN for user lookup ===
1.1	288
18.1	289	The LDAP baseDN used for looking up the authenticated user.
1.1	290
18.1	291	Example: {{code language="none"}}ou="intern", dc="example", dc="com"{{/code}}
1.1	292
18.1	293	== Theoretical consideration of the connection of several KDCs/domains ==
1.1	294
18.1	295	If multiple KDC servers or domains are desired for a global Kerberos login ability, this is theoretically possible via the standard MIT Kerberos implementation provided by Java and used by FORMCYCLE. However, the following configurations should be noted here:
	296
	297	* For each KDC server/domain a separate realm must be defined.
	298	* The list to be defined under [domain_realm] must be used to specify which request URL should be handled by which realm.
	299	* If cross realm authentication is desired, a cross realm trust must be established. This serves to the purpose that a user from realm A can also log in within the realm B. For example, this can be realized with a direct realm trust where principals are created on each relevant server against the other realms. For the realms A.REALM.COM and B.REALM.COM this would be for exemplary krbtgt/A.REALM.COM@B.REALM.COM and krbtgt/B.REALM.COM@A.REALM.COM.
	300	* Use the same name and a strong password for the service principal or configure a keytab file.
	301	* To query the correct user data after the Kerberos login, either an LDAP server with access to the whole forest of the realms or the functionality of the client-specific LDAP servers must be configured. It may also be necessary to adjust the responsible LDAP filter.
	302
	303	== Make user data available to forms ==
	304
	305	The LDAP user data for the currently authenticated user are stored in the JavaScript object {{code language="none"}}window.XFC_METADATA.user.rawData{{/code}} and can be accessed via JavaScript.
	306
1.1	307	{{info}}
18.1	308	Which data the JSON structure contains under the rawData property depends mainly on the read rights of the LDAP account, which executes the user search in the LDAP system.
1.1	309	{{/info}}
	310
18.1	311	To access the property ~/~/userPrincipalName~/~/ of the user from JavaScript, use the following code:
1.1	312
	313	{{code language="javascript"}}
	314	try {
	315	// Auslesen der Property und Anzeige in einem Label
	316	var elem = $('[name=txt1]');
	317	var ldap = XFC_METADATA.user.rawData;
	318	if(ldap.hasOwnProperty('userPrincipalName')) {
	319	elem.html(ldap.userPrincipalName);
	320	}
	321	} catch (err) {}
	322	{{/code}}