TIF ENOVIA Connector - Credentials

1. Credentials

The <Credentials> element contains the following attributes:

containerManaged: A boolean value. Specifies if authentication is carried out via the servlet container. See chapter below how to configure this.
runAs: A string value. Defines the name of the ENOVIA™ user that we will run the service as.
runAsSuperUser: A boolean value. Useful together when containerManaged=true and you want to run the service as a super user, while authentication is required.

Valid child elements are defined in the table below

Element Description Mandatory

Element	Description	Mandatory
`<SecurityContext>`	Used for defining the ENOVIA/3DExperience security context. See below how to configure this.	No
`<Role>`	In case container managed authentication is enabled, you may define additional roles, which the authenticated user must have in order to gain access. These roles are typically not ENOVIA/3DExperience roles, in case of Kerberos authentication these will be roles from your Active Directory. Note that if you specify multiple roles, the user is only required to have one of the listed roles in order to get access. Example below: `<Credentials containerManaged="true" ...> <Role name="name-of-role1" /> <Role name="name-of-role2" /> ... </Credentials>`	No.
`<Assignments>`	Specify additional ENOVIA/3DExperience assignments the user must have in order to proceed. Example below: `<Credentials ...> <Assignments> <Role name="Desing Engineer" /> <Role name="Another Role" /> </Assignments> ... </Credentials>`	No

<SecurityContext>

Used for defining the ENOVIA/3DExperience security context.

See below how to configure this.

<Role>

In case container managed authentication is enabled, you may define additional roles, which the authenticated user must have in order to gain access. These roles are typically not ENOVIA/3DExperience roles, in case of Kerberos authentication these will be roles from your Active Directory.

Note that if you specify multiple roles, the user is only required to have one of the listed roles in order to get access. Example below:

<Credentials containerManaged="true" ...>
    <Role name="name-of-role1" />
    <Role name="name-of-role2" />
    ...
</Credentials>

No.

<Assignments>

Specify additional ENOVIA/3DExperience assignments the user must have in order to proceed. Example below:

<Credentials ...>
    <Assignments>
        <Role name="Desing Engineer" />
        <Role name="Another Role" />
    </Assignments>
    ...
</Credentials>

1.1. Security Context

Via the <SecurityContext> element you define what security context to use. You may do the following.

Point out a mapping file
1. Or use a default mapping file
Specify a named security context
Or use the "default" security context as configured for the ENOVIA user

To point out a mapFile use the syntax below.

The file is relative to ${TIF_ROOT}/modules/enovia/etc

<SecurityContext mapFile="sec-mapping.xml" />

Use the default mapping file. The default file is specified via the property securityMapping.defaultFile, and the default value is security-context-mapping.xml.

The file is relative to ${TIF_ROOT}/modules/enovia/etc

<SecurityContext useDefaultMapFile="true" />

The format of the mapping file is shown below:

<Contexts>
    <Context name="Design Engineer.Company Name.GLOBAL">
        <User is="user1" />(1)
        <User is="user2" />
        <User is="user3" />

        <Role is="engineer" /> (2)
        <Role is="designer" />

        <Parameter name="test" is="something" /> (3)
        <Parameter name="x" is="y" />
    </Context>
    <Context name="...">...</Context>
    <Context name="...">...</Context>
</Contexts>

NOTE that specifying user and role requires having enabled container managed authentication (Kerberos or Basic Authenticaton etc.)

1	Specifies certain users to match against
2	Specifies additional roles the user should have
3	Specifies additional parameters and value to be evaluated In case of a REST service, the parameters are the request parameters passed to the service.

The evaluation logic is:

User list is EMPTY or user is in list
Role list is EMPTY or user have one of the roles in the list
Parameter list is EMPTY or one of the parameters have the expected value

If A AND B AND C is satisfied, then use the security context defined for this "rule".

To use a specific Security Context:

<SecurityContext use="Design Engineer.Company Name.GLOBAL" />

Specify using the default security context.

<SecurityContext useDefault="true" />

1.2. Container Managed Security

You can enable security on the servlet container level and either use Kerberos/SPNego authentication OR use Basic authentication and authenticate against the ENOVIA™ database.

1.3. Configure Security Realm

Within the ${TIF_ROOT}/modules/enovia/etc/module.custom.properties, you need to specify what login service to be used including its realm and optionally some extra parameters.

The login services currently supported are

enovia: A login service that will authenticate the remote user against the ENOVIA™ database.
ldap: A login service that will authenticate the remote user against a LDAP directory (for example Active Directory)
spnego: A login service supporting Single Sign On against Active Directory.

In order to use Spnego authentication, also read this document in order to setup the core parts of Spnego/Kerberos.

1.3.1. LDAP Authentication

If the "loginService" is set to "ldap", TIF will authenticate users against a LDAP directory.

http.webapp.app-id.loginService=ldap
http.webapp.app-id.realm=Webservices

The second value defines the "realm". (See https://www.ietf.org/rfc/rfc2617.txt for more information about realms and basic authentication).

There are some additional LDAP settings required to be defined. You can specify global LDAP parameters and/or web application specific LDAP parameters. In most cases you will be fine with only global LDAP settings.

For convenience, the application specific parameters will be merged with the global LDAP parameters. Hence you only need to override/define the parameters that is different on the application level.

Please see the table below.

The global parameter name is ldap., while the application specific parameter are named like http.webapp.<APP_NAME>.ldap.

Parameter Description Required

Parameter	Description	Required
ldap.server	Defines the server or list of LDAP servers. Separate with space if using multiple.	Yes
ldap.rootDN	Defines the root dn, where all LDAP searches starts from. If we can start a search starting at a sub-node (as opposed to root), you get a better performance because it narrows down the scope of a search. This field specifies the DN of such a subtree.	No
ldap.userSearchBase	The relative DN (From the root DN) that further narrow down searches to the sub-tree. If you do specify this value, the field normally looks something like "ou=people".	No
ldap.userSearchFilter	This field determines the query to be run to identify the user record. The query is almost always "uid={0}" as per defined in RFC 2798, so in most cases you should leave this field empty and let this default kick in. If your LDAP server doesn’t have uid or doesn’t use a meaningful uid value, try "mail={0}", which lets people login by their e-mail address. If you do specify a different query, specify an LDAP query string with marker token "{0}", which is to be replaced by the user name string entered by the user.	Yes
ldap.groupMembershipAttribute	If the user entry in the LDAP tree contains an attribute with the group membership, then specify that attribute here. Otherwise we need to query for the groups a user belongs to.	Either this or the groupSearchBase / groupSearchFilter needs to be defined.
ldap.groupSearchBase	This field determines the query to be run to identify the organizational unit that contains groups. The query is almost always "ou=groups" so try that first, though this field may be left blank to search from the root DN.	Not needed, but if the groupMembershipAttribute is undefine you can use this to make the group query faster.
ldap.groupSearchFilter	Defines the search filter for groups. In case we need to search the LDAP tree for group membership this needs to be defined. The marker token "{0}" is replaced with the current user’s DN. Example: `(& (member={0}) (objectclass=group) )`	Yes unless groupMembershipAttribute is defined.
ldap.managerDN	If your LDAP server doesn’t support anonymous binding, then we would have to first authenticate itself against the LDAP server. A DN typically looks like CN=MyUser,CN=Users,DC=mydomain,DC=com although the exact sequence of tokens depends on the LDAP server configuration. It can be any valid DN as long as LDAP allows this user to query data.	Probably Yes
ldap.managerSecret	The password for the manager DN	Probably Yes
ldap.displayNameLDAPAttribute	The attribute holding the display name. Per default we use the CN of the user entry.	No
ldap.emailAddressLDAPAttribute	The attribute holding the email value. Per default we use the field `mail`. This field is currently not used so you can leave it blank.	No
ldap.pooled	Whether or not to pool the LDAP connections	No

ldap.server

Defines the server or list of LDAP servers.

Separate with space if using multiple.

Yes

ldap.rootDN

Defines the root dn, where all LDAP searches starts from.

If we can start a search starting at a sub-node (as opposed to root), you get a better performance because it narrows down the scope of a search. This field specifies the DN of such a subtree.

ldap.userSearchBase

The relative DN (From the root DN) that further narrow down searches to the sub-tree.

If you do specify this value, the field normally looks something like "ou=people".

ldap.userSearchFilter

This field determines the query to be run to identify the user record. The query is almost always "uid={0}" as per defined in RFC 2798, so in most cases you should leave this field empty and let this default kick in.

If your LDAP server doesn’t have uid or doesn’t use a meaningful uid value, try "mail={0}", which lets people login by their e-mail address.

If you do specify a different query, specify an LDAP query string with marker token "{0}", which is to be replaced by the user name string entered by the user.

Yes

ldap.groupMembershipAttribute

If the user entry in the LDAP tree contains an attribute with the group membership, then specify that attribute here.

Otherwise we need to query for the groups a user belongs to.

Either this or the groupSearchBase / groupSearchFilter needs to be defined.

ldap.groupSearchBase

This field determines the query to be run to identify the organizational unit that contains groups. The query is almost always "ou=groups" so try that first, though this field may be left blank to search from the root DN.

Not needed, but if the groupMembershipAttribute is undefine you can use this to make the group query faster.

ldap.groupSearchFilter

Defines the search filter for groups. In case we need to search the LDAP tree for group membership this needs to be defined. The marker token "{0}" is replaced with the current user’s DN.

Example:

(& (member={0}) (objectclass=group) )

Yes unless groupMembershipAttribute is defined.

ldap.managerDN

If your LDAP server doesn’t support anonymous binding, then we would have to first authenticate itself against the LDAP server.

A DN typically looks like CN=MyUser,CN=Users,DC=mydomain,DC=com although the exact sequence of tokens depends on the LDAP server configuration.

It can be any valid DN as long as LDAP allows this user to query data.

Probably Yes

ldap.managerSecret

The password for the manager DN

Probably Yes

ldap.displayNameLDAPAttribute

The attribute holding the display name. Per default we use the CN of the user entry.

ldap.emailAddressLDAPAttribute

The attribute holding the email value.

Per default we use the field mail.

This field is currently not used so you can leave it blank.

ldap.pooled

Whether or not to pool the LDAP connections

Example setup below for Active Directory.

ldap.server=ldapserver.yourdomain.com:3268
ldap.rootDN=DC=yourdomain,DC=com
ldap.managerDN=CN=nameofuser,CN=groupforuser,DC=yourdomain,DC=com
ldap.managerSecret=the_very_secret_string
ldap.userSearchBase=
ldap.userSearchFilter=(&(objectClass=person)(|(sAMAccountName={0})(userPrincipalName={0}@*)))
ldap.emailAddressLDAPAttribute=mail
ldap.displayNameLDAPAttribute=displayName
ldap.groupMembershipAttribute=memberOf
#ldap.groupSearchBase=OU=groups
#ldap.groupSearchFilter=(&(member={0})(objectClass=group))

The managerSecret value can either be defined in plain text, or you can encrypt the password from an MQL client using the "mql encrypt" feature.

<MQL> encrypt password the_password_to_be_encrypted;

The encrypted value can be used in the configuration file if you add the prefix enovia:.

Eg.

ldap.managerSecret=enovia:=vc4QGO6tVoYi

1.3.2. ENOVIA Authentication

If the "loginService" is set to "enovia", TIF will authenticate users against the ENOVIA database.

http.webapp.app-id.loginService=enovia
http.webapp.app-id.realm=Webservices

The second value defines the "realm". (See https://www.ietf.org/rfc/rfc2617.txt for more information about realms and basic authentication).

1.3.3. Spnego Authentication

Secondly, an example for spnego:

http.webapp.app-id.loginService=spnego
http.webapp.app-id.spnego.targetName=HTTP/tifserver.exampledomain.com
http.webapp.app-id.realm=Webservices

Instead of specifying the targetName you may instead point out a property file that holds that value under the key targetName. See below:

http.webapp.app-id.loginService=spnego
http.webapp.app-id.spnego.config=${tif.home}/etc/kerberos/spnego.properties
http.webapp.app-id.realm=Webservices

The spnego.properties defines the targetName like this:

${tif.home}/etc/kerberos/spnego.properties

targetName = HTTP/tifserver.exampledomain.com

1.4. Configure Security Constraints in WEB.XML

Within the "web.xml" file (webapps/app-id/WEB-INF/web.xml) you need to setup the rules for the application.

If you have not started TIF, you will not find the web.xml file, instead it will be found under webapps/app-id/WEB-INF/web.xml.template. Upon start, TIF will copy over the template file unless the web.xml file is found.

Below is an example when using ENOVIA/Basic authentication and how such might look like.

Note that in this example, each user that is supposed to use the web-services must have the role "WS-Integration-User". Note that depending on login service used (ldap or enovia), the role is either a LDAP role or a ENOVIA role.

<security-constraint>
    <web-resource-collection>
        <web-resource-name>blocked</web-resource-name>
        <url-pattern>/service/*</url-pattern>
    </web-resource-collection>
    <auth-constraint>
        <role-name>WS-Integration-User</role-name>
    </auth-constraint>
    <user-data-constraint>
        <transport-guarantee>NONE</transport-guarantee>
    </user-data-constraint>
</security-constraint>
<login-config>
    <auth-method>BASIC</auth-method>
    <realm-name>Webservices</realm-name>
</login-config>

Below is an example for Spnego:

<security-constraint>
    <web-resource-collection>
        <web-resource-name>blocked</web-resource-name>
        <url-pattern>/service/*</url-pattern>
    </web-resource-collection>
    <auth-constraint>
        <role-name>EXAMPLEDOMAIN.COM</role-name>
    </auth-constraint>
</security-constraint>
<login-config>
    <auth-method>SPNEGO</auth-method>
    <realm-name>Webservices</realm-name>
</login-config>