Skip Headers

Oracle® Communication and Mobility Server Administrator's Guide Release 10.1.3 Part Number E10292-02 |
Home | Contents | Index | Contact Us

Previous | Next
| View PDF

# 6 OCMS Security

This chapter describes how to set the security provider for an application. This chapter includes the following topics:

- "Overview of Security"

- "Configuring Applications to Use Login Modules"

- "Configuring Login Modules for the JBoss Application Server"

- "Security in SIP Servlets"

- "Authentication Using the P-Asserted Identity Header"

- "Authentication of Web Service Calls and XCAP Traffic"

## Overview of Security

OCMS implements both basic (HTTP) authentication and digest authentication as described in RFCs 3261 and 2617. In OCMS, both SIP and HTTP applications can be configured to authenticate against the TimesTen In-Memory Database that stores users, user roles, and user data, a RADIUS authentication system, or the Oracle Internet Directory (OID).

The Subscriber Data Services application provides the infrastructure for authentication and authorization. This application, which is parent to applications requiring authentication, enables its child applications to access the authentication backend (TimesTen, RADIUS or Oracle Internet Directory) by means of native Enterprise JavaBeans (EJBs). Subscriber Data Services provides a framework that enables security but does not impose security constraints itself; this is done instead by its child applications, such as Proxy Registrar, which have authority constraints defined by the `<security-constraint>` element in `sip.xml`. For more information on configuring security in the deployment descriptor file, see "Security in SIP Servlets".

Each of the child applications of Subscriber Data Services must be configured to use a JAAS (Java Authentication and Authorization Service) login module for authentication and authorization against the configured user repository.

### The OCMS JAAS-Compliant Login Modules

OCMS leverages the pluggable architecture of JAAS by providing the following modules that check user credentials stored in the TimesTen or RADIUS user repositories for SIP or HTTP applications:

- OCMS Login Module

  The OCMS Login Module provides authentication and authorization against the users provisioned to the TimesTen In-Memory database. These users are provisioned using the CommandService MBean or through the Sapphire Shell (Sash) as described in Chapter 5, "Provisioning Users and Applications". The OCMS Login Module provides digest authentication for SIP applications and basic authentication for HTTP applications. For converged applications (applications containing both SIP servlets and HTTP), the OCMS Login Module provides basic authentication.

  Note:

  User provisioning depends upon the type of user repository and login module. While you can provision users to the TimesTen In-Memory database using Sash and then authenticate and authorize these users using the OCMS Login Module, you can also use Sash to provision users to the TimesTen In-Memory database while using an external database based on the RADIUS (Remote Authentication Dial-In User Service) protocol to store user passwords.

- RADIUS Login Module

  The RADIUS Login Module provides digest authentication for SIP applications as described in RFC 4590 and basic authentication HTTP applications for users provisioned to a RADIUS database.

  The RADIUS database only authenticates users. Unlike the TimesTen In-Memory database, RADIUS is not used to authorize users. Therefore, if you use the RADIUS Login Module, you must create users and assign the appropriate roles in the TimesTen In-Memory database that correspond to each user provisioned to the RADIUS database for role-based authorization. When deleting a user's authentication information from a RADIUS database, you must also delete that user's authorization information (for example, an account and role-related information) manually from the TimesTen In-Memory database. This prevents a future user provisioned with the same user name in RADIUS from inheriting the authorization and account-specific information of a user who had previously been deleted.

  Note:

  Due to licensing restrictions, open source RADIUS is not packaged with OCMS during installation. Prior to configuring the RADIUS Login Module with OCMS, the JRadius client library must be manually downloaded and installed. The necessary JRadius client library can be downloaded from the Sourceforge project at:

  `http://jradius-client.sourceforge.net/`

  Once the JRadius client library has been downloaded, manually copy the `jradius-client.jar` file to `$ORACLE_HOME/j2ee/home/lib/ext` on Oracle Containers for J2EE (OC4J) deployments or to `$JBOSS_HOME/server/default/lib` on JBoss Application Server deployments. You must then restart the application server to deploy the RADIUS Login Module.

These pluggable JAAS login modules enable the SIP servlet container to perform authentication and authorization against external databases for User Agents sending SIP requests. The modules implement user authentication against the TimesTen or RADIUS user repositories by first invoking the JAAS `LoginModule` class and then by authorizing a previously authenticated user by verifying that the appropriate access permissions have been granted.

Note:

Because these login modules authenticate users against external repositories, they are considered custom security providers in OC4J. See Oracle Containers for J2EE Security Guide for information on configuring a custom security provider within a J2EE application.

#### Application Type and Authentication Mode

The type of application (SIP, HTTP, or converged) dictates the authentication mode used by login module. As noted in Table 6-1, HTTP and converged applications are limited to basic authentication. In particular, this limitation applies to third-party HTTP applications that are deployed to OCMS and use the J2EE container to invoke the OCMS Login module.

Note:

Although the Aggregation Proxy is a Web application, it is not limited to basic authentication because it explicitly performs authentication using internal security APIs. As a result, the Aggregation Proxy's default security settings (which set the authentication method as digest) will work without further configuration.

Table 6-1 Authentication Based on Application Type

Application Types | Authentication Mode
--- | ---
SIP | Basic or Digest
HTTP and Converged | Basic Only

Note:

This chapter describes how to specify the login module used by an application and how to configure the OCMS and RADIUS login modules themselves. See "Configuring Oracle Internet Directory as the User Repository" for information on using Oracle Internet Directory (OID), the LDAP data store used by Oracle WebCenter Suite, as the user provisioning repository for an OCMS deployment.

## Configuring Applications to Use Login Modules

You configure security for SIP applications by first defining the `<security-constraint>` element in the deployment descriptor file, `sip.xml`, setting the security provider (login module) appropriate to the authenticating user repository used by the application and then by configuring the login module itself. For more information on setting security in `sip.xml`, see "Security in SIP Servlets".

You can configure a login module for each application that you deploy. During the deployment process, you can configure the login module for SIP or HTTP applications using the Security Provider task in the Deployment Settings page of the Application Server Control deployment wizard. Once you deploy an application, you can examine or edit its login module's configuration From the Edit Login Module page, accessed from the Security Providers task in the Administration page (Figure 6-1).

Figure 6-1 Modifying a Login Module.

Description of "Figure 6-1 Modifying a Login Module."

For more information, see Deploying with Application Server Control Console in Oracle Containers for J2EE Deployment Guide

### Configuring Login Modules though system-jazn-data.xml and orion-application.xml

Alternatively, login modules can also be configured through the `<jazn-loginconfig>` settings either in the `system-jazn-data.xml` file or in the `orion-application.xml` file located in an application's EAR (Enterprise Archive) file.

#### Configuring Login Modules in system-jazn-data.xml

The `system-jazn-data.xml` file is the repository for login module configuration. The settings in this file are updated when you administer login modules through Oracle Application Server Control (Figure 6-1) or through the OracleAS JAAS Provider Admintool. For more information, see Oracle Containers for J2EE Security Guide.

Table 6-2 describes the options supported by the OCMS Login Module and the RADIUS Login Module that you configure in `system-jazn-data.xml`.

Table 6-2 Login Module Options

Option | Description
--- | ---
`useUTF8` | If set to `true`, then the login module supports user names and passwords encoded in the UTF-8 character set.
`authMethod` | For SIP applications, select either `Basic` or `Digest`. For HTTP applications, select `Basic`.
`failurePeriod` | The time, in seconds, that an account is locked. The value entered in `orion-application.xml` takes precedence over the value entered in the `DefaultLockDuration` attribute of the AA Service MBean. See also "SIP Servlet Container".
`maxfailure` | The number of failed login attempts before an account is blocked.

#### Declaring the OCMS Login Module in orion-application.xml

The `<jazn-loginconfig>` element in `orion-application.xml` defines the login modules used by an application. The configurations you set in this file are populated to `system-jazn-data.xml`. Example 6-1 and Example 6-2 illustrate configuring login modules for authentication against the TimesTen In-Memory database and a RADIUS authentication system, respectively.

Example 6-1 illustrates how the Proxy Registrar, a SIP application (defined in the `<application>` element), uses the OCMS Login Module to authenticate against the TimesTen In-Memory database. The OCMS Login Module class is declared within the `<login-module>` element. The `<control-flag>` element further describes the OCMS Login Module as required, meaning that the OCMS Login Module must succeed. The options for this module (described in Table 6-2) set the OCMS Login Module to authenticate user names and passwords encoded in UTF-8 character set. The `<failurePeriod>` element locks the account for 600 seconds after an unsuccessful login attempt. The `<maxFailure>` element sets the number of unsuccessful login attempts to five.

Example 6-1 Declaring the OCMS Login Module in orion-application.xml

    <jazn-loginconfig>
            <application Key="name">
                <name>proxyregistrar</name>
                <login-modules>
                    <login-module Key="class control-flag">
                        <class>
                            oracle.sdp.ocmsloginmodule.OCMSLoginModule
                        </class>
                        <control-flag>required</control-flag>
                        <options>
                            <option>
                                <name>useUTF8</name>
                                <value>true</value>
                            </option>
                            <option>
                                <name>authMethod</name>
                                <value>Digest</value>
                            </option>
                            <option>
                                <name>failurePeriod</name>
                                <value>600</value>
                            </option>
                            <option>
                                <name>maxFailure</name>
                                <value>5</value>
                            </option>
                        </options>
                    </login-module>
                </login-modules>
            </application>
        </jazn-loginconfig>

#### Declaring the RADIUS Login Module in orion-application.xml

Like Example 6-1, Example 6-2 defines a login module for the Proxy Registrar application. This application, however, requires users to be authenticated against the RADIUS database. In addition to the options described in Table 6-2, the RADIUS Login Module also supports the options described in Table 6-3.

Table 6-3 RADIUS Login Module Options

Option | Description
--- | ---
`hostname` | The host name or IP address of the remote RADIUS server.
`authPort` | The destination port for authentication requests.
`acctPort` | The destination port for the accounting server.
`sharedSecre`t | A `String` known only to the RADIUS server and the RADIUS client.

Example 6-2 Declaring the Radius Login Module in orion-application.xml

    <jazn-loginconfig>
           <application Key="name">
               <name>proxyregistrar</name>
               <login-modules>
                   <login-module Key="class control-flag">
                       <class>
                           oracle.sdp.radiusloginmodule.RadiusLoginModule
                       </class>
                       <control-flag>required</control-flag>
                       <options>
                           <option>
                               <name>useUTF8</name>
                               <value>true</value>
                           </option>
                           <option>
                               <name>authMethod</name>
                               <value>Digest</value>
                           </option>
                           <option>
                               <name>failurePeriod</name>
                               <value>600</value>
                           </option>
                           <option>
                               <name>maxFailure</name>
                               <value>5</value>
                           </option>
                           <option>
                               <name>hostName</name>
                               <value>127.0.0.1</value>
                           </option>
                           <option>
                               <name>authPort</name>
                               <value>1812</value>
                           </option>
                           <option>
                               <name>acctPort</name>
                               <value>1813</value>
                           </option>
                           <option>
                               <name>sharedSecret</name>
                               <value>secret</value>
                           </option>
                           <option>
                               <name>radiusClientClass</name>
                               <value>oracle.sdp.radiusloginmodule.JRadiusClient</value>
                           </option>
                       </options>
                   </login-module>
               </login-modules>
           </application>
       </jazn-loginconfig>

## Configuring Login Modules for the JBoss Application Server

You must configure a security domain for each application that you deploy through the JBoss Application Server. You reference this domain for each application in the `<security-domain>` element (illustrated in Example 6-3) in `jboss-app.xml`.

Example 6-3 Defining a Security Domain

    <security-domain>java:/jaas/OCMSSecurity</security-domain>

For SIP applications, define the value for `<security-domain>` as `OCMSSecurity` (for digest authentication) or `OCMSSecurityBasic` (for basic authentication). For HTTP applications, enter `OCMSSecurityBasic` as the value for `<security-domain>`.

## Security in SIP Servlets

OCMS supports declarative and programmatic security for SIP servlets as described in the SIP Servlet API.

Declarative Security

The SIP Servlet API describes declarative security as expressing an application's security structure that includes roles, access control, and authentication requirements in a form that is external to the applicationFoot 1 . The deployment descriptor, `sip.xml`, is the vehicle for declarative security. Developers define how security should be effected in a deployed application by defining the `<security-constraint>` element. This element, which is described in detail in Oracle Communication and Mobility Server Developer's Guide, includes the following child elements (described in Table 6-4).

In OCMS, you first configure security for SIP applications by defining these elements. You can also set the login module used by the application in the `system-jazn-data.xml` file or in the `orion-application.xml` file as described in "Configuring Applications to Use Login Modules".

Note:

You can prevent a SIP application from performing authentication by removing the constraints defined in `sip.xml` and then by redeploying the application.

Table 6-4 Child Elements of the <security-constraint> Element

Element | Description
--- | ---
`<proxy-authentication>` | If this element is present in `SIP.xml`, the container must challenge the user agent with a 407 (Proxy Authentication Required) response status code when authenticating an incoming request or return a 401 response (Unauthorized).
`<resource-collection>` | A set of servlets and SIP methods. This element describes the servlet that requires authentication and the SIP methods used for authentication.
`<auth-constraint>` | Indicates the user roles that are permitted access to this resource collection.
`<role-name>` | The name of a security role.

Programmatic Security

Programmatic security describes the security model from inside a servlet using the `SipServletMessage` methods `getRemoteUser`, `isUserInRole`, and `getUserPrincipal`.

## Authentication Using the P-Asserted Identity Header

The SIP Servlet API 1.0 states that in addition to basic and digest authentication, a User Agent authenticates users through the P-Asserted Identity, a SIP header field that conveys the identity of an authenticated user between the nodes of a trusted domain. As described in RFC 3325, a proxy within a trusted domain can receive messages from both trusted and non-trusted nodes alike. In the case of the latter, the proxy authenticates the originator of the message using digest authentication. The proxy then creates the P-Identity Asserted header field from the identity that it derived from authentication and places this field into the message header which it passes to other entities. For example, an inbound proxy server authenticates a user and then inserts the P-Asserted Identity header field into the received SIP message. By inserting the P-Asserted Identity header field, other servers within the trusted domain (such as the Presence Server) do not have to perform authentication again.

OCMS supports the trusted domain identity assertion described in RFC 3325 through the SipservletCommandInterceptors attribute of its SIP Servlet Container Mbean.

## Authentication of Web Service Calls and XCAP Traffic

The Aggregation Proxy authenticates any XCAP traffic and Web Service calls (which are conducted through HTTP, not SIP) by inserting one of the following headers that are set through the Aggregation Proxy Mbean:

- X_3GPP_ASSERTED_IDENTITY (the default)

- X_3GPP_INTENDED_IDENTITY

- X_XCAP_ASSERTED_IDENTITY

The XCAP traffic and Web Service calls are then proxied to their respective servers. See also "Securing the XDMS with the Aggregation Proxy". For more information on Web Services, see Oracle Communication and Mobility Server Developer's Guide.

Footnote Legend

Footnote 1: SIP Servlet API, Version 1.0