Authorization is the process of verifying that a presentity
has the necessary authority to perform certain operations. Authentication
is the process of checking incoming requests to ensure their validity.
Use the Presence Server configuration
file to enable or disable authorization and authentication, and to
configure other security-related settings.
Before you begin
You will need the following files to complete
this task. After you install the
Presence Server product,
these files are found in the directory
was_root/installableApps/presence/scripts/config.
- SystemConfiguration.xml
- ConfigurationParams.txt
- UpdateConfiguration.jar
Before you can make changes to your configuration, the file
UpdateConfiguration.jar must
be in the class path.
About this task
In Presence Server,
the configuration file is used to enable and disable authorization
and to establish paths for allowing and disallowing access by white-list
and black-list users. Presence Server also
supports authorization rules, such as those in IBM® WebSphere® XML
Document Management Server Component (IBM XDMS).
These rules enable presentities to specify which users are allowed
to watch their presence information.
Authorization is disabled
by default. If you plan to use an authorization application with Presence Server,
you must enable authorization (externalAuthorization tag) and you
must disable white lists and black lists (authorizationLists tag).
To
enable or disable authorization and authentication, and to configure
other security-related settings, complete the following steps:
- Open SystemConfiguration.xml with
a text editor.
- Modify the externalAuthorization tag to
enable the use of external authorization applications.
Set enable="true" to
enable the authorization API. Subscriptions are authorized only when
the authorization service provides authorization.
Set enable="false" Address
and port of the group list server to which SUBSCRIBE requests are
sent. Transport protocol for incoming requests can be specified here.
If transport protocol is omitted, then XDMS listening port is configured
in UDP protocol by default.
For example: - <externalAuthorization enable="true"/>
- Modify the attributes on the authorizationLists tag
to define IBM XDMS paths
for accessing a white list and a black list. Requests coming from
presentities in the white list are always authorized, regardless of
presence authorization rules. Requests coming from presentities in
the black list are always rejected.
You can set the
following attributes. Default values are shown.
- enable="false"
- true to enable the use of white lists, black
lists, or both; false to disable
- XDMSSipAddress=""
- Address of the IBM XDMS server
to which subscription requests are sent
- fromUri
- A valid SIP URI that will appear in the
From: header for outgoing SUBSCRIBE requests sent to the IBM XDMS shared
list server. This value is required.
- assertedIdentity=""
- URI, in scheme:identity format, of the requester authorized to
get XCAP documents
This value will appear in the P-Asserted-Id:
header for outgoing SUBSCRIBE requests sent to the IBM XDMS shared
list server. The
identity must have IBM XDMS administrator
authority to access user groups.
For the
assertedIdentity attribute,
the display name is optional. If you choose to define a display name,
you must use the HTML code for symbols for the value of the attribute.
For example, use
<assertedIdentity=""Super Admin" <glm:GLMSuperAdmin>"/>
instead
of
<assertedIdentity=""Super Admin" <glm:GLMSuperAdmin>" />
- user=""
- A user ID with administrator-level privileges, for connecting
to the Aggregation Proxy. This value is optional.
- password=""
- Password of the administrator-level user, for connecting to the
Aggregation Proxy. Required only when a user is specified.
- subscribeExpiration="63"
- Time, in minutes, to specify in the Expire header
when Presence Server sends
SUBSCRIBE requests to the IBM XDMS shared
list server. The subscription will be refreshed as long as there are
client subscriptions on the server.
- retryInterval="5"
- Time, in minutes, to wait before retrying a request
that fails. This applies to outgoing SUBSCRIBE requests sent to an
external source–for example, the IBM XDMS shared
list server. Presence Server sends
the requests to subscribe to the group content and to receive notification
when the group content is modified. The valid range is 1-1440.
- xcapRoot=""
- HTTP URL of the IBM XDMS server
from which Presence Server should
get data using xcap_get requests. This attribute
provides a way for Presence Server to
connect directly with the IBM XDMS server
rather than connecting through the Aggregation Proxy.
When xcapRoot is
specified, Presence Server uses
this value as the URI for performing the xcap_get operation–bypassing
the Aggregation Proxy.
In this case, Presence Server uses
the asserted identity to perform the operation.
When xcapRoot is
not specified, Presence Server performs
the xcap_get operation using the xcap root URI
that is specified in the NOTIFY request received from IBM XDMS.
In this case, Presence Server uses
the specified user ID and password to perform the operation.
You
must specify an xcapRoot when enableXcapEvent is
true.
- whiteListPath=""
- The IBM XDMS path
that designates a white list–a list of presentities whose requests
are always authorized.
- blackListPath=""
- The IBM XDMS path
that designates a black list–a list of presentities whose requests
are never authorized.
- specifyAssertedIdentityOnAllRequests="true"
- If set to true, a P-Asserted-Identity must be
specified in all outgoing subsequent subscribe requests. If set to false,
a P-Asserted-Identity is required only in the first outgoing SUBSCRIBE
request but is not required in subsequent SUBSCRIBE requests.
For example: - <authorizationLists enable="true" sipAddress="sip:xdmshostname.example.com:5070"
fromURI="sip:user@example.com" assertedIdentity="sip:superadmin@example.com" user="glsuser"
password="authpw" subscribeExpiration="63" retryInterval="1" xcapRoot=""
whiteListPath="xcap.example.com/services/resource-lists/users/sip:white.xml"
blackListPath="xcap.example.com/services/resource-lists/users/sip:black.xml" specifyAssertedIdentityOnAllRequests="true"/>
- Modify the attributes on the publicIdMapping tag
to define the ways in which Presence Server uses
mapping and normalization for presentities on white and black lists,
and for presence rules.
You can set the following attributes.
All values are disabled by default.
- enableForWhiteList
- true to enable ID mapping for presentities on
the white list; false to disable.
- enableForBlackList
- true to enable ID mapping for presentities on
the black list; false to disable.
- enableForPresenceRules
- true to enable the testing of identity conditions
for comparison in Presence rules documents; false to
disable.
For example: - <publicIDMapping enableForWhiteList="true" enableForBlackList="true" enableForPresenceRules="true"/>
- Modify the attributes on the presenceRules tag
to specify an IBM XDMS server
and user name for getting Presence rules documents.
You
can set the following attributes. Default values are shown.
- enable="false"
- true to enable IBM XDMS to
get presence rules; false to disable
- XDMSSipAddress=""
- SIP Address, port, and transport protocol (optional) of the IBM XDMS server
to which subscription requests are sent
- fromUri
- A valid SIP URI that will appear in the
From: header for outgoing SUBSCRIBE requests sent to the IBM XDMS shared
list server. This value is required.
- assertedIdentity=""
- URI, in scheme:identity format, of the requester authorized to
get XCAP documents
This value will appear in the P-Asserted-Id:
header for outgoing SUBSCRIBE requests sent to the IBM XDMS shared
list server. The
identity must have IBM XDMS administrator
authority to access user groups.
For the
assertedIdentity attribute,
the display name is optional. If you choose to define a display name,
you must use the HTML code for symbols for the value of the attribute.
For example, use
<assertedIdentity=""Super Admin" <glm:GLMSuperAdmin>"/>
instead
of
<assertedIdentity=""Super Admin" <glm:GLMSuperAdmin>" />
- user=""
- A user ID with administrator-level privileges, for connecting
to the Aggregation Proxy. This value is optional.
- password=""
- Password of the administrator-level user, for connecting to the
Aggregation Proxy. Required only when a user is specified.
- subscribeExpiration="63"
- Time, in minutes, to specify in the Expire header
when Presence Server sends
SUBSCRIBE requests to the IBM XDMS shared
list server. The subscription will be refreshed as long as there are
client subscriptions on the server.
- retryInterval="5"
- Time, in minutes, to wait before retrying a request
that fails. This applies to outgoing SUBSCRIBE requests sent to an
external source–for example, the IBM XDMS shared
list server. Presence Server sends
the requests to subscribe to the group content and to receive notification
when the group content is modified. The valid range is 1-1440.
- xcapRoot=""
- HTTP URL of the IBM XDMS server
from which Presence Server should
get data using xcap_get requests. This attribute
provides a way for Presence Server to
connect directly with the IBM XDMS server
rather than connecting through the Aggregation Proxy.
When xcapRoot is
specified, Presence Server uses
this value as the URI for performing the xcap_get operation–bypassing
the Aggregation Proxy.
In this case, Presence Server uses
the asserted identity to perform the operation.
When xcapRoot is
not specified, Presence Server performs
the xcap_get operation using the xcap root URI
that is specified in the NOTIFY request received from IBM XDMS.
In this case, Presence Server uses
the specified user ID and password to perform the operation.
You
must specify an xcapRoot when enableXcapEvent is
true.
- enableMultipleIDMapping="true"
- true to omit the schema name from the authorized
user's URI when getting presence rules from the IBM XDMS server. false to
include the schema name.
For example, if the user's URI is sip:name@host,
specify true to identify the user to the server as name@host.
Specify false to identify the user as sip:name@host.
- Modify the authorizationChangeJMS tag
to specify whether, following a change in authorization, the JMS message
sent to servers in the cluster should contain the authorization document.
Set includeFullDocument="true" (the
default) to include the authorization document in the JMS message
after a change in authorization.
Set includeFullDocument="false" to
omit the authorization document from the JMS message.
A setting
of true might improve performance because the documents
are cached and do not need to be retrieved from the database. If you
do not require the additional content, you can disable this feature.
Doing so reduces the size of JMS messages and may, as a result, improve
the performance of your system.
For example: - <authorizationChangeJMS includeFullDocument="true"/>
- On the authentication tag, set authenticatedUserOnAllRequests=true to
specify that all incoming Subscribe requests must be authenticated.
The default value is true.
When you
are using the IMS Trust Association Interceptor (TAI),
this setting means that a p-asserted-identity header must be specified
in each incoming request.
When authenticatedUserOnAllRequests=false,
only the first request is authenticated. Subsequent requests in the
Subscribe dialog are treated as if they came from the sender of the
first request.
For example: - <authentication authenticatedUserOnAllRequests="true"/>
- Save and close the file.
- Open ConfigurationParams.txt with
a text editor.
- Update
the following parameters for your environment:
- cfg.system = xml_path (where xml_path is
the directory location for SystemConfiguration.xml)
- username = database_administrator_user_name
- password = database_administrator_password
dbDriver =
com.ibm.db2.jcc.DB2Driver
dbDriver =
oracle.jdbc.driver.OracleDriver
dbConnectionString =
jdbc:db2://database_host_name:database_port/database_name
dbConnectionString =
jdbc:oracle:thin:@database_host_name:database_port:database_name
- Run the java command
that is appropriate for your operating system:
Important: Enter the following
parameters on a single line.

java
-classpath UpdateConfiguration.jar: jdbc_path CmdConfig config_path/ConfigurationParams.txt
(where jdbc_path is the directory location
for your JDBC drivers and config_path is the directory
location for ConfigurationParams.txt)Important: JDBC drivers must be separated by a colon.
For example:
/usr/IBM/WebSphere/AppServer/java/bin/java -classpath UpdateConfiguration.jar:/opt/IBM/db2/V9.5/java/db2jcc.jar:/opt/IBM/db2/V9.5/java/db2jcc_license_cu.jar CmdConfig ConfigurationParams.txt
/opt/IBM/WebSphere/AppServer/java/bin/java -classpath UpdateConfiguration.jar:/opt/IBM/db2/V9.5/java/db2jcc.jar:/opt/IBM/db2/V9.5/java/db2jcc_license_cu.jar CmdConfig ConfigurationParams.txt
- Restart the application:
- Click .
Note: If you are using WebSphere Application Server version 6.1.0.x, reach
this window by clicking .
- Select the check box associated with the Presence Server.
- Click Stop. The Application
Status column should indicate a Stopped status.
- Click Start. The Application
Status column should indicate a Started status.
- Restart all servers that are running applications that
have implemented the authorization service.
Results
Note: xcap_get requests for external lists
group lists uses user and password, if available. If there is no configured
user, asserted identity is used assertedIdentity.