Endpoint

Endpoint URL

An endpoint is uniquely identified by an endpoint URL:

Request Type	Endpoint URL
SOAP	http://<host>:<port>/<context_root>/soap/<Workflow_ID>
XML	http://<host>:<port>/<context_root>/xml/<Workflow_ID>
HTML	http://<host>:<port>/<context_root>/html/<Workflow_ID>
GENERIC	http://<host>:<port>/<context_root>/generic/<Workflow_ID>
OCSP	http://<host>:<port>/<context_root>/ocsp/<Workflow_ID>

The parallel requests are limited to 100 requests. All requests above this limit will drop and a 503 Server busy will be returned.

Endpoint Configuration

Normally the defaults are fine and you don’t need this file, except if you want to tune a specific endpoint eg. ocsp or allow big attachments.

Variable	Description
maxRequestSize	Size in MB of request allowed to be sent through the servlet 0 for no restriction.
requestTypeParameterName / requestTypeDefault	parameter acting as the requestType, and default that should be taken if it wasn’t found.
parseHeaders	true or false Do we want to parse the http headers sent to the TrustBuilder servlet. if set to true these headers will we placed into the RequestHeaders of the incomming resquest.
ocspResponderKeystoreType	Specific ocsp endpoint setting. PKCS12 or JKS Defines the type of keystore used.
ocspResponderKeystoreFile	Specific OCSP endpoint setting. Absolute path to the store
ocspResponderKeystorePassword	Specific OCSP endpoint setting. Password of the store [Base64].
ocspResponderKeystoreAlias	Specific OCSP endpoint setting. Alias of the private key in the keystore used to sign the response. Only used when type is set to ‘JKS’
ocspResponderKeystoreAliasPassword	Specific OCSP endpoint setting. Password of the private key in the keystore.

Request-api

Whenever a request comes into the workflow as an entry in your workItem it request will have a couple of attributes. These attributes are depending on the endpoint on which the request comes in. Note, the attributes are always there, but not necessarily filled in. The request object available as a real javascript object contains the following properties/function.

• headers: containing all headers
• cookies: containing all cookies
• parameters: containing all passed parameters (empty for every endpoint except html-endpoint), value is an array !!
• parameter(‘myparam’): function!! returning the value if there is only one value for a certain parameter, array in every other case
• body: string containing the body
• bodyAsXml(): function returning the body as an xml object (if it actually is one)

Response-Api

When sending something out via the FinalState property the engine requires a response the endpoint can understand.

This is where the tb.generateResponse comes in. This is a helper function requires the following parameters:

• body: whatever you want to have in the body of your endpoint, html/xml/soap
• headers: object key/value pairs rendered as headers in the endpoint
• cookies: object key/value pairs rendered as cookies in the endpoint (only applies to http protocol, not to cdas)
• status: number to be used as http statuscode

eg:

var cookies = {
    "TbSession": {
        value: 'someIdentifier',
        maxage: '300',
        path: "/"
    },
    "RememberMe": {
        value: '1',
        maxage: '300',
        path: "/"
    },
};
var header = { "Content-type": "text/html", 'X-Application': 'Trustbuilder' };
tb.generateResponse('\<html\>my doc\</html\>', headers, cookies, 200);

Endpoint Authorisation

These pages describe the authorisation mechanism applied to the TrustBuilder Endpoints. There are currently five HTTP endpoints within TrustBuilder (TB) being XML, SOAP, HTML, GENERIC and OCSP.Each endpoint consumes a different kind of request with its own authorisation structure.

The mechanism for authentication and authorization is the standard J2EE implementation where roles are defined in the deployment descriptor of the application and then mapped on the application server.

Not only can the endpoints be secured, but are some of the parameters of the request taken into account in the decision: config, workflow and RequestType. If none of these parameters are present (via HTTP headers, URL or Form values) the authorisation is applied on the default requestType on the condition that this is configured naturally.

Through services in the configuration of TrustBuilder it is possible to add an Radius and LDAP endpoint.

Many applications and network access management solutions use these interfaces for such requests. Now they can take advantage of the power of TrustBuilder’s Policy and Workflow Engine to handle the requests independently from the actual repository containing the user and validation data.

The deployment descriptor (DD) is where the roles are defined. These roles are read by the application server upon installation of the application and can then be mapped to users and groups. These can be from ITIM or LDAP or any other mechanism that your application server provides. The destinations for authorisation and the authentication method are also defined in the deployment descriptor.

Security Roles

Roles are defined in the DD that are used by the following definitions to map the application to the container: WebSphere. Ultimately the security; users, credentials, groups, roles, are defined by the container these roles provide hooks to the container and need to be mapped on installation of TB.

<security-role>

    <role-name>TrustBuilderRole\</role-name>

</security-role>

<security-role>

    <role-name>TrustBuilderAdmin\</role-name>

</security-rol\>

<security-role>

    <role-name>TrustBuilderAuditor\</role-name>

</security-role>

Security Constraints

The constraints map the endpoint servlets to roles and transport restrictions securing SOAP, XML, HTML or Genric types of requests. The constraints are mapped to URLs so one constraint can be set for each request type or the trustbuilder/* root could be constrained covering all the instances. The role-name elements map to security-role elements.

<security-constraint>
   <web-resource-collection>
      <web-resource-name>XMLRequest</web-resource-name>
      <url-pattern>/xmlTrustBuilderRequest</url-pattern>
      <http-method>DELETE</http-method>
      <http-method>GET</http-method>
      <http-method>POST</http-method>
      <http-method>PUT</http-method>
      <http-method>HEAD</http-method>
      <http-method>TRACE</http-method>
      <http-method>OPTIONS</http-method>
   </web-resource-collection>
   <auth-constraint>
      <role-name>TrustBuilderRequestXML</role-name>
      <role-name>TrustBuilderRequestALL</role-name>
   </auth-constraint>
   <user-data-constraint>
      <description>SSL or MSSL not required</description>
      <transport-guarantee>NONE</transport-guarantee>
   </user-data-constraint>
</security-constraint>

Authentication Configuration

For authorisation to function authentication needs to be performed. This is also specified in the web.xml file. Initially this is set to BASIC authentication but can be set to DIGEST or FORM.

<login-config>
   <auth-method>BASIC</auth-method>
   <realm-name>TrustBuilder</realm-name>
</login-config>

Websphere

The roles defined in the deployment descriptor of TrustBuilder (TB) must be mapped to users that are defined within WebSphere (WAS). This is performed at the application level within WAS and for it all to function application security needs to be enabled.

Application Security Settings

For the authentication that is setup within the web.xml file to function application authentication must be enabled in WebSphere.

For WAS 7 and WAS 8 this is set here:

> Security > Global Security > Application Security > Enable application security 

Creating Internal Users

NB. This is only one way to create users in WAS for more information view WAS documentation.

Once TrustBuilder has been installed within WAS then the roles defined in the deployment descriptor(web.xml) need to be assigned to users within the organisation, however they are managed. WebSphere can use a number of resources for users and groups.

If using the internal federated repository then users can be seen here (in WAS 7 or 8):

> Users and Groups > Manage Users 

Mapping Application Roles

To map the TrustBuilder roles created in the deployment descriptor (web.xml) enter the WAS administrative console and go here for WAS 7 and WAS 8:

> Applications > Application Types > Websphere enterprise applications > trustbuilder > Security role to user/group mapping 

Within this page all the roles defined in the deployment descriptor with be visible. To map a role to users within WAS select the roles you wish to work with then click the Map Users or Map Groups buttons. On the following page search for the users or groups that are to be assigned to the selected roles. These users or groups define the credentials that are used when authenticating to the TrustBuilder endpoints and authorising to specific resources.

XSD Validation

This section describes how to configure XSD validation of requests for TrustBuilder. This can be used to validate transactions or portions of a request to TrustBuilder against a pre-written XSD file.

Configuration

In order to use the xsd validation the config file should contain the ‘ValidationResource’ element referencing an absolute path to a validation properties file.

This properties file contains the element to be validated against which XSD. For each type of request that must be validated the request type name and the name and location of the XSD file to perform the validation must be specified within the property file (requestValidation.properties).

An example property set for one element that is to be validated

# requestValidation.properties

TRAN1=/opt/securit/XSD/tran1.xsd

TRAN1.element=TranData

TRAN1.element.namespace=http://securit.be/stb 

Name	Example	Description
validation.element	transactionType	Defines which element in the payload defines against which xsd this payload should be validated
validation.namespace	http://securit.biz/stb	Optional namespace of the element
xsd.home		Optional absolute path containing xsd’s defined for every type
transactionType	transactionType.xsd	The relative path from xsd.home to validate against
transactionType.element	Data (TransactionDataSet)	The name of the element that contatins the data that is to be validated
transactionType.element.namespace	URI	The optional namespace of the Data if needed

Requests

Within each request that is sent to TrustBuilder the body will be searched for the validation.element, for instance a transactionType. The value of this element will be looked up with a relevant namespace if appropriate. Which will determine:

• If this type of request should be validated (ie. is there a key found in the properties file)
• The location of the XSD file to validate this request (dependent upon 1)
• The part of the request that should be validated (dependent upon 1)

Kerberos authentication

In order to enable kerberos authentication on an http endpoint the following steps is required. In TBHOME a trustbuilder.properties should be created with the following parameters: (note: all paths are relative from TBHOME) After modifying this file, a restart of trustbuilder is required.

// krb5 config, eg. /etc/krb5.conf

krb5Conf= 

// login config, jaas configuration file containing the configuration for the kerberos modules

krb5LoginConf=

// module to use in the jaas configuration file (referrably using keytab)

krb5Module=

// if basic auth is permitted, not recommended

krb5AllowBasic= 

Now trustbuilder will ‘negotiate’ with clients asking for a kerberos ticket.

An example krb5.conf could look like:

[libdefaults]

        default_realm = TRUSTBUILDER


[realms]

        TRUSTBUILDER = {

                kdc = kdc01.trustbuilder

                admin_server = kdc01.trustbuilder

        } 

Example jaas.config

SignedOnUserLoginContext
{
    com.sun.security.auth.module.Krb5LoginModule required debug = true
            tryFirstPass = true doNotPrompt = true
            principal = "HTTP/trustbuilder"
            storeKey = true useKeyTab = true keyTab = "/Users/koen/tb.keytab"
            debug = true;
};