WebSphere brand IBM WebSphere Presence Server, Version 7.0

Configuring authorization and authentication

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:

  1. Open SystemConfiguration.xml with a text editor.
  2. 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"/>
  3. 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="&quot;Super Admin&quot; &lt;glm:GLMSuperAdmin&gt;"/>
    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"/>
  4. 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"/>
  5. 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="&quot;Super Admin&quot; &lt;glm:GLMSuperAdmin&gt;"/>
    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.

  6. 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"/>
  7. 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"/>
  8. Save and close the file.
  9. Open ConfigurationParams.txt with a text editor.
  10. 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
    • DB2 dbDriver = com.ibm.db2.jcc.DB2Driver
    • Oracle dbDriver = oracle.jdbc.driver.OracleDriver
    • DB2 dbConnectionString = jdbc:db2://database_host_name:database_port/database_name
    • Oracle dbConnectionString = jdbc:oracle:thin:@database_host_name:database_port:database_name
  11. Run the java command that is appropriate for your operating system:
    Important: Enter the following parameters on a single line.
    • AIXLinux 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:
    • AIX /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
    • Linux /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
  12. Restart the application:
    1. Click Applications > Application types > WebSphere Enterprise Applications.
      Note: If you are using WebSphere Application Server version 6.1.0.x, reach this window by clicking Applications > Enterprise Applications.
    2. Select the check box associated with the Presence Server.
    3. Click Stop. The Application Status column should indicate a Stopped status.
    4. Click Start. The Application Status column should indicate a Started status.
  13. 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.



Terms of use
(C) Copyright IBM Corporation 2009. All Rights Reserved.