TIF ENOVIA/3DExperience Connector - Configurable SOAP Services

TIF includes an Apache Axis2 installation in order to support SOAP based web-services.

In addition to the standard distribution of Apache Axis2, TIF provides some extended Axis2 functionality that supports creation and deployment of some different kind of SOAP based web-services solely defined in XML file. E.g. no need to implement the webservice in Java, compile and package it as a AAR file.

The kind of configurable web-services you can use in the current TIF release are:

  • Export of data from business object(s).

    • The configuration format allows specifying criteria used to find the business object(s) to export

    • Also, you configure what data to be exported for these objects.

      • It is also possible to point out a Payload Definition that defines the returned meta-data

  • Update of business object(s) data

    • The configuration format allows specifying criteria used to find the business object(s) to update

    • Also, you configure what fields / attributes the web-service client may update and some rules for the values.

The first service is called "configurable export service" and the second is called "configurable update service".

These are described in more detail in the child pages.

Location of Configurable Web Service’s

A configurable web-service is defined in an XML file that should be put inside the following folder:

$\{TIF_ROOT}/modules/enovia/cfg/soapservice

By default, TIF has enabled hot-deployment and hot-update of the Axis2 application meaning that you can add new configurable web-services or update existing at runtime of TIF.

From Definition to Implementation

The web-service definition is defined by you and consists of an XML file. When this file is put into the directory "soapservice", the TIF deployer in Axis2 will pick up the file and scan it. The following actions will take place then:

  • Parse and validate definition

  • Generate a WSDL

  • Compile the WSDL into Axis Data Binding classes (ADB)

  • Generate Java code implementing the service classes.

  • Compiles all source code.

  • Packages all compiled artifacts along with necessary resource into a so called AAR file (Axis archive).

  • The AAR file is deployed into Apache Axis2.

  • Service is ready for use

The final AAR files are stored internally under the following folder inside TIF:

$\{TIF_ROOT}/data/$\{TIF_INSTANCE_ID}/axis2/services

Common Settings

There are some common settings possible to define on a configurable web service. These are defined as attributes on the root-element in the XML definition.

The attributes are:

Attribute Name Description Required

namespace

Used to specify the namespace of the schema in the WSDL.

No

package

Unless defined, a default package name for the generated Java classes will be used.

Note that if you define your package name, ensure that it is unique and will not collide with existing web-service’s.

No

keepSource

A boolean flag that may be used to keep the generated source files. This might be useful for debugging purposes.

No

debug

If set to true the source code is generated with some debug information.

No

serviceDescription

Gives the service a more human friendly description. Unless specified, the service description will be the same as the service name.

No

URL to a Configurable Web Service

The URL to a configurable web service depends on what hostname your TIF server uses, the port TIF will be using (8181 is default), the context path to the jaxws application and finally the name of the XML definition that defines the webservice.

Assuming your configurable webservice is defined in a file called ProductQueryService.xml and the default configurations are used, the URL becomes

http(s)://tif-server:8181/enovia/jaxws/services/ProductQueryService

To obtain the WSDL file for this service, just append the ?wsdl at the end of the URL. Axis2 Installation Details

The Apache Axis2 installation is part of the TIF installation. The place where the Axis2 related files are installed is:

$\{TIF_ROOT}/modules/enovia/webapps/jaxws

TIF has made some changes into the Axis2 configuration files.

If you do any changes in the Axis2 configuration files, ensure that you don’t remove or destroy the TIF specific additions.

Configurable Export Service

The configurable export web-service support is used to quickly setup a SOAP based web-service that can be used by a client to export business object meta data.

Each configuration results in one web-service to be exposed. This kind of web service may have one or two operations (or methods) that can be invoked remotely, namely:

  • Extracting data based upon a list of object id’s

  • Extracting data from object(s) based upon query parameters deciding what object’s to be exported

Below is a sample configuration illustrating some concepts.

<ExportServiceDefinition>
     <Credentials required="true" />
     <ObjectId max="100" />
     <Query>
        <Params>
            <Limit min="1" max="50" />
            <Name allowWildCard="true" />
        </Params>
        <Defaults>
            <Limit>25</Limit>
            <Type>type_Product</Type>
            <Vault>vault_eServiceProduction</Vault>
            <Revision>*</Revision>
            <Where>current matchlist 'Release,Obsolete' ','</Where>
        </Defaults>
    </Query>
     <Extract payload="tvc:payload/ProductDetails.xml"/>
 </ExportServiceDefinition>

The root element of this file must be <ExportServiceDefinition>.

The available child elements are listed in the table below.

Child Element Description Example

<Credentials>

Defines if the client of this web-service must provide a user name / password for an ENOVIA/3DEXPERIENCE user.

If the definition does not contain this element or has the attribute required set to false, the query and data extract will be performed with super-user privileges.

No but recommended.

<ObjectId>

Defines if an operation in the web-service called "getDataForObjectId" should be available.

This method allows passing in ENOVIA/3DEXPERIENCE object-id’s to the service in order to extract data. Note that the service will not perform any check of the validity of these object-id’s.

For example, a client might pass object-id’s pointing to for example business objects of type Part to a service that normally deals with Products.

No but either this or the <Query> element must be present.

<Query>

Defines if an operation in the web-service called "query" should be available.

Depending on the content of this element, the query method can accept a wide range of different input. See below for further details.

No but either this or the <ObjectId> element must be present.

<Extract>

Defines what to be extracted from this web-service. You may point out a payload configuration or define selectables directly in the configuration.

Yes

<Handler>

Defines a custom Java class OR a custom Script file that can be used to perform additional validations.

No

Credentials

If this element is omitted or if the attribute required is set to false then the operations or methods of this web service will be executed with admin privileges.

Example:

<ExportServiceDefinition>
    <Credentials required="true"/>
    ...
</ExportServiceDefinition>

If credentials is required, the user calling the web-service operation is required to enter a valid ENOVIA/3DEXPERIENCE user id / password combination.

It is also possible to use container managed authentication (basic authentication). See Container Managed Credentials for more information.

ObjectId

If the <ObjectId> element is present, this will result in that an operation called getDataForObjectId() is available on the web service.

This element may have one attribute defined called "max". This attribute may be used to limit the number of object-id’s that are allowed to pass in to the operation.

The default value is "-1", meaning that there is no upper limit.

Example:

<ExportServiceDefinition>
    ...
    <ObjectId max="-1" />
    ...
</ExportServiceDefinition>

Query

If the <Query> element is present, this will result in that an operation called "query" is available on the web service.

The query method will accept some input arguments, which are defined by the definition. Lets take a closer look what child elements you may have for the <Query> element:

Child Element Description Required

<Params>

Defines what parameters the client may pass in. See below for details.

No, but probably always used.

<Defaults>

Defines some default settings for the query, such as default where expression or default type pattern etc.

No, but for security reasons recommended as you may not want the client to be able to search upon any data inside the ENOVIA/3DEXPERIENCE database.

These child elements are described below.

Params

The <Params> element defines what input arguments the client may pass in.

The possible child elements are shown in the table below:

Child Element Description Attributes Required Example

<Limit>

Used to allow the client to define a query limit.

You may also say what the min and max value for the limit can be.

min

max

value

No

<Limit min="1" max="1000" value="100"/>

<Type>

If present, allows the client to define a type pattern for the query.

The attribute "wildcardAllowed" may be used to specify if characters such as * and/or ? may be used in the pattern.

The attribute "name" may be used to give this parameter a different name.

wildcardAllowed name

No

<Type wildcardAllowed="false"/>

<Type name="productType"/>

<Name>

Same as <Type>, but applies to the "name pattern" for the query.

See above

No

<Name/>

<Revision>

Same as <Type>, but applies to the "revision pattern" for the query.

See above

No

<Revision/>

<Owner>

Same as <Type>, but applies to the "owner pattern" for the query.

See above

No

<Owner/>

<Vault>

Same as <Type>, but applies to the "vault pattern" for the query.

See above

No

<Vault/>

<Arg>

Defines an argument that affects the where clause of the query.

The Arg element has a child element called <Where>, which contains the where clause. See below for details.

The name attribute is used to provide this argument a valid name.

The required attribute specifies if the client must provide this value or not.

The type attribute may be one of: string, integer, decimal, boolean

The rangeLoader attribute may be used to point out a custom range value provider. The class must implement the interface: com.technia.tif.enovia.jaxws.api.RangeLoader

name

required

type

rangeLoader

No

 
<Arg name="category">
    <Where>${attribute[attribute_Category]} == '%s'</Where>
</Arg>

Arg / Where

Within the where clause of the argument, you use the %s (String.format is used for this) to be replaced with the real value. Note that you might use other format options if you are familiar with the Formatter / String.format in Java.

Defaults

The <Defaults> element defines the default search criteria.

The possible child elements are shown in the table below:

Child Element Description Required Example

<Limit>

Specifies the default find/query limit

No

<Limit>23</Limit>

<Type>

Defines a type in the type pattern.

Each type in the pattern is defined inside it’s own Type tag.

No

<Type>type_HardwarePart</Type> <Type>type_SoftwarePart</Type>

<Name>

See <Type>. Defines the default name pattern

No

<Revision>

See <Type>. Defines the default revision pattern

No

<Owner>

See <Type>. Defines the default owner pattern

No

<Vault>

See <Type>. Defines the default vault pattern.

No

<Where>

Defines the default part of the where clause.

Note: This where expression will be added first to the where clause, before any custom arguments.

No

<Where>current == Released</Where>

Extract

The <Extract> element defines what data to be extracted for the objects found via the query (or the objects provided by the getDataForObjectId() operation).

You have two different options to perform the extract, either point out a payload definition that specifies what data to be extracted, or define it in this configuration.

For the first alternative, e.g. using a payload definition, you configure that scenario like shown below:

<ExportServiceDefinition>

    <Extract payload="tvc:payload/MyPayload.xml" />

or

    <Extract payload="MyPayload.xml"/>

For the other alternative, the possible child elements are shown in the table below:

Child Element Description Attributes Required Example

<Basics>

Defines that the basic data from the business object(s) may be part of the extracted data, if the client wants it.

You may define certain basic properties to be excluded by using the <Exclude> child element.

The name attribute is default set to "basics".

The default attribute is default set to "include".

name default

No

 
<Basics name="basics" default="exclude">
    <Exclude>vault</Exclude>
    <Exclude>locker</Exclude>
</Basics>

<Attributes>

Defines that the attributes from the business object(s) may be part of the extracted data, if the client wants it.

You may define certain attributes to be excluded by using the <Exclude> child element

The name attribute is default set to "attributes".

The default attribute is default set to "include".

name

default

No

 
<Attributes name="metaData" default="include">
    <Exclude>attribute_Weight</Exclude>
</Attributes>

<Arg>

Defines custom extraction arguments. See details below.

name

default

dataType

select

No

 
<Arg name="abc" dataType="integer" default="include">
    <Select>from[Y].attribute[ABC]</Select>
</Arg>

Arg

The <Arg> element is used to specify custom extract arguments. E.g. one argument may map to one or multiple select expressions. You may also refer to a "table column definition", which defines complex data extraction rules.

The following table shows the available attributes on the <Arg> element.

Attribute Name Description Example

select

Defines a single select expression

<Arg select="attribute[ABC]"

dataType

Defines the data type of the returned data. One of:

  • string

  • datetime or timestamp

  • real, float, double or numeric

  • boolean or bool

  • integer or int

<Arg dataType="int"

multiple

A boolean indicating if the returned data contains one or multiple values.

If a select expression starts with "from[", "to[" or "relationship[", this value will by default be set to true.

<Arg multiple="true"

The possible child elements are shown in the table below:

Child Element Description Required Example

<Select>

Defines a select expression that should be used for extraction of the data

No

<Select>from[Y].attribute[ABC]</Select>

<TableColumn>

Defines a table column that is used for extraction of the data

No

<TableColumn>tvc:tablecolumn/MyColumn.xml</TableColumn>

Handler

The handler element allows pointing out a custom Java class or a custom script for validation/custom handling of the web service. The latter is a convenient way to quickly implement custom validation without having to compile any code.

To define a custom Java class, configure it like shown below:

<ExportServiceDefinition>
    <Handler>com.acme.integrations.ws.ProductDataExportHandler</Handler>

This class must either implement the interface com.technia.tif.enovia.jaxws.api.export.QueryServiceHandler or extend from the default implementation com.technia.tif.enovia.jaxws.api.export.DefaultQueryServiceHandler.

The default implementation is implemented like shown below:

import java.util.Map;
import com.technia.tif.enovia.jaxws.api.Value;
import com.technia.tif.enovia.jaxws.api.Webservice;
import com.technia.tvc.core.db.Query;

public class DefaultQueryServiceHandler implements QueryServiceHandler {

    public void validateInput(Webservice service, Object input) {
    }

    public void validateQuery(Webservice service, Query query) {
    }

    public void handleBasicsMap(Webservice service, Map<String, Value> valueMap) {
    }

    public void handleAttributesMap(Webservice service, Map<String, Value> valueMap) {
    }

    public boolean isAuthorized(Webservice service, String userId) {
        return true;
    }
}

If you want to implement the same handler in a script file, for example a Javascript file you can point out such script like shown below (different syntaxes shown).

<ExportServiceDefinition>
    <Handler>script:MyHandler.js</Handler>
    <Handler>tvc:script/MyHandler.js</Handler>
    <Handler>script:tvc:script/MyHandler.js</Handler>

    <Handler>tvc:script:acme/MyHandler.js</Handler>
</ExportServiceDefinition>

The first three variants all refers to the same script file, e.g. ${TIF_ROOT}/modules/enovia/cfg/script/MyHandler.js

The last example refers to the file: ${TIF_ROOT}/modules/enovia/cfg/acme/script/MyHandler.js

You may choose what functions to implement in your script, below is an example:

function validateInput(service, input) {
    var qp = input.getQueryParams();
    var arg1 = qp.getArg1(), arg2 = qp.getArg2();
    if (arg1 == "1" && arg2 == "1") {
        throw "Arg1 and Arg2 may not both be set to 1";
    }
}

function isAuthorized(service, uid) {
    if (uid == "creator") {
        return false;
    }
    return true;
}

Configurable Update Service

The configurable update web-service support is used to quickly set up a SOAP based web-service that can be used by a client to update business object metadata in ENOVIA/3DEXPERIENCE.

Each configuration results in one web-service to be exposed. This kind of web service will have one operation that can be invoked remotely. This method is called "update".

Below is a sample configuration illustrating some concepts.

<UpdateServiceDefinition>
    <Credentials required="true" />

    <Query>
        <Params>
            <Arg name="unitOfMeasure" required="true" type="String">
                <Where>${attribute[attribute_UnitofMeasure]} == "%s"</Where>
            </Arg>
        </Params>
        <Defaults>
            <Limit>100</Limit>
            <Type>type_Part</Type>
            <Vault>vault_eServiceProduction</Vault>
        </Defaults>
    </Query>

    <Update>
        <Field
            name="unitOfMeasure"
            type="string"
            attribute="attribute_UnitofMeasure"/>
        <Field
            name="test"
            type="string"
            required="false"
            java="com.technia.tif.enovia.jaxws.api.update.TestUpdater"/>
    </Update>

    <ReturnFormat>
        <OnSucess>
            <Status>OK:${COUNT}</Status>
        </OnSucess>
        <OnError>
            <Status>FAILED</Status>
            <Message>${ERROR}</Message>
        </OnError>
    </ReturnFormat>
 </UpdateServiceDefinition>

The root element of this file must be <UpdateServiceDefinition>.

The available child elements are listed in the table below.

Child Element Description Required

<Credentials>

Defines if the client of this web-service must provide a user name / password for an ENOVIA/3DEXPERIENCE user.

If the definition does not contain this element or has the attribute required set to false, the query and data extract will be performed with super-user privileges.

No but recommended

<Query>

Defines the query parameters, e.g. the query that returns the objects which is subject for being updated.

Yes

<Update>

Defines what to be updated, e.g. what input the client must provide and what this input maps to.

Yes

<ReturnFormat>

Defines the response/return value from the service. You may configure the success message and error message / status.

No

<Handler>

Defines a custom Java class OR a custom Script file that can be used to perform additional validations.

No

Credentials

If this element is omitted or if the attribute required is set to false then the operations or methods of this web service will be executed with admin privileges.

Example:

<UpdateServiceDefinition>
    <Credentials required="true"/>
    ...
</UpdateServiceDefinition>

If credentials is required, the user calling the web-service operation is required to enter a valid ENOVIA/3DEXPERIENCE user id / password combination.

It is also possible to use container managed authentication (basic authentication). See Container Managed Credentials for more information.

Query

The details of the <Query> element is described within the Configurable Export Service chapter.

Update

The <Update> element defines what to be updated.

The following table shows the possible child elements of this element.

Child Element Description Required Example

<Field>

Defines the "fields" that contains the update settings

At least one present

<Field name="unitOfMeasure" type="string" attribute="attribute_UnitofMeasure"/>

<Field name="description" type="string" basic="description"/>

Field

The <Field> element has a number of attributes used to control the behavior of the field. The following table shows the available attributes on the <Field> element.

Attribute Name Description Example Required

name

Defines the name of the field. Note that the name must only contain the characters a-z and or A-Z or digits.

The first character must be a letter.

<Field name="unitOfMeasure"

Yes

type

Defines the data-type for the value sent by the client. The possible values are:

  • string

  • date

  • real, float, double or numeric

  • boolean or bool

  • integer or int

<Field type="integer"

No, defaults to String

attribute

Specifies an attribute, which the field maps to.

<Field attribute="${attribute[attribute_ABC]}"

-

basic

Specifies a basic property, which the field maps to.

<Field basic="description"

-

java

Specifies a Java class, which the field maps to. See below for details

<Field java="com.acme.ws.UpdateHandler"

-

script

Specifies a Script file, which the field maps to. See below for details

<Field script="MyUpdater.js"

<Field script="tvc:script/MyUpdater.js"

<Field script="tvc:script:integration/MyUpdater.js"

-
Exactly one of the attributes "attribute", "basic", "java" and "script" must be set.

The Java attribute, if used, must contain the fully qualified classname of a class implementing the interface com.technia.tif.enovia.jaxws.api.update.Updater.

This interface is defined as below:

package com.technia.tif.enovia.jaxws.api.update;

import com.technia.tif.enovia.jaxws.api.Webservice;

/**
 * The updater interface used by the configurable update webservice.
 * @author Technia
 */
public interface Updater {
    /**
     * Performs the update of the field.
     *
     * @param service The service, which is calling this updater.
     * @param objectId The id of the object to update
     * @param field The field name to be updated
     * @param value The value sent by the client.
     * @throws Exception If unable to perform the update operation, for some reason.
     */
    void update(Webservice service, String objectId, String field, Object value) throws Exception;
}

Using the script attribute lets you define the update logic inside a script file instead. Below is an example of such:

importClass(com.technia.tvc.core.db.BusinessObjectUtils);

function update(service, objectId, field, value) {
    var type = BusinessObjectUtils.select(objectId, "type.kindof");
    if (type == "Part") {
        if (value < "1") {
            throw "Invalid value: " + value;
        }
        BusinessObjectUtils.setAttribute(objectId, "Target Cost", value);
    }
}

ReturnFormat

The <ReturnFormat> element allows defining how the response should look alike when the web-service has been invoked.

You can control the success status and the error status and message. See below for syntax:

<UpdateServiceDefinition>
    <ReturnFormat>
        <OnSucess>
            <Status>OK:${COUNT}</Status>
        </OnSucess>
        <OnError>
            <Status>FAILED</Status>
            <Message>${ERROR}</Message>
        </OnError>
    </ReturnFormat>
</UpdateServiceDefinition>

The ${COUNT} macro refers to the number of objects being updated.

The ${ERROR} macro may be used in the <OnError> section to include the error message.

Handler

The <Handler> element is described in the Configurable Export Service chapter.

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/3DEXPERIENCE 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.

handler

The fqn name of a class that implements the interface com.technia.tif.enovia.security.ContextProviderHandler. See further down in this document for more details.

Valid child elements are defined in the table below

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

Custom Context Provider Handler

In some cases you may need some more fine-tuned control over what ENOVIA/3DEXPERIENCE Context to be used.

The handler attribute is used to point out the class implementing the interface com.technia.tif.enovia.security.ContextProviderHandler.

If you have enabled container managed authentication, the servlet container (the Jetty engine) have already done some authentication. In case you are using "enovia" as the login-service you will in that case has a "Context" set already. This Context Provider Handler cannot override/by-pass the container managed logic - if this is needed then you should disable the container managed security and take care about this in your custom ContextProviderHandler. 
public class MyContextProviderHandler implements ContextProviderHandler {

    @Override
    public ContextProvider apply(AuthorizationContext ctx, CredentialsConfig config) {
        // Principal available in case container-managed-security is enabled. Otherwise, null.
        Principal p = ctx.getPrincipal();

        // EXAMPLE: Use the ENOVIA user credentials directly.
        if (principal instanceof EnoviaUserPrincipal) {
            EnoviaUserPrincipal eup = (EnoviaUserPrincipal) principal;
            if (eup.isValid()) {
                return eup;
            }
        }

        // EXAMPLE: Get headers
        List<String> headerNames = ctx.getHeaderNames();
        for (String header : headerNames) {
            System.out.printf("Header>>> %30s : %s%n", header, ctx.getHeaderValues(header));
        }

        // EXAMPLE: Get parameters
        List<String> paramNames = ctx.getParameterNames();
        for (String param : paramNames) {
            System.out.printf("Parameter>>> %30s : %s%n", param,
                    StringUtils.concat(ctx.getParameterValues(param), "|"));
        }

        // EXAMPLE: Get other request based properties
        if (ctx instanceof RequestBasedAuthorizationContext) {
            RequestBasedAuthorizationContext rctx = (RequestBasedAuthorizationContext) ctx;
            System.out.printf("Request URI>> %s%n", rctx.getHttpServletRequest().getRequestURI());
        }

        // EXAMPLE: Run as specific user
        String runAs = ctx.getHeaderValue("x-run-as");
        return ContextProviders.getRunAs(runAs);
    }
}
In the above example we are not considering if the Credentials have been configured with Security Context nor Authorization rules. If you want to do this you can see below how to do so. 
import com.technia.tif.enovia.security.DefaultContextProviderHandler;

...
ContextProvider contextProvider = ...;
return DfaultContextProviderHandler.getInstance().apply(ctx, credentials, contextProvider);

Security Context

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

  1. Point out a mapping file

    1. Or use a default mapping file

  2. Specify a named security context

  3. Or use the "default" security context as configured for the ENOVIA/3DEXPERIENCE 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:

  1. User list is EMPTY or user is in list

  2. Role list is EMPTY or user have one of the roles in the list

  3. 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" />

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/3DEXPERIENCE database.

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

app-token

A login service that will authenticate the remote user against the Tokens declared from the administration UI.

enovia

A login service that will authenticate the remote user against the ENOVIA/3DEXPERIENCE 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 set up the core parts of Spnego/Kerberos.

LDAP Authentication

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

http.webapp.jaxws.loginService=ldap
http.webapp.jaxws.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

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 username 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 undefined 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.authenticationStrategy

Defines authentication strategy. Possible values are

  • simple

  • external-tls

  • tls

  • digest-md5

Default is simple

No

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:.

If you ran the mql encrypt command in a release between 19x-HF2 and 20x then you must use the prefix enovia-19x. If you ran it in 21x or later, then use enovia-21x as prefix.

Eg.

ldap.managerSecret=enovia:=vc4QGO6tVoYi

Also note that in case LDAPS is being used, you may need to add some additional JVM parameters specifying a keystore containing a certificate used for the LDAP authentication. As this is handled by a lower level in the JVM, these have to be passed as system parameters (-D) to the JVM running TIF.

Example:

-Djavax.net.ssl.trustStore=/home/test/ldap.pkcs12
-Djavax.net.ssl.trustStorePassword=123456

ENOVIA/3DEXPERIENCE Authentication

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

http.webapp.jaxws.loginService=enovia
http.webapp.jaxws.realm=Webservices

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

Spnego Authentication

Secondly, an example for spnego:

http.webapp.jaxws.loginService=spnego
http.webapp.jaxws.spnego.targetName=HTTP/tifserver.exampledomain.com
http.webapp.jaxws.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.jaxws.loginService=spnego
http.webapp.jaxws.spnego.config=${tif.home}/etc/kerberos/spnego.properties
http.webapp.jaxws.realm=Webservices

The spnego.properties defines the targetName like this:

$\{tif.home}/etc/kerberos/spnego.properties
targetName = HTTP/tifserver.exampledomain.com

Application Token Authentication

Application tokens are managed inside TIF and can be used to grant access for remote systems to use webservices hosted in TIF.

The tokens should be sent as Basic authorization header in the request. The actual token value is only revealed once after the Application Token is created, so you need to store that in a secret place.

You need to configure the web-app to use the login service "app-token".

http.webapp.jaxws.loginService=app-token
http.webapp.jaxws.realm=Webservices

The created application token declares what ENOVIA/3DEXPERIENCE user to run the action as, and also what roles to assign the security principal with.

If you leave those properties undeclared on the application token, then TIF will fall back to some default values as declared within the module.properties file.

apptoken.default.roles = Employee,Another Role,Third Role
apptoken.default.user = creator

Configure Security Constraints in WEB.XML

Within the "web.xml" file (webapps/jaxws/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/jaxws/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 an ENOVIA/3DEXPERIENCE 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>