Copyright © Cloud Software Group, Inc. All Rights Reserved

WS Security Services Authentication

TIBCO API Exchange Gateway supports the WebServices Security (WSS) authentication services for the northbound messages.

• The configuration mechanism for WS security policies on Facade Operations tab in TIBCO API Exchange Gateway 2.x is provided for the backward compatibility to use with TIBCO ActiveMatrix Service Gateway 1.2.0 product release. This configuration mechanism is deprecated in 2.x release of the software. • WS Security is supported using the security policies in the TIBCO API Exchange Gateway 2.x release. Refer to Security Policies chapter for details on how to use security policies.

TIBCO API Exchange Gateway supports the following security token profiles:

−

User name

TIBCO API Exchange Gateway provides the user authentication for the northbound requests with the LDAP system.

−	SAML 1.1 and SAML 2.0

TIBCO API Exchange Gateway provides SAML based sign-in authentication of the northbound requests.

−

X.509

TIBCO API Exchange Gateway uses X.509 protocol to process the requests and confirm that integrity and confidentiality is maintained.

TIBCO API Exchange Gateway provides the processing of northbound messages as follows:

•	Northbound Request Messages

The Core Engine can verify the signature of the sender of the request using the trust store as well as can decrypt it.

•	Northbound Response Messages

The Core Engine can sign the response message using private key to maintain integrity, as well as can encrypt it using the trust store and public certificate of the receiver of the response.

TIBCO API Exchange Gateway ensures availability, integrity and confidentiality by implementing the following protocols:

•	SAML 1.1 and SAML 2.0 authentication.

•	X.509 based signature verification and public key infrastructure for non-repudiation.

•	Signs the response using private keys issued by CA.

•	Decrypts the request with private keys issued by CA. TIBCO API Exchange Gateway supports variety of encryption algorithms and modes.

•	TIBCO API Exchange Gateway can encrypt the response document with the consumer's public certificates.

Security Service Providers

This section describes the following types of security service providers:

•	Authentication Service Provider

Authenticated Service provider ensures that access is restricted to authenticated user. To access the web services managed by the API Exchange Gateway, the user must include an appropriate token in the SOAP header to authenticate.

The supported authentication tokens are:

−	Web Services Security usernameToken

−	Web Services Security X.509 Certificate

−	Web Services Security SAML token profile

•	Identity Service Providers

Identity service providers makes use of public and private credentials for common trust and identity operations such as token signing, data encryption and creation of SSL connections. The main types of identity service providers are Trust Identity Provider and Subject Identity Provider.

Web Services Security (WSS) Properties

This section explains the Web Services Security (WSS) properties for TIBCO API Exchange Gateway .

Types of Security Service Providers

Table Types of Service Providers lists the types of service providers used by WSS configuration.

Table 93 Types of Service Providers

Type	Description
LDAP	LDAP authentication service provider (LDAP ASP) provides the ability to authenticate a username and password against an LDAP server.
Trust Identity	The Trust Identity Provider is used for retrieving certificates required for performing trust operations from a credential store. For example, use Trust Identity Provider (TIP) for verifying a signature or encryption and SSL client authentication.
Subject Identity	The Subject Identity Provider is used for retrieving and using private credentials obtained from a credential store. For example, use Subject Identity Provider (SIP) for signing or decryption.
WSS	WSS security authentication provider is used as a combination of LDAP, Trust Identity Provider(TIP), and Subject Identity Provider(SIP).

• WSS service provider is a combination of LDAP authentication, Trust Identity and Subject Identity Providers. Depending on the usage of service provider, WSS can be configured to include one or more types of service providers that it is used for. • Trust Identity Provider (TIP) and Subject Identity Provider (SIP) depends on Keystore Credential Provider (KCP), so TIP and SIP always include an associated KCP.

Configuring LDAP Authentication Service Provider (LDAP ASP)

Description

The LDAP authentication service provider is used to authenticate the user name and password against the LDAP server. The user name is specified as the usernameToken in the incoming request from the client.

Use Case

Verifying usernameToken in the incoming request.

Example Properties

See the following properties:

Properties

Table Properties for LDAP Authentication Service Provider describes the properties for LDAP Authentication Service Provider.

Table 94 Properties for LDAP Authentication Service Provider

Property	Description
com.tibco.asg.intent.usernameToken
	Boolean intent property indicates if the LDAP authentication method can be enforced on the request message or not. Possible values are true or false. If the value of this property set to true, the request message must contain a valid username token.
com.tibco.trinity.runtime.core.provider.authn.ldap.initialCtxFactory
	Specifies the name of the JNDI Factory to use. The default value is com.sun.jndi.ldap.LdapCtxFactory (Sun's LdapCtxFactory). Optional.
com.tibco.trinity.runtime.core.provider.authn.ldap.serverURL
	Specifies the URL to connect to the LDAP directory server. The LDAP URL is defined as: ldap://hostname:port. The LDAP SSL URL is defined as: ldaps://hostname:port Required.
com.tibco.trinity.runtime.core.provider.authn.ldap.searchTimeOut
	The time (in milliseconds) to wait for a response from the LDAP directory server. A value of 0 causes it to wait indefinitely. If a negative number is specified, it uses the provider's default setting. Optional.
com.tibco.trinity.runtime.core.provider.authn.ldap.userAttributeUsersName
	The name of the attribute in the user object that represents the user's name. The value depends on which LDAP server is used. If you are using ActiveDirectory LDAP Server, set this value as CN. If SunOne or OpenLDAP LDAP Server is used, set this value as uid. Optional.
com.tibco.trinity.runtime.core.provider.authn.ldap.userAttributesExtra
	Specifies the optional list of user attributes to retrieve from the LDAP directory during authentication. Separation characters for the list of user attributes are comma, any ASCII whitespace or semicolon. For example, mail givenname Optional.
com.tibco.trinity.runtime.core.provider.authn.ldap.userSearchBaseDN
	Specifies the base distinguished name (DN) where the searches for the users begin. You must supply the base DN that narrows the search to the smallest set of objects that includes all valid users. This is relevant only when used with the administrator's credentials in search mode. For example, ou=people,ou=na,dc=example,dc=org Required in admin (search) mode.
com.tibco.trinity.runtime.core.provider.authn.ldap.userSearchExpression
	Specifies the expression to be used for searching in admin mode against potential user objects. For example, the search expression is specified as: (&(uid={0})(objectClass=person)). In this string, the variable {0} represents the name of the user. The code substitutes the user name for this variable, and passes the resulting boolean expression to the LDAP server. The LDAP server matches that search expression against user objects to find a match. The search result must contain exactly one match. This property is relevant only when credentialProvider property is set and the binding is done as an administrator; otherwise userDNTemplate is used. Required in admin (search) mode.
com.tibco.trinity.runtime.core.provider.authn.ldap.userDNTemplate
	Specifies a template to be used when formatting user's DN before binding. It is used as an alternative to admin (search) mode. For example, uid={0},ou=employee,ou=tsi,o=tibco Required for bind mode (not in admin (search) mode).
com.tibco.trinity.runtime.core.provider.authn.ldap.userAttributeGroupsName
	If you specified "LDAP user indicates groups" (as either userHasGroups or userDNHasGroups) then you must supply the name of the attribute in each user object that lists the groups to which the user belongs. Otherwise, this parameter is not relevant. Mandatory when relevant.
com.tibco.trinity.runtime.core.provider.authn.ldap.userAttributesExtraList
	Same as userAttributesExtra property but this is specified in list form. Optional.
com.tibco.trinity.runtime.core.provider.authn.ldap.userSearchScopeSubtree
	A boolean property which determines if the entire sub-tree is searched or not. If a true value is specified, the entire sub-tree starting at the base DN is searched. Otherwise, the nodes one level below the base DN are searched. Optional.
com.tibco.trinity.runtime.core.provider.authn.ldap.groupSearchBaseDN
	Specifies the base distinguished name (DN) where the searches for the groups begin. Supply the base DN that narrows the search to the smallest set of objects that includes all valid groups. For example, ou=groups,ou=na,dc=example,dc=org The default value is empty. Optional.
com.tibco.trinity.runtime.core.provider.authn.ldap.enableNestedGroupSearch
	Indicates the flag to determine if nested groups should be searched for. If the value is not set to true, the groups are only returned in which the user is the direct member. The default value is false. Optional.
com.tibco.trinity.runtime.core.provider.authn.ldap.groupSearchExpression
	Specifies the expression to be used for searching against potential groups. For example, search expression is specified as: (&(uid={0})(objectClass=person)). In this string, the variable {0} represents the name of the user. The code substitutes the user name for this variable, and passes the resulting boolean expression to the LDAP server. The LDAP server matches that search expression against groups to find all groups containing the username. The values might be different for different LDAP server. For example, its defined as uniquemember={0} for SunOne, cn={0} for OpenLDAP, member={0} for Active Directory. Required.
com.tibco.trinity.runtime.core.provider.authn.ldap.groupSearchScopeSubtree
	A boolean property which determines if the entire sub-tree is searched or not. If a true value is specified, the entire sub-tree starting at the base DN for groups is searched. Otherwise, the nodes one level below the base DN are searched. Optional.
com.tibco.trinity.runtime.core.provider.authn.ldap.groupIndication
	Specifies how the group memberships for users are found. The default value is noGroupInfo. Optional. The possible values are as follows: − userHasGroups − userDNHasGroups − groupHasUsers − noGroupInfo • If the value has userHasGroups,you must specify the attribute name which points the groups the user belongs to in the userAttributeGroupsName property. • If the value has userDNHasGroups,the userAttributeGroupsName property has the attribute name which hold the DNs of groups to which the user belongs. You must specify groupAttributeGroupsName property to get a specific part of the DN name. • If the value has groupHasUsers,each group object includes a list of users that belong to the group. • If the value has noGroupInfo, group memberships are not handled.
com.tibco.trinity.runtime.core.provider.authn.ldap.groupAttributeGroupsName
	Depends on value of groupIndication. Required if the groupIndication property has groupHasUsers value. • groupHasUsers: Specifies the group attribute holding the name of group. For example, the value is defined as cn for OpenLDAP server, sAMAccountName for ActiveDirectory LDAP server. • userHasGroups:Specifies the name of the group. If this is not specified, the whole DN of the group is used. For example, the value is defined as cn for OpenLDAP server.
com.tibco.trinity.runtime.core.provider.authn.ldap.groupAttributeSubgroupsName
	Specifies the name of the attribute in each group object denoting subgroups. For example, the value is defined as uniqueMember for OpenLDAP server, member for ActiveDirectory LDAP server. Optional
com.tibco.trinity.runtime.core.provider.authn.ldap.groupAttributeUsersName
	Specifies the attribute name if the groupIndication property has groupHasUsers value. It specifies the name of the attribute in each group object denoting its users. For example, the value is uniqueMember for OpenLDAP, member for ActiveDirectory Server. Required if the groupIndication property has groupHasUsers value.
followReferrals
	Determines if the client follow referrals are returned by the LDAP server. The default value is false Optional.
LDAP SSL
com.tibco.trinity.runtime.core.provider.identity.trust.trustStoreServiceProvider
	Specifies the Identity Trust Provider configuration to provide SSL support for LDAP
com.tibco.trinity.runtime.core.provider.credential.keystore.truststore.keyStoreLocation
	Specifies the location of the keystore for the credentials.
com.tibco.trinity.runtime.core.provider.credential.keystore.truststore.keyStorePassword
	Specifies the location of the keystore for the credentials.
com.tibco.trinity.runtime.core.provider.credential.keystore.truststore.keyStoreRefreshInterval
	Specifies the refresh interval (milliseconds).
com.tibco.trinity.runtime.core.provider.credential.keystore.truststore.keyStoreType
	Specifies the keystore type. Supported formats are JKS,PKCS12.

Sample File

The properties and example configuration for LDAP authentication service providers are found in the following sample files:

•	ASG_CONFIG_HOME/default/wss/req_usernametoken_ldapbind.properties

This file lists the properties with the example configuration for the LDAP server in bind mode.

•	ASG_CONFIG_HOME/default/wss/req_usernametoken_ldapsearch.properties

This file lists the properties with the example configuration for the LDAP server in search mode.

•	ASG_CONFIG_HOME/default/wss/req_usernametoken_ldapbindssl.properties

This file lists the properties with the example configuration for the LDAP server in SSL mode.

Configuring Trust Identity Provider

Description

The Trust Identity Provider is used to retrieve public certificates from a credential store required to perform trust operations. You must store the public certificate and provide its location. The certificates are used by the Core Engine to verify the signatures when the payload in the incoming request is signed. The Core Engine uses the public certificate to encrypt the response payload before it sends the response back to the client.

Use Case

•	Verify signatures for the signed request payload.

•	Encrypt the response payload.

Example Properties

See the following properties:

Properties

Table Properties for Trust Identify Provider (TIP) describes the properties for Trust Identify Provider.

Table 95 Properties for Trust Identify Provider (TIP)

Property	Description
com.tibco.asg.intent.signature
	Boolean intent property which indicates if the incoming request message is signed or not. If signed, then the signatures are verified using the trust identity provider properties (public credentials). Possible values are true or false. If the value of this property set to true, the request message must have valid signatures.
com.tibco.trinity.runtime.core.provider.identity.trust.trustStoreServiceProvider
	Specifies the name of the credential service provider containing the credentials for establishing trust.
com.tibco.trinity.runtime.core.provider.credential.keystore.truststore.keyStoreType
	Specifies the keystore type. Supported formats are JKS,PKCS12.
com.tibco.trinity.runtime.core.provider.credential.keystore.truststore.keyStoreLocation
	Specifies the location(s) of the keystore.
com.tibco.trinity.runtime.core.provider.credential.keystore.truststore.keyStorePassword
	Specifies the password to unlock the keystore.
com.tibco.trinity.runtime.core.provider.credential.keystore.truststore.keyStoreRefreshInterval
	Specifies the refresh interval (milliseconds).

Sample File

•	See ASG_CONFIG_HOME/default/wss/req_verifysig.properties file for the properties and example configuration for verifying the signature in the request message.

•	See ASG_CONFIG_HOME/default/wss/resp_encrypt.properties file for the properties and example configuration for encrypting the response message.

Configuring Subject Identity Provider

Description

The Subject Identity Provider is used to retrieve private keys (credentials) from a credential store. You must store the private keys and provide its location. The private keys are used by the Core Engine to decrypt the message when the payload in the incoming request is encrypted. The Core Engine uses the private keys to sign the response message before sending it back to the client.

Use Case

•	Decrypt the request payload.

•	Sign the response payload.

Example Properties

See the following properties:

Properties

Table Properties for Subject Identify Provider (SIP) describes the properties for Subject Identify Provider.

Table 96 Properties for Subject Identify Provider (SIP)

Property	Description
com.tibco.asg.intent.decrypt
	Boolean intent property indicates if the incoming request message is encrypted or not. If encrypted, then the request message payload is decrypted using the subject identity provider properties (private credentials). Possible values are true or false. If the value of this property set to true, the request message must be encrypted.
com.tibco.trinity.runtime.core.provider.identity.subject.identityStoreServiceProvider
	Specifies the name of the credential service provider containing the private credentials for establishing the subject's identity.
com.tibco.trinity.runtime.core.provider.identity.subject.keyAlias
	Specifies an alias name for the key corresponding to the private credentials in the credential store for establishing the subject's identity.
com.tibco.trinity.runtime.core.provider.identity.subject.keyPassword
	Specifies the protection parameter of the private credentials in the credential store for establishing the subject's identity.
com.tibco.trinity.runtime.core.provider.credential.keystore.keyStoreType
	Specifies the keystore type of the private credentials.
com.tibco.trinity.runtime.core.provider.credential.keystore.keyStoreLocation
	Specifies the location(s) of the keystore of the private credentials.
com.tibco.trinity.runtime.core.provider.credential.keystore.keyStorePassword
	Specifies the password to unlock the keystore.
com.tibco.trinity.runtime.core.provider.credential.keystore.keyStoreRefreshInterval
	Specifies the refresh interval in milliseconds.

Sample File

•	See ASG_CONFIG_HOME/default/wss/req_decrypt.properties file for the properties and example configuration for decrypting a request message.

•	See ASG_CONFIG_HOME/default/wss/resp_sign.properties.properties file for the properties and example configuration for encrypting a request message.

Configuring WSS Service Provider

Description

You can combine the properties of LDAP, Subject Identity Provider (SIP) and Trust Identity Provider(TIP) to obtain more than one functionality. For example, you can verify the signatures in an incoming payload, when signed, and also decrypt the request payload, when encrypted.

Use Case

•	Verify signatures in the request payload and decrypt the request payload.

•	Sign and Encrypt the response payload.

Example Properties

See the following properties:

Properties

The properties for WSS Service Provider are defined as a combination of LDAP authentication, Subject Identity and Trust Identity provider.

See the following properties to define the WSS Service Provider properties:

•	Configuring LDAP Authentication Service Provider (LDAP ASP)

•	Configuring Trust Identity Provider

•	Configuring Subject Identity Provider

Sample File

•	See ASG_CONFIG_HOME/default/wss/req_decrypt_verifysig.properties file for the properties and example configuration for decrypting and verifying signatures for the request message.

•	See ASG_CONFIG_HOME/default/wss/resp_sign_and_encrypt.properties file for the properties and example configuration for signing and encrypting the response message.

Limitations

•	WSS authentication does not check if the request contains SAML 1.1 or SAML 2.0 version.

•	WSS authentication validates the request only if the SAML assertion is valid but does not enforce a specific SAML version or issuer on the request.

Configuring Web Services Security Authentication

This section explains the procedure to configure the web services security for the Core Engine.

Define the WSS Configuration Properties file

This section explains how to define the properties files required for the WSS shared resources configuration.

Sample Files

TIBCO API Exchange Gateway provides the sample configuration file for the shared resources for each of the security type profile. It is recommended to use the sample files as templates and edit the properties as per your requirement. The sample files are located in the ASG_CONFIG_HOME/asg/default/wss directory.

The property files are defined depending on the type of WSS configuration selected. The following section explains the WSS type and a sample property file which can be used for that type:

•	User name token

TIBCO API Exchange Gateway authenticates the user with the LDAP system and requires to create the configuration file for LDAP configuration as follows:

LDAP configuration for bind mode

This configuration type provides the authentication based on the user name token with a LDAP system for bind mode.

The sample file req_usernametoken_ldapbind.properties for LDAP shared resource configuration is located in the following directory: ASG_CONFIG_HOME/asg/default/wss

You can use this file as a template and edit the LDAP server properties as per your environment.

LDAP configuration in bind mode with SSL Enabled

This configuration type provides the authentication based on the user name token with a LDAP system with SSL enabled in bind mode.

The sample file req_usernametoken_ldapbindssl.properties for LDAP shared resource configuration is located in the following directory: ASG_CONFIG_HOME/asg/default/wss

You can use this file as a template and edit the LDAP server with SSL properties as per your environment.

LDAP configuration for search mode

This configuration type provides the authentication based on the user name token with an LDAP system for search mode.

The sample file req_usernametoken_ldapsearch.properties for LDAP shared resource configuration is located in the following directory: ASG_CONFIG_HOME/asg/default/wss

You can use this file as a template and edit the LDAP server properties for search mode as per your environment.

•	Subject Identity

The configured keystore along with a valid key from keystore can be used to provide an identity of the interested subject. The Identity provider takes as an input the password of the Key alias, and it is used to access the private key of that particular alias. This is used for signing.

TIBCO API Exchange Gateway requires certain properties to be defined for this type. These properties are defined in a file, which can be imported in the configuration GUI. See Define the WSS Configuration Properties file

This configuration type provides the properties for the keystore configuration (private key) to sign the message or decrypt the message.

The sample file resp_sign.properties describes the keystore properties required to sign the message. This file is located in the following directory: ASG_CONFIG_HOME/asg/default/wss

You can use this file as a template and edit the keystore configuration as per your environment.

•	Trust Identity

The trust store consumes a keystore provider and it is used for accessing public keys of the keys for signature verification or for encryption.

TIBCO API Exchange Gateway requires certain properties to be defined for this type. These properties are defined in a file, which can be imported in the configuration GUI. See Define the WSS Configuration Properties file

This configuration type provides the properties for the keystore configuration to verify the signatures or encrypt the message.

The sample file resp_encrypt.properties describes the certificate keystore properties required to encrypt the message. This file is located in the following directory: ASG_CONFIG_HOME/asg/default/wss

You can use this file as a template and edit the keystore configuration as per your environment.

Register WSS resources with TIBCO API Exchange Gateway

The WSS tab on the configuration allows you to register the WSS resources with TIBCO API Exchange Gateway.

To setup the WSS configuration, follow these steps:

1.	Start the GUI, if not already started.

2.	Click WSS tab.

3.	Enter the details for WSS defined as follows:

Table 97 WSS Configuration

Parameter	Description
WSS Name	Unique name which identifies a WSS configuration.
Type	Type of the WSS configuration. Select the type from the drop-down list. Possible values are: • WSS • Subject Identity • Trust Identity
New Property File	A new property file which defines the WSS resources configuration. See Define the WSS Configuration Properties file.
Existing Property Files	Select a configuration file of WSS resources configuration.

Define the WSS security operations

This section explains the steps to define a WSS enabled security operation. An operation is WSS enabled using the Operations tab of the GUI.

To setup the WSS configuration, follow these steps:

1.	On the configuration GUI, click ROUTING tab.

2.	Click the Facade Operations tab.

3.	Add a new operation. Enter the details of the Operation. See Facade Operations

4.	Check the Enable WSS check box.

5.	Enter the details for WSS enabled operation defined as follows:

Table 98 WSS Enabled Operation Configuration

Parameter	Description
WSS Request	This is the name of the WSS configuration from WSS tab. The property file from this configuration is used for northbound request processing.
WSS Response	This is the name of the WSS configuration from WSS tab. The property file from this configuration is used for northbound response processing.
Encrypt Response	This check box flag indicates whether to encrypt the response message.
Sign Response	This check box flag indicates whether to sign the response message.
Encryption Algorithm	Using this list box, select the algorithm to use for data encryption. Supported values are: TRIPLE_DES, AES_128, AES_256, AES_192
Key Algorithm	Using this list box, select the algorithm to use for key encryption. Supported values are: RSA15, RSAOEP, AES128, AES192, AES256, TRIPLEDES
Signing Algorithm	Using this list box, select the algorithm to use for signing. Supported values are: HMAC_MD5, DSA_SHA1, HMAC_SHA1, RSA_SHA1, RSA_MD5, RSA_RIPEMD160, RSA_SHA256, RSA_SHA384, RSA_SHA512, HMAC_RIPEMD160, HMAC_SHA256, HMAC_SHA384, HMAC_SHA512
Key Type	Using this list box, choose a key reference method. Supported values are: BST_DIRECT_REFERENCE, ISSUER_SERIAL, X509_KEY_IDENTIFIER, SKI_KEY_IDENTIFIER, EMBEDDED_KEYNAME, EMBED_SECURITY_TOKEN_REF, UT_SIGNING, THUMBPRINT_IDENTIFIER
Keystore Alias	Specifies an alias of the public certificate from the truststore to be used for encryption.

Copyright © Cloud Software Group, Inc. All Rights Reserved