- api.client.keystore - specifies the keystore file containing the client certificate
- api.client.keystore.pass - specifies the password of the keystore file specified by api.client.keystore
- api.client.keystore.type - specifies the type of the keystore file specified by api.client.keystore; optional property, if not specified the default keystore format for the JVM will be used
- api.client.key.pass - specifies the password of the private keystored in the keystore file contained in api.client.keystore; if this property is missing, the password specified by api.client.keystore.pass is used instead.
- api.client.truststore - specifies the keystore file containing the TDI Server public certificate.
- api.client.truststore.pass - specifies the password for the keystore file specified by api.client.truststore.
- api.client.truststore.type - specifies the type of the keystore file specified by api.client.truststore; optional property, if not specified the default keystore format for the JVM will be used
Use the Server API specific SSL properties when your client application is using the standard Java SSL properties. The standard Java SSL properties are properties used to configure another SSL channel used by the same application.
We can specify these properties as JVM arguments on the command line, for example:
java MyTDIServerAPIClientApp -Dapi.client.ssl.custom.properties.on=true -Dapi.client.truststore=C:\TDI\serverapi\testadmin.jks -Dapi.client.truststore.pass=administrator -Dapi.client.keystore=C:\TDI\serverapi\testadmin.jks -Dapi.client.keystore.pass=administrator
This example refers to the sample "testadmin.jks" keystore file shipped with TDI. Note that it contains both the client private key and also the public key of the TDI Server, so we use it both as a keystore and truststore.
We can specify these properties in global.properties or solution.properties when the client is a TDI server.
Using the standard SSL Java System properties
When the Java System property api.client.ssl.custom.properties.on is missing or when it is set to "false", then the standard JSSE system properties are used for configuring the SSL channel. Follow the standard JSSE procedure for configuring the keystore and truststore used by the client application.
We can specify these properties as JVM arguments on the command line, for example:
java MyTDIServerAPIClientApp -Djavax.net.ssl.keyStore=C:\TDI\serverapi\testadmin.jks -Djavax.net.ssl.keyStorePassword=administrator -Djavax.net.ssl.trustStore=C:\TDI\serverapi\testadmin.jks -Djavax.net.ssl.trustStorePassword=administrator
Also these properties can be specified in global.properties or solution.properties when the client is a TDI server.
Server API authentication
Server API authentication is usually referred to in the context of a remote Server API client establishing a Server API session. This scenario represents the substance of the Server API authentication logic as the Server API provides several different kinds of client authentication. But before diving into the different authentication mechanisms let us discuss the scenario in which a local client establishes a local Server API session.
Local client session
A local client session is a session established by a client which runs in the same Java Virtual Machine as the TDI server. Examples of such sessions are local sessions for access to the local Server API established from JavaScript code in hooks or in a Script component, from Connectors and Function Components which are executed as part of an AssemblyLine which runs in the same TDI server, and so on. When a local client establishes a local Server API session, the client has two options:
- Do not provide a username and password pair - in this case the local Server API session is established and the client is authorized as having the "admin" role. For more information about Server API roles, see Server API Authorization.
- Provide a username and password pair - in this case the Server API session is established only after the "username" supplied in the username and password pair is authorized according to the Server API Authorization logic described in the Server API Authorization section. This option would normally be used when a specific user ID is needed for authentication - for demos, prototyping, and so on.
Remote client session
A remote client session is a session established by a client which does not run in the same Java Virtual Machine as the TDI server. Examples of such sessions are sessions for access to a remote Server API established from the Configuration Editor, or a Java™ application wishing to access a TDI Server. For access of this kind there are the following methods of authentication to the TDI Server:
JAAS authentication
The Java Authentication and Authorization Service (JAAS) is supported as an authentication module for TDI Server APIs. JAAS is a set of APIs that enables services to authenticate and enforce access controls upon users. The JAAS authentication is facilitated by the TDI Server API. No changes are required on the TDI Server API clients such as CLI and AMC in order to use the JAAS authentication module.
In order to use JAAS authentication, configure the appropriate properties in global.properties or solution.properties and the JAAS Logon should be installed.
SSL-based authentication
This is the only authentication mechanism available in TDI 6.0. SSL-based authentication is based on a two-stage verification of the client's credentials.
- First the TDI server verifies that a client (represented by its
SSL certificate) has the right to access the TDI server by checking
whether the client's SSL certificate is contained in the TDI
server's truststore, that is, checks whether the TDI server trusts
this client. Checking whether the client's certificate is contained
in the server's truststore is part of the SSL handshake sequence.
Attention: A client certificate example, corresponding to the Server certificate example in file testserver.jks is provided in file serverapi/testadmin.jks; the certificate's password is "administrator". As with all default security parameters we should not rely upon these and generate your own client/server certificates and specify these in the properties files. See Certificates for the TDI Web service Suite.
The truststore is kept in the file indicated by the api.truststore property.
- If the truststore check is successful then the server verifies that the client SSL certificate distinguished name (DN) matches a user ID in the Server API User Registry. If the client certificate's DN does not match any of the user IDs in the Server API User registry file the connection request from the client is denied. This second step could be regarded as part of the authorization sequence as well.
The SSL-based authentication mechanism can be switched off in TDI 7.1. An additional property is available in the TDI Server configuration file global.properties or solution.properties: api.remote.ssl.client.auth.on. When this property is set to "true", the TDI Server requires client authentication within the SSL handshake (the TDI 6.0 mechanism for SSL-based authentication). SSL client authentication for TDI Server API does not depend on whether a username and password pair is supplied. This means that if no username and password pair is supplied, the TDI 6.0 mechanism for SSL-based authentication is used. And if a username and password pair is supplied then the client still needs to send its SSL certificate for authentication, but the User ID for authentication (and at a later step authorization) is taken from the username supplied.
When api.remote.ssl.client.auth.on is set to "false", SSL-based authentication cannot be used. When the property is not specified a value of "false" is assumed.
Username/password based authentication
This mechanism requires a client to supply a username and password on the opening of his Server API connection to the TDI server. In order to configure this authentication method an authentication hook is used.
Authentication hook
This hook allows the provision of custom JavaScript code that performs username and password based authentication. This hook allows bundlers/deployers to write customized JavaScript code, which given a username and password pair determines whether the authentication should succeed or not.
The property allowing for this custom JavaScript authentication is specified in the TDI Server configuration file global.properties or solution.properties: api.custom.authentication. The api.custom.authentication property points to a JavaScript text file on the disk that contains custom authentication code. If this property is not specified then the TDI 6.0 SSL-based authentication mechanism is used. When the api.custom.authentication property is specified, the JavaScript code contained in the specified file is executed for each username and password based authentication request.
The authentication script has access to the predefined script object userdata. This object provides the following two public members:
- userdata.username - contains the name of the user requesting authentication
- userdata.password - contains the password provided by the user
The script is free to perform whatever checks and authentication actions it needs. It returns whether the authentication is successful through the ret object:
- set ret.auth = true to specify that the authentication is successful
- set ret.auth = false to specify that the authentication is not successful; in this case the authentication script can provide additional information for why the authentication failed through the ret.errordescr attribute (for example ret.errordescr = "Invalid user name") and ret.errorcode (for example ret.errorcode = 1).
The description and error code fields is provided by the AuthenticationException thrown by the ServerAPI on unsuccessful authentication.
The authentication script has access to the main script object. It can be used for logging custom messages in the TDI Server log file (for example main.logmsg("Authentication failed for user : " + userdata.username)).
An example authentication hook
An example authentication hook JavaScript file is available (in TDI_install_dir/examples) in order to demonstrate what the JavaScript of an authentication hook could look like. This example JavaScript can also be used as the basis of real-world TDI authentication hooks. The example JavaScript demonstrates how an authentication hook can use an LDAP server (Tivoli Directory Server, Active Directory, and so on) for authenticating client requests.
The JavaScript file is named "ldap_auth.js" and is installed in the examples/auth_ldap TDI Server folder. To deploy this sample LDAP authentication mechanism users can copy that file to the TDI solution folder and specify api.custom.authentication=ldap_auth.js in global.properties or solution.properties. The JavaScript code in "ldap_auth.js" tries to bind to an LDAP Server with the specified username and password. If the bind operation is successful, the script indicates a successful authentication, otherwise the authentication is rejected. The details for connecting to the LDAP Server like the server URL are specified in the "ldap_auth.js" script - this means that users have to edit this file and set the proper connection parameters before using the script. Here is the sample "ldap_auth.js" script:
env = new Packages.java.util.Hashtable();
env.put("java.naming.factory.initial", "com.sun.jndi.ldap.LdapCtxFactory");
env.put("java.naming.provider.url", "ldap://192.168.113.54:389");
env.put("java.naming.security.principal", userdata.username);
env.put("java.naming.security.credentials", userdata.password);
env.put(Packages.javax.naming.Context.SECURITY_AUTHENTICATION, "simple");
main.logmsg("Authentication request for user: " + userdata.username);
try
{
mCtx = new Packages.javax.naming.directory.InitialDirContext(env);
ret.auth = true;
}
catch(e)
{
ret.auth = false;
ret.errordescr = e.toString();
// ret.errorcode = "49";
}
LDAP Authentication support
The TDI Server API provides support for LDAP Authentication. This allows us to leverage your existing LDAP infrastructures that already hold User IDs and Passwords.
LDAP Authentication Configuration
In order to use LDAP authentication the appropriate properties must be configured in global.properties or solution.properties. The list of these properties along with their descriptions follows:
- api.custom.authentication
- This is the same property used for username and password authentication. For more information on username and password authentication see the "Username/password based authentication" section. This property points to a JavaScript text file on the disk that contains custom authentication code. The user may not specify this property, in which case he can only use the TDI 6.0 SSL-based authentication mechanism. The TDI 7.1 username and password authentication does not work. Set this property to "[ldap]" to enable the TDI 7.1 built-in LDAP Authentication mechanism, like this: api.custom.authentication=[ldap] All properties starting with "api.custom.authentication.ldap." are only be taken into account when api.custom.authentication is set to [ldap].
- api.custom.authentication.ldap.critical
- This parameter specifies the Server API behavior when the LDAP
Authentication module cannot be initialized on startup. If this parameter
is set to "true" the Server API initialization fails and the Server
API is not started.
If this parameter is missing or is set to "false" the Server API logs the LDAP Authentication initialization error but the Server API is started. An attempt to initialize the LDAP Authentication module is made on each authentication request received by the Server API until the LDAP Authentication module is initialized.
- api.custom.authentication.ldap.hostname
- The LDAP Server hostname. If LDAP custom authentication is used, this is a required property.
- api.custom.authentication.ldap.port
- The LDAP Server port number. For example, 389 for non-SSL or 636 for SSL. If LDAP custom authentication is used, this is a required property.
- api.custom.authentication.ldap.ssl
- Specifies whether SSL is used to communicate with the LDAP Server. When set to "true" SSL is used, otherwise SSL is not used.
- api.custom.authentication.ldap.searchbase
- Specifies the LDAP directory location where user searches is preformed. When this property is not specified user searches is not performed.
- api.custom.authentication.ldap.admindn
- Specifies an LDAP Server administrator distinguished name that is used for user searches. When this property is not specified anonymous bind is used for user searches.
- api.custom.authentication.ldap.adminpassword
- Password for the LDAP Server administrator distinguished name.
- api.custom.authentication.ldap.userattribute
- Specifies the user id attribute to be used in searches. When this property is not specified user searches are not performed. An example setting of this property would be: api.custom.authentication.ldap.userattribute=cn
If a required property is missing an exception is thrown on initialization.
If the value of either api.custom.authentication.ldap.searchbase or api.custom.authentication.ldap.userattribute is missing no search context is initialized and no searches is performed during the actual user authentication. (No search means that the bind to the LDAP Server is attempted directly with the username and password provided for authentication.)
When api.custom.authentication.ldap.admindn is provided a search context is created using "simple" authentication. If an error occurs during the search context initialization, the initialization of the LDAP Authentication module fails and an exception is thrown.
When api.custom.authentication.ldap.admindn is not provided a JNDI search context is created using JNDI "anonymous" bind.
If the search context cannot be initialized using api.custom.authentication.ldap.admindn, authentication fails directly - no anonymous bind is attempted.
LDAP Authentication Logic
On each attempt to authenticate a user the LDAP Authentication module is passed the username and the password for the user to be authenticated. The following authentication paths are possible:
- Both api.custom.authentication.ldap.searchbase and api.custom.authentication.ldap.userattribute properties are
specified :
- If the username given for authentication ends with the value of the api.custom.authentication.ldap.searchbase property it is assumed that a full distinguished name is provided and no user search is performed. A bind to the LDAP Server is attempted directly with the username and password provided for authentication. If the bind succeeds the authentication is considered successful, otherwise the authentication is considered failed.
- If the username does not end with the value of the api.custom.authentication.ldap.searchbase property, a search with a subtree search scope is executed against the search context created on initialization. The search query used is "(<LDAPUserIDAttribute>=<username>)" where LDAPUserIDAttribute is the value of the api.custom.authentication.ldap.userattribute property and username is the username given for authentication. If exactly one search result is returned, a bind to the LDAP Server is performed with the distinguished name of the returned entry and the password provided for authentication. The authentication succeeds only if the bind to the LDAP Server is successful. In all other cases it is considered that the authentication has failed. If multiple search results are returned, authentication fails.
- At least one of api.custom.authentication.ldap.searchbase or api.custom.authentication.ldap.userattribute properties
is not specified.
In this case no searches are performed and a bind to the LDAP Server is attempted directly with the username and password provided for authentication. If the bind succeeds the authentication is considered successful, otherwise it is considered that the authentication failed.
LDAP Group Support
To ease administration, TDI allows permissions to be configured for groups the same way as they are configured for users. We can set permissions in the User Registry using exactly the same syntax as you would for a user. The fact is that the User Registry does not care whether a security entity is a group or a user. The distinction between users and groups is drawn during the authentication process.
Group membership is configured in the LDAP directory, against which TDI authenticates users. If a user is a member of some LDAP group, all permissions for that group are automatically inherited by the user when the user is authenticated. Group support is disabled by default, so turn it on.
The system properties that are related to LDAP group support are:
- api.custom.authentication.ldap.groupsupport
- This is an pptional property - a boolean flag. If this property is missing, the default value "false" is used. Specifies whether group membership is resolved when authenticating users. If the group membership is resolved, it is taken into account during authorization.
- api.custom.authentication.ldap.usermembershipattribute
- This property is required only if api.custom.authentication.ldap.groupsupport is set to true. Specifies the name of the attribute of a user in LDAP that contains a list of the groups of which the user is a member.
- api.custom.authentication.ldap. usermembershipattributecontent
- This property is required only if api.custom.authentication.ldap.groupsupport is set to true. Specifies how groups are named in the membership attribute of a user. For example, if the user's membership attribute contains values that correspond to the "objectSID" attributes of groups, set this property to "objectSID". If the user's membership attribute contains distinguished names of groups, then set this property to "dn".
- api.custom.authentication.ldap.groupnameattribute
- This property is required only if api.custom.authentication.ldap.groupsupport is set to true. Specifies the name of a group's attribute in LDAP which corresponds to the way the group is named in the TDI User Registry. For example, if LDAP groups are addressed in the TDI registry by their common name, then set this property to "cn". If the User Registry contains the distinguished names of the groups, then set this property to "dn".
- api.custom.authentication.ldap.groupsearchbase
- This property is required only if api.custom.authentication.ldap.groupsupport is set to true. Represents the LDAP directory context, where groups are searched.
- api.custom.authentication.ldap.binaryattributes
- This is an optional property - it represents a list of space-separated attribute names. Specifies attributes which have non-string syntax.
Active Directory example
This example shows how to configure group support to work with an Active Directory server:
api.custom.authentication.ldap.groupsupport=true api.custom.authentication.ldap.usermembershipattribute=tokenGroups api.custom.authentication.ldap.usermembershipattributecontent=objectSID api.custom.authentication.ldap.groupnameattribute=sAMAccountName api.custom.authentication.ldap.groupsearchbase=DC=mytestadserver,DC=com api.custom.authentication.ldap.binaryattributes=objectSID tokenGroups
The 'tokenGroups' attribute is a calculated attribute that exists for all users in Active Directory.
It contains a collection of the Security Identifiers (SIDs) for all security groups that the user is a member of.
This collection contains only security groups (distribution groups, used for e-mail, are not included) and it contains all security groups including nested and primary groups.
The Security Identifiers are binary attributes so they must be set in the api.custom.authentication.ldap.binaryattributes property.
In the above example, groups are named by their "sAMAccountName" LDAP attribute in the TDI User Registry.
Tivoli Directory Server example
This example shows how to configure group support to work with Tivoli Directory Server:
api.custom.authentication.ldap.groupsupport=true api.custom.authentication.ldap.usermembershipattribute=ibm-allGroups api.custom.authentication.ldap.usermembershipattributecontent=dn api.custom.authentication.ldap.groupnameattribute=dn api.custom.authentication.ldap.groupsearchbase=ou=mytestou,c=mytestcountry
For a given user entry, the "ibm-allGroups" operational attribute enumerates all static, dynamic and nested groups, to which that user has membership.
Notes:
- TDI determines group membership by directly examining the LDAP user entry (as opposed to indirectly determining membership by scanning through all groups). For this approach to work correctly, the user entry must have an attribute that enumerates the groups, of which the user is a member. The group support works only with LDAP Servers that do support such a membership attribute on each user entry.
- If you modify the group membership of a user, this does not affect existing Server API sessions. It is, however, reflected in sessions established after the modification.
- Group support is currently provided only for LDAP authentication. There is no group support for JAAS authentication or authentication with custom JavaScript.
- When SSL client authentication is enabled in the Server API, clients that do not specify a username are to be authenticated and authorized based on the owner of the SSL client certificate. If LDAP authentication with group support is also enabled (along with the SSL client authentication), group membership is resolved for the owner of the SSL client certificate.
Host based authentication
Host based authentication is used, when SSL is turned off by specifying api.remote.ssl.on=false in global.properties or solution.properties files. Host based authentication is configured using the api.remote.nonssl.hosts property. This property specifies the list of host IP addresses from which remote Server API clients can use the Server API without specifying a username and password.
The syntax of this list of hosts is: a list of IP addresses (host names are not accepted); use a space, a comma or a semicolon as a delimiter between IP addresses. An example value of this property would be:
api.remote.nonssl.hosts=192.168.111.222, 192.168.112.158
When a client using host based authentication is successfully authenticated, then the client is granted admin authorization authority. That is why adding IP addresses to this list must be done with great care. It is not advisable to use host based authentication in production environment because of its security issues. Host based authentication would normally be used while developing a solution or when doing a demo.
Summary of Server API Authentication options
The following authentication options are available:
- SSL-based authentication (the mechanism available in TDI 6.0)
- Only works when api.remote.ssl.client.auth.on=true (you
also need api.on=true, api.remote.on=true, api.remote.ssl.on=true).
The user is authorized by the rights assigned to the SSL certificate
user ID in the Server API User Registry.
When SSL is used and the remote client application uses Server API listener objects, then the client application must have its own certificate that is trusted by the TDI Server (this is analogous to the setup for SSL client authentication). If there is no client certificate trusted by the TDI Server, the listener objects do not work and the remote client application cannot receive notifications from the TDI Server.
- Username/password based authentication
- Only works when api.custom.authentication is set to a JavaScript authentication file. This authentication method works regardless of whether SSL is used and whether SSL client authentication is used. The user is authorized as per the rights assigned to the username user in the Server API User Registry.
- LDAP authentication
- This was described in section LDAP Authentication support, and is dependent on a number of api.custom.authentication settings in the global.properties or solution.properties.
- Host-based authentication
- Only works when api.remote.ssl.on=false. Then opening of Server API sessions without username and password supplied from all hosts specified by the api.remote.nonssl.hosts property are successfully authenticated and granted admin authority. The api.remote.nonssl.hosts property can be specified in the global.properties or solution.properties.
Server API JMX layer does not support username and password authentication
The remote JMX layer of the Server API does not support username and password based authentication. It ignores the api.custom.authentication properties. Regardless of the value of these properties and whether custom authentication is enabled or not for the Server API, the remote JMX layer performs the following authentication:
- If SSL is turned on and SSL client authentication is turned on, the remote JMX layer performs SSL-based authentication (as in TDI 6.0).
- If SSL is turned on and SSL client authentication is turned off, the remote JMX layer does not work.
- If SSL is turned off, the remote JMX client is successfully authenticated only if its host is specified on the api.remote.nonssl.hosts property, that is, host-based authentication is assumed. In this case the client is granted admin authority.
The net result is that the Server API JMX layer does not support username and password authentication:
Server API authentication setup examples
Authentication configuration examples:
- Non-SSL configuration and custom authentication:
api.remote.ssl.on=false api.remote.nonssl.hosts=192.168.113.51, 192.168.113.52 api.custom.authentication=ldap_auth.js
SSL is not used.- Authentication requests with no username and password supplied succeed only if they are invoked from the localhost or from 192.168.113.51 or 192.168.113.52.
- Authentication requests with username and password supplied succeed only if the ldap_auth.js successfully authenticates the user specified with the username and password parameters.
- Remote JMX clients are authenticated only when the request comes from the localhost or from 192.168.113.51 or 192.168.113.52.
- SSL (without client authentication) and custom authentication:
api.remote.ssl.on=true api.remote.ssl.client.auth.on=false api.custom.authentication=ldap_auth.js
SSL is used for remote Server API communication.- Authentication requests with no username and password supplied fail because neither SSL client authentication, nor host-based authentication is switched on.
- Authentication requests with username and password supplied succeed only if the ldap_auth.js successfully authenticates the user specified with the username and password parameters.
- Host-based authentication is not available in this case regardless of the value of the api.remote.nonssl.hosts parameter, because api.remote.ssl.on is set to true.
- Remote JMX layer is not accessible. This is because SSL is turned on but SSL client authentication is not used.
- SSL with client authentication and custom authentication:
api.remote.ssl.on=true api.remote.ssl.client.auth.on=true api.custom.authentication=ldap_auth.js
SSL is used for remote Server API communication and the Server requires SSL client authentication.- Authentication requests with no username and password supplied succeed when the SSL certificate of the client is present in the Server's truststore (or verifiable using the certificates in the truststore).
- Authentication requests with username and password supplied succeed only when the SSL client authentication is successful (the SSL certificate of the client is present in the Server's truststore) and the ldap_auth.js script successfully authenticates the user specified with the username and password parameters. In this case, authorization is performed based on the username parameter from the username and password supplied and not with the user identity from the SSL client certificate.
- Host-based authentication is not available in this case regardless of the value of the api.remote.nonssl.hosts parameter, because api.remote.ssl.on is set to true.
- Remote JMX clients are authenticated when the SSL certificate of the client is present in the Server's truststore (or verifiable using the certificates in the truststore).
- SSL with client authentication & no custom authentication:
api.remote.ssl.on=true api.remote.ssl.client.auth.on=true api.custom.authentication=
(as an alternative, the "api.custom.authentication" property may be missing entirely)SSL is used for remote Server API communication and the Server requires SSL client authentication.
- Authentication requests with no username and password supplied succeed when the SSL certificate of the client is present in the Server's truststore (or verifiable using the certificates in the truststore).
- Authentication requests with username and password supplied do not succeed because custom authentication is not configured.
- Host-based authentication is not available in this case regardless of the value of the api.remote.nonssl.hosts parameter, because api.remote.ssl.on is set to true.
- Remote JMX clients are authenticated successfully only when the SSL certificate of the client is present in the Server's truststore.
Server API Authorization
After a client Server API session request is authenticated it needs to be authorized.
Users of the Remote API can be assigned several roles; a role defines a list of Server API calls that can be executed by the user and also defines in what context these calls can be executed. A Server API method can be executed if there is at least one role assigned to the user that allows the execution of this method in the context the user tries to execute it. For example, a role can grant the user rights to execute only specific AssemblyLines from a specific configuration. Refer to Server API User Registry for details on how to create the file that holds these user rights.
Authorization is based on the user id. Depending on the authentication mechanism used the user id is retrieved in a different way:
- SSL based authentication - the user id is the distinguished name (DN) of the client's SSL certificate.
- Username or password based authentication - the user id is the username supplied in the username and password pair.
- Host based authentication - no user id can be retrieved from the client using this authentication mechanism; in this case the client session is authorized with the admin role.
Authorization roles
Users of the Remote API are assigned roles; a role defines a list of Server API calls that can be executed by the user and also defines in what context these calls can be invoked. For example, a role can grant the user rights to invoke only specific AssemblyLines from a specific configuration.
Several roles can be assigned to a user, including assigning the same role several times with different parameters. A Server API method can be invoked if there is at least one role assigned to the user that allows the execution of this method in the context the user tries to execute it.
There are no deny semantics - actions cannot be explicitly forbidden. The following roles apply to the Server API security model:
Read role: read [list_of(configuration)]
| The read role allows the user read
data from the Server's configuration(s).
| If no list of configurations is specified or the list is empy, the user is not allowed to read any configuration. A special value * (asterisk) can be specified for the list of configurations and this means that the user is allowed to read (through Server API calls) all configurations currently loaded by the Server. When the list of configurations is not null/empty and does not specify * the user is allowed to read only the configurations specified. The read role does not grant permission
to start processes (AssemblyLines) or
apply any changes to the Server and its configurations. For example:
If no
list of configurations is specified or the list is empty, the user
is not allowed to execute any AssemblyLine from
any configuration.
A special value * (asterisk) can be specified
for the list of configurations and this means that the user is allowed
to execute all AssemblyLines from
all configurations.
When the list of configurations is present
and does not specify * the user is only allowed to start the processes
from the configurations specified in the list. For each configuration
specified in the list:
A user with admin role
is allowed to read and modify configurations, to load new configurations, to execute AssemblyLines, to read
and modify server parameters.
For example:
Admin role is required to use the Remote Configuration
Editor. Also see Using the Remote Configuration Editor.
|
The values specified in a [CONFIG] tag can be either Config file names, or Solution Names if they have been specified in the Config file.
Server API User Registry
The User Registry, identified by the api.user.registry property in the global.properties or solution.properties file is a text file that maintains the information about all the users of the API and their roles. This file is encrypted with the Server's certificate specified by the api.key.alias property from the keystore specified by the api.keystore property. The encryption algorithm employed is Asymmetric RSA encryption or decryption; that is why the Example Server certificate creation specifying the RSA algorithm, which is the default algorithm of the The TDI Encryption utility provided with TDI that we can use for this purpose. On startup, the Server API engine decrypts and reads this file into its memory structures.
Notes:
- The entire user registry file is encrypted as it is, block by block, in a straightforward manner using the RSA algorithm and the server public key. A digital signature or some sort of hashing is not utilized.
- The authorization against the user registry is not optional. Currently the TDI Server has no concept of a plug-in authorization mechanism.
The contents of the Identity Registry text file is structured as follows:
[USER]
[ID]:<user_identifier>
[ROLE]:<role_identifier>
[CONFIG]:<config_identifier>
[AL]:<assembly_line_name>
[AL]:<assembly_line_name>
...
[CONFIG]:<config_id>
...
[ROLE]:<role_identifier>
...
[ROLE]:<role_identifier>
...
[ENDUSER]
[USER]
[ID]:<user_identifier>
[ROLE]:<role_identifier>
...
[ENDUSER]
...
Each tag must span a single line and each tag must be on a separate line. Tabs and spaces do not matter. Empty lines may appear anywhere. The tags in the Identity Registry file and their arguments are as follows:
| Tag | Argument | ||||||
|---|---|---|---|---|---|---|---|
| [USER] | This tag takes no arguments, and serves as an opening bracket for the tags below; a [USER] and [ENDUSER] pair of tags, each placed on a single line, provide the definition of a single user in the registry file. There can be multiple pairs of this type, each of which specify a user of the Server API. | ||||||
[ID]:<user_identifier>
| This tag is the first tag after the [USER] tag
and its argument <user_identifier> is the unique identifier
of the user of the Server API. This ID value is the *** from the truststore file. The tag and the argument
of the tag are placed on a single line, and there can be only one [ID]: tag
included in a [USER] and [ENDUSER] pair.
| [ROLE]:<role_identifier>
| This tag specifies a role for the user. Possible
roles are: read, execute or admin. Everything
after the [ROLE]: tag and its argument and before another [ROLE]: tag
or an [ENDUSER] tag (whichever comes first) specifies details
of this user role. The tag and the argument of the tag are placed
on a single line, and there can be multiple [ROLE]: tags
included in a [USER] and [ENDUSER] pair, specifying
multiple roles for that user.
| [CONFIG]:<config_id>
| This tag specifies the identifier of a TDI configuration, the absolute file path of the configuration.
Relative file paths are not recognized. This tag is subordinate to
a [ROLE]: tag, and the tag specifies a configuration for
the role given by the [ROLE]: tag. This tag and its argument
are placed on a single line, and there can be multiple [CONFIG]: tags, all belonging to the superior [ROLE]: tag.
| If no [CONFIG]: tag is associated with a [ROLE]: tag, the list of configurations for the corresponding role definition is empty. [AL]:<assembly_line_name>
| This tag specifies an AssemblyLine name. This
tag is subordinate to a [CONFIG]: tag. The tag and its argument
are placed on a single line, and there can be multiple [AL]: tags, all belonging to the superior [CONFIG]: tag.
| If no [AL]: tag is associated with a [CONFIG]: tag, the list of AssemblyLines for the corresponding configuration ID is empty. |
The following text is an example of an Identity Registry file:
USER]
[ID]:CN=Stan, OU=TDI, O=IBM, C=US
[ROLE]:admin
[ENDUSER]
[USER]
[ID]:CN=John, OU=TDI, O=IBM, C=US
[ROLE]:read
[CONFIG]:*
[ROLE]:execute
[CONFIG]:C:/TDI/rs.xml
[AL]:*
[CONFIG]:C:/TDI/prototype.xml
[AL]:TestAssemblyLine
[ENDUSER]
[USER]
[ID]:CN=Peter, OU=TDI, O=IBM, C=US
[ROLE]:execute
[CONFIG]:C:/TDI/rs.xml
[AL]:*
[ENDUSER]
This set of Identity Registry entries implies the following constraints:
- "Stan" is an administrator according to this registry file, and is allowed to perform each and every Server API operation.
- John is allowed to read all configurations loaded on the Server, but can only execute processes from two configurations:
- From "rs.xml", John can execute all AssemblyLines.
- From "prototype.xml" John is only allowed to execute the AssemblyLine named "TestAssemblyLine".
- Peter can only execute all AssemblyLines from the "rs.xml" configuration.
The keytool and/or the Ikeyman utility can be used to obtain the user ID from the truststore file. The following command line prints all users from the truststore file:
keytool -v -list -keystore <trust_store_file> -storepass <trust_store_pass>where <trust_store_file> is the keystore file that contains the certificates of all trusted users and <trust_store_pass> is the password for this keystore file. This command line prints something like the text below for each user certificate:
Owner: CN=Stan, OU=TDI, O=IBM, C=US
Issuer: CN=Stan, OU=TDI, O=IBM, C=US
Serial number: 408f6a34
Valid from: 4/28/04 11:24 AM until: 7/27/04 11:24 AM
Certificate fingerprints:
MD5: F6:EF:81:8B:4C:0F:10:E4:A0:16:99:AB:42:29:70:8B
SHA1: FE:37:62:8B:42:2F:54:F8:F6:F3:FC:A1:DD:7D:2A:51:9A:85:09:02The
value of the Owner field must be specified
as value for the [ID]: tag in the Identity Registry as is, including
all white space and commas. For this example, the line with the ID
tag looks like:
[ID]:CN=Stan, OU=TDI, O=IBM, C=USAn alternative way to obtain the user ID from the truststore file is to use Ikeyman in the following way:
- Start Ikeyman (or select Key Manager from the toolbar).
- From the Key Database File menu click Open....
- In the Open field, set the appropriate values and click OK.
- In the Password field, enter the password for the truststore file.
- Click on the certificate you are interested in.
- Click the View/Edit... button. A window opens which contains information on the subject's DN (user ID).
Server Audit Capabilities
The TDI Audit Component enables the TDI Server to audit events such as authentication and authorization in the Server API.
Notifications are generated when authentication and authorization (auth*) events occur. Audit data is packaged into an Entry and provided as user data in the notification. The "Audit Service" consists of a separate Audit config that is automatically loaded by the TDI server. The Audit config contains auto-started Audit AssemblyLines. The Audit ALs iterate on the notification connector using suitable filters. TDI users can even generate "user defined notifications" if they want to create audit events from within their own code.
TDI auditing contains two main parts:
- A way for generating the necessary audit information
- An "Audit service" for handling existing audit data
Generating necessary audit information is implemented by creating TDI Entries on each audit point in the Server API, and by broadcasting these Entries wrapped in a notification. For this purpose a new class is presented in the Server API (com.ibm.di.api.APIAuditor), that generates the Entry, attaches the Entry as UserData to a notification, and sends it to all interested listeners.
The "Audit Service" is the main consumer of the audit notifications. The Audit Service is a config consisting of several ALs that iterate on the Notification Connector. Using different filters can register to a variety of notification types.
Auditing scope
The TDI audit capability follows only what people do, and does not follow Server events in general. There is a difference between a user being authorized to perform a task (stop an AL) and the task actually being performed (AL is terminated). Being authorized is an authorization event and the performing of a legal action, like stopping an AL, is a Server event. When a user instructs an AssemblyLine to stop and the AssemblyLine terminates, an authorization event is paired with a Server event. At other times, a Server event occurs by itself, as when an AssemblyLine completes naturally. Only events which involve direct user interaction are audited. This limits the default audit points to authentication and authorization events inside the Server API. Almost every method exposed by the Server API is protected by its own piece of authorization code. The Audit component does not try to send notifications for all authorization events, but selects a reasonable subset of authorization-guarded Server API methods. The principles for the selection are to audit all events that:
- Delete logs or tombstones
- Start or stop TDI entities such as configs, ALs, and the Server
- Replace the config instance configuration: replace the config instance configuration or the check-in configuration
- Allow the user to change vital TDI data: set external property, post a message in the System Queue, call custom Java code inside the TDI JVM
Suppression of notifications
The TDI Server API allows certain notification types to be suppressed for improved performance. The notification framework does not propagate suppressed events. If you try to broadcast an event of a type suppressed, the Server API does not issue an error. However, the suppressed event cannot reach any of the registered notification listeners. The list of suppressed event types is configured by a system property named:
api.notification.suppress
By default, all authentication and authorization events are suppressed:
api.notification.suppress=di.server.api.authenticate di.server.api.authorize*
The event types in the list are separated by spaces. Wildcards matching multiple event types are allowed. If the event type property is missing or is empty, no events are suppressed. We can suppress all custom notifications by typing:
api.notification.suppress=user
Suppression affects the whole TDI Server and can result in suppression of all kinds of notifications. Even built-in notifications, such as an AssemblyLine starting or the Server shutting down, can be suppressed. Improper use of the suppression capabilities can interfere with the work of components that listen for notifications such as the Tombstone Manager and the Server Notifications Connector.
Sending notifications
Sending notifications uses a method in com.ibm.di.api.APIEngine:
public static void sendNotification (String type, String id, Object data, String configInstanceId)
This method creates a DIEvent. By this means, a notification is delivered to every Listener registered to receive the a particular type of notification. Notification delivery parameters include:
| Parameter name | Definition |
|---|---|
| type | Notification event type. |
| id | Notification event ID. |
| data | Notification event UserData object in the form of a Java object with additional information. |
| configInstanceId | Notification ConfigInstance ID to which the notification is bound. |
The com.ibm.di.api.APIEngine method throws DIException if the type parameter is null. Calls to the method can be invoked either:
- Locally, from the TDI Server JVM. This type of access includes scripting in AssemblyLine hooks and also uses the API from new Connectors implemented in Java and deployed on the TDIServer
- Remotely, from another JVM (on the local or a remote network computer), through Remote Method Invocation (RMI). This type of access uses solutions
that:
- Connect remotely to TDI
- Manage processes within TDI
- Build business logic on top of TDI
- Are applications dedicated only to TDI
- Are applications that use TDI to accomplish some of their goals