Skip Headers
Oracle® WebLogic Communication Services Administrator's Guide
11g Release 1 (11.1.1)

Part Number E13806-01
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

5 Administering Security Features

The following sections provide an overview of Oracle WebLogic Communication Services security:

5.1 Authentication for SIP Servlets

Oracle WebLogic Communication Services users must be authenticated when they request access to a protected resource, such as a protected method within a deployed SIP Servlet. Oracle WebLogic Communication Services enables you to implement user authentication for SIP Servlets using any of the following techniques:

Different SIP Servlets deployed on Oracle WebLogic Communication Services can use different authentication mechanisms as necessary. The required authentication mechanism is specified in the auth-method element of the SIP Servlet's sip.xml deployment descriptor. The deployment descriptor may also define which resources are to be protected, listing specific role names that are required for access. The SIP Servlet v1.1 specification introduces the ability to specify the realm name and identity assertion mechanism required or supported by an application. See the SIP Servlet v1.1 specification for information about defining the Servlet authentication and identity assertion mechanism.

5.1.1 Authentication Providers

Oracle WebLogic Communication Services authentication services are implemented using one or more authentication providers. An authentication provider performs the work of proving the identity of a user or system process, and then transmitting the identity information to other components of the system.

You can configure and use multiple authentication providers to use different authentication methods, or to work together to provide authentication. For example, when using Digest authentication you typically configure both a Digest Identity Asserter provider to assert the validity of a digest, and a second LDAP or RDBMS authentication provider that determines the group membership of a validated user.

When linking multiple authentication providers, you must specify the order in which providers are used to evaluate a given user, and also specify how much control each provider has over the authentication process. Each provider can contribute a "vote" that specifies whether or not the provider feels a given user is valid. The provider's control flag indicates how the provider's vote is used in the authentication process.

For more information about configuring providers, see either Section 5.7, "Configuring Digest Authentication" or Section 5.8, "Configuring Client-Cert Authentication."

5.2 Overriding Authentication with Trusted Hosts

Oracle WebLogic Communication Services also enables you to designate trusted hosts for your system. Trusted hosts are hosts for which Oracle WebLogic Communication Services performs no authentication. If the server receives a SIP message having a destination address that matches a configured trusted host name, the message is delivered without Authentication. See Oracle Fusion Middleware Security Guide for more information.

5.3 Identity Assertion Support

Oracle WebLogic Communication Services supports the P-Asserted-Identity SIP header as described in RFC 3325. This functionality automatically logs in using credentials specified in the P-Asserted-Identity header when they are received form a trusted host. When combined with the privacy header, P-Asserted-Identity also determines whether the message can be forwarded to trusted and non-trusted hosts.

Oracle WebLogic Communication Services also supports identity assertion using the Identity and Identity-Info headers as described in RFC 4474.

Both identity assertion mechanisms require that you configure an appropriate security provider with Oracle WebLogic Communication Services. See Section 5.9, "Configuring SIP Servlet Identity Assertion Mechanisms" for more information.

5.4 Role Assignment for SIP Servlet Declarative Security

The SIP Servlet API specification defines a set of deployment descriptor elements that can be used for providing declarative and programmatic security for SIP Servlets. The primary method for declaring security constraints is to define one or more security-constraint elements and role definitions in the sip.xml deployment descriptor. Oracle WebLogic Communication Services adds additional deployment descriptor elements to help developers easily map SIP Servlet roles to actual principals and/or roles configured in the SIP Servlet container.

5.5 Security Event Auditing

Oracle WebLogic Communication Services includes an auditing provider that you can configure to monitor authentication events in the security realm. See Oracle Fusion Middleware Securing Oracle WebLogic Server for more information.

5.6 Common Security Configuration Tasks

Table 5-1 lists Oracle WebLogic Communication Services configuration tasks and provides links to additional information.

Table 5-1 Security Configuration Tasks

Task Description

Section 5.7, "Configuring Digest Authentication"

  • Understanding the Digest identity assertion providers

  • Configuring LDAP Digest authentication

  • Configuring Digest authentication with an RDBMS

Section 5.8, "Configuring Client-Cert Authentication"

  • Understanding client-cert authentication solutions

  • Delivering X509 certificates over 2-way SSL

  • Developing a Perimeter authentication solution

  • Using the Oracle WebLogic Communication Services WL_Client_Cert header to deliver X509 certificates

Section 5.9, "Configuring SIP Servlet Identity Assertion Mechanisms"

  • Understand forwarding rules for SIP messages having the P-Asserted-Identity header

  • Configuring P-Asserted-Identity providers


5.7 Configuring Digest Authentication

The following sections provide a basic overview of Digest authentication, and describe Digest authentication support and configuration in Oracle WebLogic Communication Services.

5.7.1 What Is Digest Authentication?

Digest authentication is a simple challenge-response mechanism used to authenticate a user over SIP or HTTP. Digest authentication is fully described in RFC 2617.

When using Digest authentication, if a client makes an un-authenticated request for a protected server resource, the server challenges the client using a nonce value. The client uses a requested algorithm (MD5 by default) to generate an encrypted response—a Digest—that includes a username, apssword, and realm.

The server verifies the client Digest by recreating the Digest value and comparing it with the client's Digest. To recreate the Digest value the server requires a hash of the "A1" value (see RFC 2617) that includes, at minimum, the nonce, username, password and realm name. The server either recreates the hash of the A1 value using a stored clear-text password for the user, or by obtaining a precalculated hash value. Either the clear-text password or precalculated hash value can be stored in an LDAP directory or accessed from an RDBMS using JDBC. The server then uses the hash of the A1 value to recreate the Digest and compare it to the client's Digest to verify the user's identity.

Digest authentication provides secure authorization over HTTP because the clear text password is never transmitted between the client and server. The use of nonce values in the client challenge also ensures that Digest authentication is resistant to replay attacks. See Figure 5-1 for a more detailed explanation of the challenge-response mechanism for a typical request.

5.7.2 Digest Authentication Support in Oracle WebLogic Communication Services

Oracle WebLogic Communication Services includes LDAP Digest Identity Asserter security providers for asserting the validity of a client's Digest using LDAP or an RDBMS. A separate authorization provider is required to complete the authentication process (see Section 5.7.4.3, "Configure an Authenticator Provider").

The Digest Identity Asserter only verifies a user's credentials using the client Digest. After the Digest is verified, the configured authorization provider completes the authentication process by checking for the existence of the user (by username) and also populating group membership for the resulting javax.security.auth.Subject.

The Digest Identity Asserter provider requires that user credentials be stored in an LDAP server or RDBMS in one of the following ways:

  • Unencrypted (clear text) passwords. The simplest configuration stores users' unencrypted passwords in a store. If you choose this method, Oracle recommends using an SSL connection to the LDAP store or database to reduce the risk of exposing clear text passwords in server-side network traffic. Some LDAP stores do not support storing unencrypted passwords by default; in this case you must create or use a dedicated credential attribute on the LDAP server for storing the password. See Section 5.7.4.1, "Configure the LDAP Server or RDBMS".

  • Reverse-Encrypted Passwords. Oracle WebLogic Communication Services provides a utility to help you compute the Encryption Key, Encryption Init Vector, and Encrypted Passwords values used when you configure the Digest Authorization Identity Asserter provider.

  • A pre-calculated hash of each password, username, and realm. If storing unencrypted or reverse-encrypted passwords is unacceptable, you can instead store a pre-calculated hash value of the username, security-realm, and password in a new or existing attribute in LDAP or an RDBMS. The Digest Identity Asserter then retrieves only the hash value for comparison to the client-generated hash in the Digest. Storing pre-calculated hash values provides additional security.

The LDAP Digest Identity Asserter is compatible with any LDAP provider that permits storage of a clear text password or pre-calculated hash value.

Note:

You cannot change the schema for the built-in LDAP store to add a dedicated field for storing clear text passwords or pre-calculated hash values. However, you can use the predefined "description" field to store password information for testing or demonstration purposes.

If you do not use the DefaultAuthenticator provider for authentication decisions, you must make DefaultAuthenticator an optional provider (ControlFlag="SUFFICIENT" or lower) before you can use Digest authentication. This will generally be the required configuration in production installations where a separate LDAP store is used to maintain clear text or hashed password information.

Figure 5-1 Digest Authentication in Oracle WebLogic Communication Services

Description of Figure 5-1 follows
Description of "Figure 5-1 Digest Authentication in Oracle WebLogic Communication Services"

Figure 5-1 shows the basic architecture and use of an Identity Asserter provider for a typical client request:

  1. The client makes an unauthorized request for a protected application resource. (SIP Servlet resources can be protected by specifying security constraints in the sip-xml deployment descriptor.

  2. The Digest Identity Asserter provider generates a challenge string consisting of the nonce value, realm name, and encryption algorithm (either MD5 or MD5-sess). The SIP container delivers the challenge string to the client.

    Note:

    The Digest Identity Asserter maintains a cache of used nonces and timestamps for a specified period of time. All requests with a timestamp older than the specified timestamp are rejected, as well as any requests that use the same timestamp/nonce pair as the most recent timestamp/nonce pair still in the cache.
  3. The client uses the encryption algorithm to create a Digest consisting of the username, password, real name, nonce, SIP method, request URI, and other information described in RFC 2617.

  4. The Digest Identity Asserter verifies the client Digest by recreating the Digest value using a hash of the A1 value, nonce, SIP method, and other information. To obtain a hash of the A1 value, the Identity Asserter either generates HA1 by retrieving a clear-text password from the store, or the Identity Asserter retrieves the pre-calculated HA1 from the store.

  5. The generated Digest string is compared to the client's Digest to verify the user's identity.

  6. If the user's identity is verified, an authentication provider then determines if the user exists and if it does, the authentication provider populates the javax.security.auth.Subject with the configured group information. This step completes the authentication process.

    Note:

    If you do not require user existence checking or group population, you can use the special "no-op" Identity Assertion Authenticator to avoid an extra connection to the LDAP Server; see Section 5.7.4.3, "Configure an Authenticator Provider" for more information.

    After authentication is complete, the SIP Servlet container performs an authorization check for the logged in javax.security.auth.Subject against the declarative security-constraints defined in the Servlet's sip.xml deployment descriptor.

The LDAP Digest Identity Asserter and the configured Authentication provider can either use the same LDAP store or different stores.

Note:

If you use multiple LDAP stores, you must also create some infrastructure to keep both stores synchronized in response to adding, removing, or changing user credential changes, as shown in Figure 5-2. Maintaining LDAP stores in this manner is beyond the scope of this documentation.

Figure 5-2 Multiple LDAP Servers

Description of Figure 5-2 follows
Description of "Figure 5-2 Multiple LDAP Servers"

5.7.3 Prerequisites for Configuring LDAP Digest Authentication

In order to configure Digest authentication you must understand the basics of LDAP servers and LDAP administration. You must also understand the requirements and restrictions of your selected LDAP server implementation, and have privileges to modify the LDAP configuration as well as the Oracle WebLogic Communication Services configuration.

Table 5-1 summarizes all of the information you will need in order to fully configure your LDAP server for Digest authentication with Oracle WebLogic Communication Services.

Note that the LDAP authentication provider and the Digest Authentication Identity Asserter provider can be configured with multiple LDAP servers to provide failover capabilities. If you want to use more than one LDAP server for failover, you will need to have connection information for each server when you configure Digest Authentication. See Section 5.7.4, "Steps for Configuring Digest Authentication".

Section 5.12, "Provisioning Resources in Oracle Internet Directory" describes how to provision the correct resources for Oracle Internet Directory.

Table 5-2 Digest Identity Asserter Checklist

Item Description Sample Value

Host

The host name of the LDAP server.

MyLDAPServer

Port

The port number of the LDAP server. Port 389 is used by default.

389

Principal

A Distinguished Name (DN) that Oracle WebLogic Communication Services can use to connect to the LDAP Server.

cn=ldapadminuser

Credential

A credential for the above principal name (generally a password).

ldapadminuserpassword

LDAP Connection Timeout

The configured timeout value for connections to the LDAP server (in seconds). For best performance, there should be no timeout value configured for the LDAP server. If a timeout value is specified for the LDAP server, you should configure the Digest Identity Asserter provider timeout to a value equal to or less than the LDAP server's timeout.

30 seconds

User From Name Filter

An LDAP search filter that Oracle WebLogic Communication Services will use to locate a given username. If you do not specify a value for this attribute, the server uses a default search filter based on the user schema.

(&(cn=%u)(objectclass=person))

User Base DN

The base Distinguished Name (DN) of the tree in the LDAP directory that contains users.

cn=users,dc=mycompany,dc=com

Credential Attribute Name

The credential attribute name used for Digest calculation. This corresponds to the attribute name used to store unencrypted passwords or pre-calculated hash values. See Section 5.7.4.1, "Configure the LDAP Server or RDBMS".

hashvalue

Digest Realm Name

The realm name to use for Digest authentication.

mycompany.com

Digest Algorithm

The algorithm that clients will use to create encrypted Digests. Oracle WebLogic Communication Services supports both MD5 and MD5-sess algorithms. MD5 is used by default.

MD5

Digest Timeout

The Digest authentication timeout setting. By default this value is set to 2 minutes.

2


5.7.4 Steps for Configuring Digest Authentication

Follow these steps to configure Digest authentication with Oracle WebLogic Communication Services:

  1. Section 5.7.4.1, "Configure the LDAP Server or RDBMS".

  2. Section 5.7.4.2, "Reconfigure the DefaultAuthenticator Provider".

    Note:

    DefaultAuthenticator is set up as a required authentication provider by default. If the DefaultAuthentication provider, which works against the embedded LDAP store, is not used for authentication decisions, you must change the Control Flag to "SUFFICIENT".
  3. Section 5.7.4.3, "Configure an Authenticator Provider".

  4. Section 5.7.4.4, "Configure a New Digest Identity Asserter Provider".

The sections that follow describe each step in detail.

5.7.4.1 Configure the LDAP Server or RDBMS

The LDAP server or RDBMS used for Digest verification must store either unencrypted, clear text passwords, pre-calculated hash values, or passwords encrypted by a standard encryption algorithm (3DES_EDE/CBC/PKCS5Padding by default). The sections below provide general information about setting up your LDAP server or RDBMS to store the required information. Keep in mind that LDAP server uses different schemas and different administration tools, and you may need to refer to your LDAP server documentation for information about how to perform the steps below.

If you are using multiple LDAP servers to enable failover capabilities for the security providers, you must configure each LDAP server as described below.

5.7.4.1.1 Using Unencrypted Passwords

If you are using an RDBMS, or if your LDAP server's schema allows storing unencrypted passwords in the user's password attribute, no additional configuration is needed. The Digest Identity Asserter provider looks for unencrypted passwords in the password field by default.

If the schema does not allow unencrypted passwords in the password attribute, you have two options:

  • Store the unencrypted password in an existing, unused credential attribute in the LDAP directory.

  • Create a new credential attribute to store the unencrypted password.

See your LDAP server documentation for more information about credential attributes available in the schema. Regardless of which method you use, record the exact attribute name used to store unencrypted passwords. You must enter the name of this attribute when configuring the LDAP Digest Identity Asserter provider.

5.7.4.1.2 Using Precalculated Hash Values

If you want to use precalculated hash values, rather than unencrypted passwords, you can store the hash values in one of two places in your LDAP directory:

  • In an existing, unused credential attribute.

  • In a new credential attribute that you create for the hash value.

See your LDAP server documentation for more information using or creating new credential attributes.

For RDBMS stores, you can place the hash values in any column in your schema; you will define the SQL command used to obtain the hash values when configuring the RDBMS Identity Assertion Provider.

Oracle WebLogic Communication Services provides a simple utility (PreCalculatedHash) to generate a hash of the A1 value from a given username, realm name, and unencrypted password.

You can use also use 3rd-party utilities for generating the hash value, or create your own method using information from RFC 2617.

Note that you must also create the necessary infrastructure to update the stored hash value automatically when the user name, password, or realm name values change. Maintaining the password information in this manner is beyond the scope of this documentation.

5.7.4.1.3 Using Reverse-Encrypted Passwords

Oracle WebLogic Communication Services provides a utility to help you compute the Encryption Key, Encryption Init Vector, and Encrypted Passwords values used when you configure the Digest Authorization Identity Asserter provider. The utility is named JSafeEncryptionUtil and is packaged in the wlss.jar file in the WLSS_HOME/server/lib/wlss directory.

To view usage instructions and syntax:

  1. Add wlss.jar to your classpath. Here is the default location (but, it is user-customizable):

    export CLASSPATH=$CLASSPATH:WLSS_HOME=MW_HOME/wlcserver_10.3/server/lib/wlss/wlss.jar
    
  2. Execute the utility without specifying options.

5.7.4.2 Reconfigure the DefaultAuthenticator Provider

In most production environments you will use a separate LDAP provider for storing password information, and therefore the DefaultAuthenticator, which works against the embedded LDAP store, must not be required for authentication. Follow the instructions in this section to change the provider's control flag to "sufficient".

Note:

DefaultAuthenticator is set up as a required authentication provider by default. If the DefaultAuthentication provider, which works against the embedded LDAP store, is not used for authentication decisions, you must change the Control Flag to "SUFFICIENT".

To reconfigure the DefaultAuthenticator provider:

  1. Log in to the Administration Console for the Oracle WebLogic Communication Services domain you want to configure.

  2. In the left pane of the Console, select the Security Realms node.

  3. Select the name of your security realm in the right pane of the Console. (for example, myrealm).

  4. Select the Providers > Authentication tab.

  5. Select the DefaultAuthenticator provider.

  6. In the Configuration > Common tab, change the Control Flag value to SUFFICIENT.

  7. Click Save to save your changes.

5.7.4.3 Configure an Authenticator Provider

In addition to the Digest Identity Asserter providers, which only validate the client digest, you must configure an "authentication" provider, which checks for a user's existence and populates the user's group information. Follow the instructions in Oracle Fusion Middleware Securing Oracle WebLogic Server to create an LDAP authentication provider for your LDAP server. Use the information from Table 5-1, "Digest Authentication in Oracle WebLogic Communication Services" to configure the provider.

If you do not require user existence checking or group population, then, in addition to a Digest Identity Asserter provider, you can configure and use the special "no-op" authentication provider, packaged by the name "IdentityAssertionAuthenticator." This provider is helpful to avoid an extra round-trip connection to the LDAP server. Note that the provider performs no user validation and should be used when group information is not required for users.

To configure the "no-op" authorization provider:

  1. Log in to the Administration Console for the Oracle WebLogic Communication Services domain you want to configure.

  2. In the left pane of the Console, select the Security Realms node.

  3. Select the name of your security realm in the right pane of the Console. (for example, myrealm).

  4. Select the Providers > Authentication tab.

  5. Click New.

  6. Enter a name for the new provider, and select IdentityAssertionAuthenticator as the type.

  7. Click OK.

  8. Select the name of the new provider from the list of providers.

  9. Set the Control Flag to SUFFICIENT in the Configuration > Common tab.

  10. Click Save to save your changes.

5.7.4.4 Configure a New Digest Identity Asserter Provider

Follow these instructions in one of the sections below to create the Digest Identity Asserter provider and associate it with your LDAP server or RDBMS store:

5.7.4.4.1 Configure an LDAP Digest Identity Asserter Provider

Follow these instructions to create a new LDAP Digest Identity Asserter Provider:

  1. Log in to the Administration Console for the Oracle WebLogic Communication Services domain you want to configure.

  2. In the left pane of the Console, select the Security Realms node.

  3. Select the name of your security realm in the right pane of the Console. (for example, myrealm).

  4. Select the Providers > Authentication tab.

  5. Click New.

  6. Enter a name for the new provider, and select LdapDigestIdentityAsserter as the type.

  7. Click OK.

  8. Select the name of the new provider from the list of providers.

  9. Select the Configuration > Provider Specific tab in the right pane.

  10. On the configuration page, enter LDAP server and Digest authentication information into the fields as follows (use the information from Table 5-1):

    • User From Name Filter: Enter an LDAP search filter that Oracle WebLogic Communication Services will use to locate a given username. If you do not specify a value for this attribute, the server uses a default search filter based on the user schema.

    • User Base DN: Enter the base Distinguished Name (DN) of the tree in the LDAP directory that contains users (for example, cn=Users,dc=example,dc=com).

    • Credential Attribute Name: Enter the credential attribute in the LDAP directory that stores either the pre-calculated hash value or the unencrypted password (for example, authpassword;wlss). By default Oracle WebLogic Communication Services uses the password attribute of the user entry. If you use a pre-calculated has value instead of an unencrypted password, or if the unencrypted password is stored in a different attribute, you must specify the correct attribute name here.

    • Group Attribute Name: Enter the group attribute in the LDAP directory that stores a the set of group names to which the user belongs.

    • Password Encryption Type: Select the format in which the password is stored: PLAINTEXT, PRECALCULATEDHASH, or REVERSIBLEENCRYPTED.

    • Encryption Algorithm: If you have stored encrypted passwords, enter the encryption algorithm that the Digest identity assertion provider will use for reverse encryption.

    • Encryption Key and Please type again to confirm: If you have stored encrypted passwords, enter the base-64 encrypted key used as part of the reverse encryption algorithm.

    • Encryption Init Vector and Please type again to confirm: If you have stored encrypted passwords, enter the base-64 encrypted init vector string used as part of the reverse encryption algorithm.

    • Digest Realm Name: Enter the realm name to use for Digest authentication (for example, example.com).

    • Digest Algorithm: Select either MD5 or MD5-sess as the algorithm to use for encrypting Digests.

    • Digest Timeout: This value defines the nonce timeout value for the digest challenge. If the nonce timeout is reached before the client responds, the client is re-challenged with a new nonce. By default, the Digest Timeout is set to 120 seconds.

    • Host: Enter the host name of the LDAP server to use for Digest verification. If you are using multiple LDAP servers for failover capabilities, enter the host name:port value for each server separated by spaces. For example: ldap1.mycompany.com:1050 ldap2.mycompany.com:1050

      See Oracle Fusion Middleware Securing Oracle WebLogic Server for more information about configuring failover.

    • Port: Enter the port number of the LDAP server.

    • SSL Enabled: Select this option if you are using SSL to communicate unencrypted passwords between Oracle WebLogic Communication Services and the LDAP Server.

    • Principal: Enter the name of a principal that Oracle WebLogic Communication Services uses to access the LDAP server (for example, orclApplicationCommonName=WLSSInstance1,cn=WLSS,cn=Products,cn=OracleContext,dc=example,dc=com).

    • Credential and Please type again to confirm: Enter the credential for the above principal name (generally a password).

    • OIDSupportEnabled: Select this checkbox if you are using Oracle Internet Directory as your LDAP provider. This checkbox is necessary when using a precalculated hash value because Oracle Internet Directory prefixes the hash value with {SASL/MD5} as described in RFC 2307. Other LDAP providers may omit the prefix.

  11. Click Save to save your changes.

  12. Select the Performance tab in the right pane.

  13. On the Performance page, enter the caching and connection information into the fields as follows:

    • LDAP Connection Pool Size: Enter the number of connections to use for connecting to the LDAP Server. This value should be equal to or less than the total number of execute threads configured for Oracle WebLogic Communication Services. To view the current number of configured threads, right-click on the Oracle WebLogic Communication Services name in the left pane of the Administration Console and select View Execute Queues; the SIP Container uses the Thread Count value of the queue named sip.transport.Default. The default value of LDAP Connection Pool Size is 10.

      Note that stale connections (for example, LDAP connections that are timed out by a load balancer) are automatically removed from the connection pool.

    • Cache Enabled: Specifies whether a cache should be used with the associated LDAP server.

    • Cache Size: Specifies the size of the cache, in Kilobytes, used to store results from the LDAP server. By default the cache size is 32K.

    • Cache TTL: Specifies the time-to-live (TTL) value, in seconds, for the LDAP cache. By default the TTL value is 60 seconds.

    • Results Time Limit: Specifies the number of milliseconds to wait for LDAP results before timing out. Accept the default value of 0 to specify no time limit.

    • Connect Timeout: Specifies the number of milliseconds to wait for an LDAP connection to be established. If the time is exceeded, the connection times out. The default value of 0 specifies no timeout value.

    • Parallel Connect Delay: Specifies the number of seconds to delay before making concurrent connections to multiple, configured LDAP servers. If this value is set to 0, the provider connects to multiple servers in a serial fashion. The provider first tries to connect to the first configured LDAP server in the Host list. If that connection attempt fails, the provider tries the next configured server, and so on.

      If this value is set to a non-zero value, the provider waits the specified number of seconds before spawning a new thread for an additional connection attempt. For example, if the value is set to 2, the provider first tries to connect to the first configured LDAP server in the Host list. After 2 seconds, if the connection has not yet been established, the provider spawns a new thread and tries to connect to the second server configured in the Host list, and so on for each configured LDAP server.

    • Connection Retry Limit: Specifies the number of times the provider tries to reestablish a connection to an LDAP server if the LDAP server throws an exception while creating a connection.

  14. Click Save to save your changes.

5.7.4.4.2 Configure an RDBMS Digest Identity Asserter Provider

Follow these instructions to create a new RDBMS Digest Identity Asserter Provider:

  1. Log in to the Administration Console for the Oracle WebLogic Communication Services domain you want to configure.

  2. Click Lock & Edit to obtain a configuration lock.

  3. In the left pane of the Console, select the Security Realms node.

  4. Select the name of your security realm in the right pane of the Console. (for example, myrealm).

  5. Select the Providers > Authentication tab.

  6. Click New.

  7. Enter a name for the new provider, and select DBMSDigestIdentityAsserter as the type.

  8. Click OK.

  9. Select the name of the new provider from the list of providers.

  10. Select the Configuration > Provider Specific tab in the right pane.

  11. In the configuration tab, enter RDBMS server and Digest authentication information into the fields as follows:

    • Data Source Name: Enter the name of the JDBC DataSource used to access the password information.

    • SQLGet Users Password: Enter the SQL statement used to obtain the password or hash value from the database. The SQL statement must return a single record result set.

    • SQLList Member Groups: Enter a SQL statement to obtain the group information from a specified username. The username is supplied as a variable to the SQL statement, as in SELECT G_NAME FROM groupmembers WHERE G_MEMBER = ?.

    • Password Encryption Type: Select the format in which the password is stored: PLAINTEXT, PRECALCULATEDHASH, or REVERSIBLEENCRYPTED.

    • Encryption Algorithm: If you have stored encrypted passwords, enter the encryption algorithm that the Digest identity assertion provider will use for reverse encryption.

    • Encryption Key and Please type again to confirm: If you have stored encrypted passwords, enter the base-64 encrypted key used as part of the reverse encryption algorithm.

    • Encryption Init Vector and Please type again to confirm: If you have stored encrypted passwords, enter the base-64 encrypted init vector string used as part of the reverse encryption algorithm.

    • Digest Realm Name: Enter the realm name to use for Digest authentication.

    • Digest Algorithm: Select either MD5 or MD5-sess as the algorithm to use for encrypting Digests.

    • Digest Timeout: This value defines the nonce timeout value for the digest challenge. If the nonce timeout is reached before the client responds, the client is re-challenged with a new nonce. By default, the Digest Timeout is set to 120 seconds.

  12. Click Save to save your changes.

5.7.5 Sample Digest Authentication Configuration Using Embedded LDAP

You can use Oracle WebLogic Communication Services's embedded LDAP implementation for Digest authentication in a test or demo environment. Because you cannot change the schema of the embedded LDAP store, you must store password information in the existing "description" field.

To use the embedded LDAP store for Digest authentication, follow the instructions in the sections that follow.

5.7.5.1 Store User Password Information in the Description Field

To create new users with password information in the existing "description" field:

  1. Log in to the Administration Console for the Oracle WebLogic Communication Services domain you want to configure.

  2. In the left pane of the Console, select the Security Realms node.

  3. Select the name of your security realm in the right pane of the Console. (for example, myrealm).

  4. Select the Users and Groups > Users tab.

  5. Click New.

  6. Enter a name for the new user in the Name field.

  7. Enter the Digest password information for the user in the Description field. The password information can be either the clear-text password, a pre-calculated hash value, or a reverse-encrypted password.

  8. Enter an 8-character password in the Password and Confirm Password fields. You cannot proceed without adding a standard password entry.

  9. Click OK.

5.7.5.2 Set the Embedded LDAP Password

Follow these instructions to set the password for the embedded LDAP store to a known password. You will use this password when configuring the Digest Identity Asserter provider as described in Section 5.7.4.4.1, "Configure an LDAP Digest Identity Asserter Provider":

  1. Log in to the Administration Console for the Oracle WebLogic Communication Services domain you want to configure.

  2. In the left pane, click the name of the domain you are configuring (for example, mydomain).

  3. Select Security > Embedded LDAP in the right pane.

  4. Enter the password you would like to use in the Credential and Confirm Credential fields.

  5. Click Save.

  6. Reboot the server.

5.7.5.3 Configure the Digest Identity Asserter Provider

Example 5-1 shows the security provider configuration in config.xml for a domain that uses LDAP implementation embedded in Oracle WebLogic Communication Services. Note that such a configuration is recommended only for testing or development purposes. Example 5-1 highlights values that you must define when configuring the provider using the instructions in Section 5.7.4.4.1, "Configure an LDAP Digest Identity Asserter Provider".

Example 5-1 Sample Security Provider Configuration with Embedded LDAP

<sec:authentication-provider xmlns:ext="http://www.bea.com/ns/weblogic/90/security/extension" xsi:type="ext:ldap-digest-identity-asserterType">
        <sec:name>myrealmLdapDigestIdentityAsserter</sec:name>
        <ext:user-base-dn>ou=people, ou=myrealm, dc=mydomain</ext:user-base-dn>
        <ext:credential-attribute-name>description</ext:credential-attribute-name>
        <ext:digest-realm-name>wlss.oracle.com</ext:digest-realm-name>
        <ext:host>myserver.mycompany.com</ext:host>
        <ext:port>7001</ext:port>
        <ext:principal>cn=Admin</ext:principal>
      </sec:authentication-provider>

5.8 Configuring Client-Cert Authentication

Client-Cert authentication uses a certificate or other custom tokens in order to authenticate a user. The token is "mapped" to a user present in the Oracle WebLogic Communication Services security realm in which the Servlet is deployed. SIP Servlets that want to use Client-Cert authentication must set the auth-method element to CLIENT-CERT in their sip.xml deployment descriptor.

The token used for Client-Cert authentication can be obtained in several different ways:

SIP Servlets can also use the CLIENT-CERT auth-method to implement perimeter authentication. Perimeter authentication uses custom token names and values, along with a custom security provider, to authenticate clients. See Section 5.8.3, "Supporting Perimeter Authentication with a Custom IA Provider" for a summary of steps required to implement perimeter authentication.

5.8.1 Configuring SSL and X509 for Oracle WebLogic Communication Services

Oracle WebLogic Communication Services includes two separate Identity Assertion providers that can be used with X509 certificates. The LDAP X509 Identity Asserter provider receives an X509 certificate, looks up the LDAP object for the user associated with that certificate in a separate LDAP store, ensures that the certificate in the LDAP object matches the presented certificate, and then retrieves the name of the user from the LDAP object. The Default Identity Asserter provider maps the user according to its configuration, but does not validate the certificate.

With either provider, Oracle WebLogic Communication Services uses two-way SSL to verify the digital certificate supplied by the client. You must ensure that a SIPS transport (SSL) has been configured in order to use Client-Cert authentication. See Managing Oracle WebLogic Communication Services Network Resources in Configuring Network Resources if you have not yet configured a secure transport.

See Section 5.8.1.1, "Configuring the Default Identity Asserter" to configure the Default Identity Asserter provider. In most production installations you will have a separate LDAP store and will need to configure the LDAP X509 Identity Asserter provider to use client-cert authentication; see Section 5.8.1.2, "Configuring the LDAP X509 Identity Asserter".

5.8.1.1 Configuring the Default Identity Asserter

The Default Identity Asserter can be configured to verify an X509 certificate passed to it by a client over a secure (SSL) connection. The Default Identity Asserter requires a separate user name mapper to map the associated client "certificate" to a user configured in the default security realm. You can use the default user name mapper installed with Oracle WebLogic Communication Services, or you can create a custom user name mapper class as described in Oracle Fusion Middleware Securing Oracle WebLogic Server.

Follow these instructions to configure the Default Identity Asserter:

  1. Log in to the Administration Console for the Oracle WebLogic Communication Services domain you want to configure.

  2. In the left pane of the Console, select the Security Realms node.

  3. Select the name of your security realm in the right pane of the Console. (for example, myrealm).

  4. Select the Providers > Authentication tab.

  5. In the right pane of the Console, select DefaultIdentityAsserter from the table of configured providers.

  6. On the Configuration > Common page, select X.509 in the Available column of the Active Types table and use the arrow to move it to the Chosen column.

  7. Click Save to apply the change.

  8. You can use either a custom Java class to map names in the X509 certificate to usernames in the built-in LDAP store, or you can use the default user name mapper. To specify a custom Java class to perform user name mapping:

    1. Select the Configuration > Provider Specific tab.

    2. Enter the name of the custom class in the User Name Mapper Class Name field.

    3. Click Save.

    To use the default user name mapper:

    1. Select the Configuration > Provider Specific tab.

    2. Select Use Default User Name Mapper.

    3. In the Default User Name Mapper Attribute Type list, select either CN (for Common Name) or E (for Email address) depending on the user name attribute you have stored in the security realm.

    4. In the Default User Name Mapper Attribute Delimiter field, accept the default delimiter of "@". This delimiter is used with the E (Email address) attribute type to extract the email portion from the client token. For example, a token of "joe@mycompany.com" would be mapped to a username "joe" configured in the default security realm.

    5. Click Save.

5.8.1.2 Configuring the LDAP X509 Identity Asserter

Follow these steps to create and configure the X509 Authentication Provider.

  1. Log in to the Administration Console for the Oracle WebLogic Communication Services domain you want to configure.

  2. In the left pane of the Console, select the Security Realms node.

  3. Select the name of your security realm in the right pane of the Console. (for example, myrealm).

  4. Select the Providers > Authentication tab.

  5. Click New.

  6. Enter a name for the new provider, and select LDAPX509IdentityAsserter as the type.

  7. Click OK.

  8. In the list of providers, select the name of the provider you just created.

  9. In the Configuration > Provider Specific tab, enter LDAP server information into the fields as follows:

    • User Field Attributes: Enter an LDAP search filter that Oracle WebLogic Communication Services will use to locate a given username. The filter is applied to LDAP objects beneath the base DN defined in the Certificate Mapping attribute described below.

    • User Name Attribute: Enter the LDAP attribute that stores the user's name.

    • Certificate Attribute: Enter the LDAP attribute that stores the certificate for the user name.

    • Certificate Mapping: Specify how a query string to construct the base LDAP DN used to locate the LDAP object for the user.

    • Host: Enter the host name of the LDAP server to verify the incoming certificate. If you are using multiple LDAP servers for failover capabilities, enter the host name:port value for each server separated by spaces. For example: ldap1.mycompany.com:1050 ldap2.mycompany.com:1050

      See Oracle Fusion Middleware Securing Oracle WebLogic Server for more information about configuring failover.

    • Port: Enter the port number of the LDAP server.

    • SSL Enabled: Select this option if you are using SSL to communicate unencrypted passwords between Oracle WebLogic Communication Services and the LDAP Server.

    • Principal: Enter the name of a principal that Oracle WebLogic Communication Services uses to access the LDAP server.

    • Credential: Enter the credential for the above principal name (generally a password).

    • Confirm Credential: Re-enter the principal's credential.

    • Cache Enabled: Specifies whether a cache should be used with the associated LDAP server.

    • Cache Size: Specifies the size of the cache, in Kilobytes, used to store results from the LDAP server. By default the cache size is 32K.

    • Cache TTL: Specifies the time-to-live (TTL) value, in seconds, for the LDAP cache. By default the TTL value is 60 seconds.

    • Follow Referrals: Select this to specify that a search for a user or group within the LDAP X509 Identity Assertion provider should follow referrals to other LDAP servers or branches within the LDAP directory.

    • Bind Anonymously On Referrals: By default, the LDAP X509 Identity Assertion provider uses the same DN and password used to connect to the LDAP server when following referrals during a search. If you want to connect as an anonymous user, check this box.

    • Results Time Limit: Specifies the number of milliseconds to wait for LDAP results before timing out. Accept the default value of 0 to specify no time limit.

    • Connect Timeout: Specifies the number of milliseconds to wait for an LDAP connection to be established. If the time is exceeded, the connection times out. The default value of 0 specifies no timeout value.

    • Parallel Connect Delay: Specifies the number of seconds to delay before making concurrent connections to multiple, configured LDAP servers. If this value is set to 0, the provider connects to multiple servers in a serial fashion. The provider first tries to connect to the first configured LDAP server in the Host list. If that connection attempt fails, the provider tries the next configured server, and so on.

      If this value is set to a non-zero value, the provider waits the specified number of seconds before spawning a new thread for an additional connection attempt. For example, if the value is set to 2, the provider first tries to connect to the first configured LDAP server in the Host list. After 2 seconds, if the connection has not yet been established, the provider spawns a new thread and tries to connect to the second server configured in the Host list, and so on for each configured LDAP server.

    • Connection Retry Limit: Specifies the number of times the provider tries to reestablish a connection to an LDAP server if the LDAP server throws an exception while creating a connection.

  10. Click Save to save your changes.

  11. Reboot the server to realize the changed security configuration.

5.8.2 Configuring Oracle WebLogic Communication Services to Use WL-Proxy-Client-Cert

In order for Oracle WebLogic Communication Services to use the WL-Proxy-Client-Cert header, a proxy server or load balancer must first transmit the X509 certificate for a client request, encrypt it using base-64 encoding, and then add the resulting token WL-Proxy-Client-Cert header in the SIP message. If your system is configured in this way, you can enable the local Oracle WebLogic Communication Services instance (or individual SIP Servlet instances) to examine the WL-Proxy-Client-Cert header for client tokens.

To configure the server instance to use the WL-Proxy-Client-Cert header:

  1. Log in to the Administration Console for the Oracle WebLogic Communication Services domain you want to configure.

  2. In the left pane, select the Environment > Servers node.

  3. Select the name of a configured engine tier server.

  4. Select the Configuration > General tab in the right pane.

  5. Select Client Cert Proxy Enabled.

  6. Click Save to save your changes.

  7. Follow the instructions under Section 5.8.1, "Configuring SSL and X509 for Oracle WebLogic Communication Services" to configure either the default identity asserter or the LDAP Identity Asserter provider to manage X509 certificates.

  8. Reboot the server to realize the changed configuration.

To enable the WL-Proxy-Client-Cert header for an individual Web Application, set the com.bea.wcp.clientCertProxyEnabled context parameter to true in the application's sip.xml deployment descriptor.

5.8.3 Supporting Perimeter Authentication with a Custom IA Provider

With perimeter authentication, a system outside of WebLogic Server establishes trust via tokens. The system is generally comprised of an authentication agent that creates an artifact or token that must be presented to determine information about the authenticated user at a later time. The actual format of the token varies from vendor to vendor (for example, SAML or SPNEGO).

Oracle WebLogic Communication Services supports perimeter authentication through the use of an Identity Assertion provider designed to recognize one or more token formats. When the authentication type of a SIP Servlet is set to CLIENT-CERT, the SIP container in Oracle WebLogic Communication Services performs identity assertion on values from the request headers. If the header name matches the active token type for a configured provider, the value is passed to the provider for identity assertion.

The provider can then use a user name mapper to resolve the certificate to a user available in the security realm. The user corresponding to the Subject's Distinguished Name (SubjectDN) attribute in the client's digital certificate must be defined in the server's security realm; otherwise the client will not be allowed to access a protected WebLogic resource.

If you want to use custom tokens to pass client certificates for perimeter authentication, you must create and configure a custom Identity Assertion provider in place of the LDAP X509 or Default Identity Asserter providers described above. See Oracle Fusion Middleware Securing Oracle WebLogic Server for information about creating providers for handling tokens passed with perimeter authentication.

5.9 Configuring SIP Servlet Identity Assertion Mechanisms

A SIP Servlet can be configured to use one of the following identity assertion mechanisms:

The selected identity assertion mechanism is defined in the identity-assertion element of the sip.xml deployment descriptor. The identity-assertion-support element determines whether the identity assertion mechanism is required for the Servlet, or whether alternate authentication mechanisms can be used with SIP messages that do not contain the required headers. See the SIP Servlet Specification v1.1 for more information on configuring identity assertion for a Servlet.

Oracle WebLogic Communication Services supports identity assertion mechanisms using security providers. The sections that follow describe how Oracle WebLogic Communication Services handles messages with each identity assertion mechanism, and how to configure the required security providers.

Note:

Oracle WebLogic Communication Services version provides backward compatibility for applications that conform to the SIP Servlet v1.0 specification.

5.9.1 Understanding Trusted Host Forwarding with P-Asserted-Identity

The P-Asserted-Identity header is honored only within a trusted domain. In a Oracle WebLogic Communication Services system, trusted domains are purely configuration-based. To enable use of the header, you must configure one of two available P-Asserted Identity Assertion providers as described in Section 5.9.3, "Configuring a P-Asserted-Identity Assertion Provider". The P-Asserted-Identity assertion providers expose the trusted domain configuration for P-Asserted-Identity headers. If you do not configure a provider, the header considers no IP addresses as being "trusted."

When Oracle WebLogic Communication Services receives a message having the P-Asserted-Identity header from a trusted host configured with the provider, it logs in the user specified in the header to determine group membership and other privileges. The value contained in the P-Asserted-Identity header must be a SIP address (for example, sipuser@oracle.com). By default, Oracle WebLogic Communication Services removes the domain portion of the address (@oracle.com) and uses the remainder as the user name. If you must support overlapping usernames from different names (for example, sipuser@oracle.com and sipuser@cea.com), you can create and use a custom user-name mapper to process the header contents into a unique username (for example, sipsuser_b and sipuser_c). Using a custom user name mapper also enables you to support WebLogic user names that contain an "@" character, such as @oracle.com.

The presence of a P-Asserted-Identity header combined with the Privacy header also determines the way in which Oracle WebLogic Communication Services proxies incoming requests. The value of the identity-assertion-support element in sip.xml is also considered. Figure 5-3 describes how incoming SIP requests are managed in relation to the P-Asserted-Identity header.

Figure 5-3 Managing Inbound Requests Having P-Asserted-Identity and Privacy Headers

Description of Figure 5-3 follows
Description of "Figure 5-3 Managing Inbound Requests Having P-Asserted-Identity and Privacy Headers"

Figure 5-4 describes the standard security check procedure that Oracle WebLogic Communication Services uses when an asserted user name is not authorized to access a requested resource. The standard security check is performed according to the auth-method defined in the login-config element of the sip.xml descriptor for the current application.

Figure 5-4 Standard Security Check Procedure

Description of Figure 5-4 follows
Description of "Figure 5-4 Standard Security Check Procedure"

The presence of a P-Asserted-Identity header or a P-Preferred-Identity header also affects the processing of outbound SIP requests. Figure 5-5 describes the behavior.

Figure 5-5 Managing Outbound Requests Having P-Asserted-Identity or P-Preferred Identity

Description of Figure 5-5 follows
Description of "Figure 5-5 Managing Outbound Requests Having P-Asserted-Identity or P-Preferred Identity"

5.9.2 Overview of Strict and Non-Strict P-Asserted-Identity Asserter Providers

If the contents of a P-Asserted-Identity header are invalid, or if the header is received from a non-trusted host, then the security provider returns an "anonymous" user to the SIP Servlet container. If you configured the PAsserted Identity Strict Asserter provider, an exception is also thrown so that you can audit the substitution of the anonymous user. (If you configured the basic PAsserted Identity Asserter provider, no exception is thrown.)

With either provider, if identity assertion fails and the requested resource is protected (the request matches a security-constraint defined in sip.xml), the SIP container uses the auth-method defined in the sip.xml deployment descriptor to challenge the end user. For example, digest authentication may be used if the Servlet specifies the digest authentication method.

If the requested resource is not protected, the anonymous user is simply passed to the SIP Servlet without authorization. Because the 3GPP TS 24.229 specification recommends forced authorization even when a resource is unrestricted (and privacy is not requested), you should use declarative security to protect all of a SIP Servlet's resources to remain compliant with the specification.

If authorization of the anonymous user fails, Oracle WebLogic Communication Services then forces authentication by challenging the user.

5.9.3 Configuring a P-Asserted-Identity Assertion Provider

Follow these steps to configure a security provider used to support the P-Asserted-Identity header. Note that one of two providers can be selected, as described in Section 5.9.2, "Overview of Strict and Non-Strict P-Asserted-Identity Asserter Providers".

In addition to configuring one of the above providers, configure a secondary, "fallback" login method (for example, using DIGEST or CLIENT-CERT authentication).

To configure a P-Asserted-Identity provider:

  1. Log in to the Administration Console for the Oracle WebLogic Communication Services domain you want to configure.

  2. In the left pane of the Console, select the Security Realms node.

  3. Select the name of your security realm in the right pane of the Console. (for example, myrealm).

  4. Click New.

  5. Enter a name for the new provider, and select one of the following options for the Type:

    • PAssertedIdentityAsserter—Select this option to configure a provider that does not throw an exception when the P-Asserted-Identity header is invalid or is received from a non-trusted host and an anonymous user is substituted.

    • PAssertedIdentityStrictAsserter—Select this option to configure a provider that throws an exception when the P-Asserted-Identity header is invalid or is received from a non-trusted host and an anonymous user is substituted.

    See Section 5.9.2, "Overview of Strict and Non-Strict P-Asserted-Identity Asserter Providers" for more information.

  6. Click OK.

  7. Select the name of the provider you just created.

  8. Select the Configuration > Provider Specific tab.

  9. Fill in the fields of the configuration tab as follows:

    • Trusted Hosts: Enter one or more host names that the provider will treat as trusted hosts. You can enter a list of IP addresses or DNS names, and wildcards are supported.

      Note:

      The provider does not use trusted hosts configured in the sipserver.xml file.
    • User Name Mapper Class Name: Enter the name of a custom Java class used to map user names in the P-Asserted-Identity header to user names in the default security realm. A custom user name mapper is generally used if user names are received from two or more different domains. In this case additional logic may be required to map usernames received from each domain. A custom user name mapper class is required if you want to map usernames in the P-Asserted-Identity header to WebLogic usernames. See Oracle Fusion Middleware Securing Oracle WebLogic Server for more information.

      Alternately, leave this field blank to use the default user name mapper. The default mapper simply discards the domain name and takes the resulting user name without applying any additional logic.

  10. Click Save.

5.9.4 Understanding Identity Assertion with the Identity and Identity-Info Headers

Oracle WebLogic Communication Services can also perform identity assertion using the Identity and Identity-Info headers, as described in RFC 4474. As with the p-asserted-identity assertion mechanism, Identity header assertion requires that you first configure the appropriate security provider (the IdentityHeaderAsserter provider) in Oracle WebLogic Communication Services.

When asserting the identity of inbound requests having the Identity and Identity-Info headers, Oracle WebLogic Communication Services considers the values of the identity-assertion and identity-assertion-support elements in sip.xml as well as the presence of a configured security provider. Figure 5-6 describes how incoming messages are processed using this assertion mechanism.

Figure 5-6 Managing Inbound Requests Having Identity and Identity-Info Headers

Description of Figure 5-6 follows
Description of "Figure 5-6 Managing Inbound Requests Having Identity and Identity-Info Headers"

5.9.5 Configuring the Identity Header Assertion Provider

Follow these steps to configure the security provider used to support the Identity header:

  1. Log in to the Administration Console for the Oracle WebLogic Communication Services domain you want to configure.

  2. In the left pane of the Console, select the Security Realms node.

  3. Select the name of your security realm in the right pane of the Console. (for example, myrealm).

  4. Click the Providers > Authentication tab in the right pane.

  5. Click New.

  6. Enter a name for the new provider, and select IdentityHeaderAsserter for the Type.

  7. Click OK.

  8. Select the name of the provider you just created.

  9. Select the Provider Specific tab.

  10. Fill in the fields of the configuration tab as follows:

    • Date Period: Enter the valid period for Date header, in seconds.

    • Https Channel Name: Enter the name of an HTTPS channel the provider should use to initialize an HTTPS client. An HTTPS channel is required (and must be configured separately) if a remote certificate must be retrieved via HTTPS.

    • User Name Mapper Class Name (optional): Enter the name of a custom Java class used to map user names in the Identity header to user names in the default security realm. A custom user name mapper class is required if you want to map usernames in the Identity header to WebLogic usernames. See Oracle Fusion Middleware Securing Oracle WebLogic Server for more information.

  11. Click Save.

5.10 Configuring 3GPP HTTP Identity Assertion Providers

In order to function as an Application Server in an IMS network, Oracle WebLogic Communication Services supports handling the X-3GPP-Asserted-Identity header as specified in 3GPP TS 33.222 Generic Authentication Architecture (GAA); Access to network application functions using Hypertext Transfer Protocol over Transport Layer Security (HTTPS) (http://www.3gpp.org/ftp/Specs/html-info/33222.htm). Oracle WebLogic Communication Services provides this support via a configured security provider, X3gppAssertedIdentityAsserter or X3gppAssertedIdentityStrictAsserter. The providers use the same authentication process, but the "strict" assertion provider also throws an exception when the header is received from a non-trusted host (which enables you to audit asserted identity requests from non-trusted hosts).

The X-3GPP-Asserted-Identity header functions for HTTP requests in the same manner that the P-Asserted-Identity header functions for SIP requests. When the container receives an incoming HTTP requesting having a X-3GPP-Asserted-Identity header, it first verifies that the request was received from a trusted host. If the host was trusted, the container asserts the user's identity using the information in the header, authenticates the user, and logs the user in if that user is authorized to access the requested resource. (If a request comes from a non-trusted host, the container simply ignores the header.)

The X-3GPP-Asserted-Identity header may contain multiple names in a list (for example, user1@oracle.com, user2@oracle.com). When configured with the default user name mapper class, the Oracle WebLogic Communication Services providers remove the domain portion of the addresses (@oracle.com) and use the remainder as the user name. The default user name mapper always chooses the first username in the list and uses it for asserting the identity. This behavior can be changed by creating and configuring a custom user name mapper class. For example, if you must support overlapping usernames from different names (for example, sipuser@oracle.com and sipuser@cea.com), a custom user-name mapper might process the header contents into a unique username (for example, sipsuser_b and sipuser_c). Using a custom user name mapper also enables you to support WebLogic user names that contain an "@" character, such as @oracle.com.

In order for SIP Servlets to support authentication with the X-3GPP-Asserted-Identity header, the auth-method element must be set to CLIENT-CERT in the web.xml deployment descriptor. See Oracle Fusion Middleware Securing Oracle WebLogic Server for more information.

5.10.1 Configuring a X-3GPP-Asserted-Identity Provider

Follow these steps to configure a security provider used to support the X-3GPP-Asserted-Identity header in HTTP requests. Note that one of two providers can be selected, as described in the Section 5.10, "Configuring 3GPP HTTP Identity Assertion Providers":

  1. Log in to the Administration Console for the Oracle WebLogic Communication Services domain you want to configure.

  2. In the left pane of the Console, select the Security Realms node.

  3. Select the name of your security realm in the right pane of the Console. (for example, myrealm).

  4. Select the Providers > Authentication tab.

  5. Click New.

  6. Enter a name for the new provider, and select one of the following options for the Type field:

    • X3gppAssertedIdentityAsserter—Select this option to configure a provider that does not throw an exception when the header is invalid or is received from a non-trusted host.

    • X3gppAssertedIdentityStrictAsserter—Select this option to configure a provider that throws an exception when the header is received from a non-trusted host and is therefore ignored.

    See Section 5.10, "Configuring 3GPP HTTP Identity Assertion Providers" for more information.

  7. Click OK.

  8. Select the name of the new provider you just created.

  9. In the Active Types Chooser list, select the X-3GPP-Asserted-Identity type and use the arrow to move it to the Chosen column.

  10. Click Save.

  11. Select the Configuration > Provider Specific tab.

  12. Fill in the fields of the configuration page as follows:

    • Trusted Hosts: Enter one or more host names that the provider will treat as trusted hosts. Note that the provider does not use trusted hosts configured in the sipserver.xml file (see sip-security in the Configuration Reference Manual.) You can enter a list of IP addresses or DNS names, and wildcards are supported.

    • User Name Mapper Class Name: Enter the name of a custom Java class used to map user names in the X-3GPP-Asserted-Identity header to user names in the default security realm. A custom user name mapper is generally used if user names are received from two or more different domains. In this case additional logic may be required to map user names received from each domain. A custom user name mapper class is required if you want to map usernames to WebLogic usernames, or if you want to logically process multiple usernames specified in the X-3GPP-Asserted-Identity header (rather than using only the first username). See Oracle Fusion Middleware Securing Oracle WebLogic Server for more information.

      Alternately, leave this field blank to use the default user name mapper. The default mapper simply discards the domain name and takes the first resulting user name to assert the identity. For example, the default user name mapper takes the following header:

      X-3GPP-Asserted-Identity: "user1@oracle.com", "user2@oracle.com"
      

      and asserts the identity "user1."

  13. Click Save.

5.11 Configuring Basic Authentication for HTTP Servlets

Although Basic authentication is deprecated for use with SIP Servlets, you may choose to use this authentication mechanism with HTTP Servlets. Basic authentication is supported via the LDAPAuthenticator provider. Follow these steps to configure the provider with Oracle Internet Directory:

  1. Log in to the Administration Console for the Oracle WebLogic Communication Services domain you want to configure.

  2. In the left pane of the Console, select the Security Realms node.

  3. Select the name of your security realm in the right pane of the Console. (for example, myrealm).

  4. Select the Providers > Authentication tab.

  5. Click New.

  6. Enter a name for the new provider, and select LDAPAuthenticator for the Type field.

  7. Click OK.

  8. Select the name of the new provider you just created.

  9. Select the Configuration > Provider Specific tab.

  10. Fill in the fields of the configuration page as follows:

    • Principal: Enter the application instance that was configured for Oracle WebLogic Communication Services in Oracle Internet Directory (for example, orclApplicationCommonName=WLSSInstance1,cn=WLSS,cn=Products,cn=OracleContext,dc=example,dc=com). Note that you must provision this instance manually after installing Oracle Internet Directory. See Section 5.12, "Provisioning Resources in Oracle Internet Directory" for instructions.

    • Credential: Enter the password of the Principal that was configured in Oracle Internet Directory.

    • Group Base DN: Enter the DN of the Groups object in Oracle Internet Directory (for example, cn=groups,dc=example,dc=com).

    • User Base DN: Enter the DN of the Users object in Oracle Internet Directory (for example, cn=Users,dc=example,dc=com).

  11. Click Save.

5.12 Provisioning Resources in Oracle Internet Directory

The following sections provide an overview of how to provision Oracle WebLogic Communication Services resources when using Oracle Internet Directory as your LDAP provider. These instructions are necessary when using Digest Authentication with a precalculated hash value, or when configuring Basic authentication for HTTP Servlets.

See the Oracle Fusion Middleware Administrator's Guide for Oracle Internet Directory for more details about these procedures.

5.12.1 Configuring Oracle Internet Directory

You must configure the following mappings for the OID LDAP backend:

  • JAAS Usernames to LDAP User Entries--JAAS (Java Authentication and Authorization Service) user names are mapped to LDAP Users based on value of the orclcommonnicknameattribute under the node cn=Common,cn=Products,cn=OracleContext. For example, setting this attribute to uid implies that users authenticating against OID must provide their corresponding LDAP uid as their username during authentication. The rest of the configuration described in this chapter assumes that the orclcommonnicknameattribute is set to uid (default value).

  • JAAS Realms to LDAP Subscribers--JAAS realms are mapped to LDAP Realm entries based on the value given to orclsubscribernicknameattribute under the root cn=Common,cn=Products,cn=OracleContext node for an OID deployment. For example, setting the value of orclsubscribernicknameattribute to o (the letter "o") for an OID deployment implies that users authenticating against OID must belong to the JAAS realm identified by the value of the o attribute. Set the value of orclsubscribernicknameattribute to o.

  • JAAS Roles to LDAP Groups--Group membership determines the JAAS roles for a specific user. Mapping LDAP groups to JAAS roles is based on the value given to orclcommonnamingattribute under the node cn=Common,cn=Products,cn=OracleContext for each of the provisioned LDAP Realms. For example, if a user belongs to an LDAP group with the distinguished name of cn=Location Service, cn=groups, dc=example, dc=com and the orclcommonnamingattribute is set to cn, then that JAAS user is populated with the "Location Service" JAAS role. Set the value of orclcommonnamingattribute to cn

5.12.2 Configuring Static Verifiers

After configuring Oracle Internet Directory as described above, you must create a new product entry for Oracle WebLogic Communication Services (OWLCS), install the static verifier, create entries for each instance of OWLCS, and grant verifier privileges to each new instance created. You must perform these steps before provisioning users in OID. If users already exist in OID, after creating and configuring the static verifier, users must reset their passwords before they can login successfully.

5.12.2.1 Add Oracle WebLogic Communication Services

To add the Oracle WebLogic Communication Services product to Oracle Internet Directory:

  1. Start the oidadmin tool in $ORACLE_HOME/bin/ and connect to the installed Oracle Internet Directory server. Login using "orcladmin" account and the password you chose during your installation of Oracle Internet Directory.

  2. Browse the Entry Management tree to find:

    cn=Products,cn=OracleContext,dc=example,dc=com. The exact domain part (dc=example,dc=com) will depend on the domain that you created when you installed Oracle Internet Directory

  3. A convenient way to create a new entry for OWLCS is to clone an existing product entry. Select the first entry under Products (this is generally the "Calendar" entry) and right-click on the Calendar entry and choose "Create Like". In the resulting dialog:

    Replace "Calendar" entry in dn with WLCS.

    Enter WLCS for cn

  4. Click OK.

  5. Select the Products entry, right-click and choose "Refresh SubTree Entries" and make sure that a new product with name WLCS shows up under Products.

5.12.2.2 Install the Static Verifier

Use the ldapadd command-line tool to install the static verifier, as follows:

  1. Set the environmental variable ORACLE_HOME to point to the ORACLE_HOME of your OID installation

  2. Create an ldif file containing the following lines (again replace the domain parts with your domain):

    dn: cn=WLCSVerifierProfileEntry,cn=WLCS,cn=Products,cn=OracleContext,dc=example,dc=com

    objectclass:top

    objectclass:orclpwdverifierprofile

    cn:WLCSVerifierProfileEntry

    orclappid:wlcs

    orclpwdverifierparams;authpassword: crypto:SASL/MD5 $ realm:example.com $ usernameattribute:uid

  3. cd $ORACLE_HOME

  4. Run the command ./bin/ldapadd -D cn=orcladmin -w <password of orcladmin user> -f <yourfile>.ldif

  5. In oidadmin, refresh the WLCS product entry (by right-clicking on entry and choosing "Refresh SubTree Entries"). The WLCSVerifierProfileEntry should appear

5.12.3 Add a New Oracle WebLogic Communication Services

To add a new Oracle WebLogic Communication Services Instance:

  1. Select the WLCS product entry you created, right-click and choose Create.

  2. In the Distinguished Name (dn) field enter

    orclApplicationCommonName=WLCSInstance1,cn=WLCS,cn=Products,cn=OracleContext,dc=example,dc=com" (replacing the domain part with your domain)
    
  3. Under Object Classes, click Add.

  4. Select the "orclApplicationEntity". Click Select.

  5. Click on the Optional Properties and populate the values of the following attributes:

    userpassword (not authpassword) - enter any password of your choice

    orclappfullname - enter "Oracle Weblogic Communication Services"

    description - enter "Entry for Oracle Weblogic Communication Services Instance"

  6. Click OK.

  7. Refresh the WLCS product by right-clicking the entry and choosing "Refresh SubTree Entries" and make sure that you see the new entry you just created

5.12.4 Grant Verifier Privileges to the Oracle WebLogic Communication Services Instance

To grant Verifier Privileges to the Oracle WebLogic Communication Services Instance:

  1. Navigate to: cn=verifierServices,cn=Groups,cn=OracleContext,dc=example,dc=com entry (replacing the domain part with your domain).

  2. Click cn=verifierServices

  3. In the right pane, scroll down to the uniquemember attribute. You might see an entry or two for the value of the attribute. Add "orclApplicationCommonName=WLCSInstance1,cn=WLCS,cn=Products,cn=OracleContext,dc=example,dc=com" (replacing the domain part with your domain)to the existing value of uniquemember attribute.

  4. Click Apply.

  5. Repeat above two steps for each instance of OWLCS

    For each instance of OWLCS that needs to communicate with OID, you need to repeat the above two steps (Adding a new OWLCS instance and granting verifier privileges to the instance)

5.13 Provisioning Users

To provision users, you have to first create a user, set required attributes for the user, create a group, and assign the new user to be a member of the group by doing the following:

5.13.1 Create a New User

See the OID manual for administrating users via oiddas.

Alternatively, if you want to quickly create one test user you can use the oidadmin and clone the orcladmin user as follows:# Navigate to cn=Users,dc=example,dc=com (replacing the domain part with your domain)

  1. Right-click on cn=orcladmin and choose Create Like.

  2. In the resulting dialog, do the following:

    Change orcladmin in the Distinguised Name attribute value to "test.user1"

    Enter test.user1 for cn

    Enter test.user1 for sn

  3. Click on the "Optional Properties" tab

    Enter test.user1 for givenName

    Enter test.user1@example.com for mail (since this email address will be the user's SIP address also, make sure you enter it in the form username@your-domain)

    Change description to "Test User for OWLCS"

    Change orclSAMAccountName to test.user1

    Enter test.user1 for uid

    Enter a password for this test user of your choice

    Enter true for orclIsVisible property (this is important)

  4. Click OK.

5.13.2 Create a Group

If you want to run the ProxyRegistrar then all users must be members of the 'Location Service' group. That group has to be created, as described below.

The easiest way to add groups and add members to groups is via the OIDDAS web interface. Consult the OID documentation on how to create groups. Alternatively, you can create a new group by cloning an existing group using the oidadmin tool by doing the following:

  1. Browse to Entry Management tree until you get to cn=Groups,dc=example,dc=com (replacing the domain part with your domain)

  2. Right-click on an existing Group (such as "OCS_Portal_Users") and choose Create Like.

  3. Set the Distinguished Name (dn) to cn=Location Service,cn=Groups,dc=example,dc=com (change OCS_Portal_Users to Location Service)

  4. Enter Location Service for cn.

  5. Click on the Optional Properties tab.

  6. For the description, enter "Location Service Role for OWLCS".

  7. Enter Location Service for displayName.

  8. Click OK.

  9. Click on cn=Groups and choose "Refresh SubTree Entries" and make sure you see the new group.

5.13.3 Assign Group Memberships to Users

As already mentioned, if you want to run the ProxyRegistrar then all OWLCS users must be members of the 'Location Service' group created above. To add a user to the new Location Service group, do the following:

  1. Click on the new Location Service group you created. You will find the group in the Entry Management tree at cn=Location Service,cn=Groups,dc=example,dc=com (replace domain part with your domain)

  2. In the pane on your right, scroll down to uniquemember attribute and add cn=test.user1,cn=Users,dc=example,dc=com to any existing entries (replace domain part with your domain).

  3. Click Apply.

5.13.4 Set JAAS Realm for Users

Next you must set the JAAS Realm for users:

  1. Navigate to dc=example,dc=com under Entry Management (replace domain with your domain

  2. Click the dc=example entry.

  3. Click the Advanced radio button.

  4. Select o from the Attribute drop down.

  5. Click on the Apply button.

  6. Enter example.com for the value of the o attribute (replace with your realm).

  7. Click Apply.

5.14 Configuring OWLCS Server Instance

Add an LDAPIdentityAssertionProvider with OID support:

  1. In the WLS Admin Console go to your Security Realm and click the Providers tab.

  2. Delete the DigestIdentityAsserter if you see it in the list of providers (this is created by default for out-of-the-box installation of OWLCS) and restart OWLCS server.

  3. After server restarts, in the WLS Admin Console, click on the Providers tab.

  4. Add a new LDAP Digest Identity Assertion Provider (by clicking the New button and selecting LDAPDigestAssertionProvider from the Type drop-down). Enter LDAPDigestAssertionProvider for name. Click OK.

  5. Click on the Provider Specific tab.

  6. Set the UserBaseDN to "cn=Users,dc=example,dc=com" (replace the domain part with your domain).

  7. Set the CredentialAttributeName to "authpassword;wlcs".

  8. Set the PaswordEncryptionType to PRECALCULATEDHASH.

  9. Set the DigestRealmName to the "example.com" (this should match the realm value in your ldif file used for installing static verifier).

  10. Set Host and Port to those of the OID server.

  11. Set the Principal to "orclApplicationCommonName=WLCSInstance1,cn=WLCS,cn=Products,cn=OracleContext,dc=example,dc=com" (replace domain part with your domain)

  12. Set the Credential to what you configured the userPassword of the instance above. Confirm credential.

  13. Check the "OIDSupportEnabled" checkbox and click Save.

  14. Go back to the Providers tab described in step 1. If there is a DefaultAuthenticator entry there, click it, and set the control flag to SUFFICIENT and click Save.

5.14.1 Add an LDAP Authenticator (Setting Up Roles)

To add an LDAPAuthenticator:

  1. In the WLS Admin Console go to your Security Realm and in the Providers tab, add a new LDAPAuthenticator.

  2. On Common tab, set the Control Flag to SUFFICIENT.

  3. Click the Provider Specific tab.

  4. Set the host and the port of the OID server.

  5. Set Pricipal to "orclApplicationCommonName=WLCSInstance1,cn=WLCS,cn=Products,cn=OracleContext,dc=example,dc=com" (replace domain part with your domain).

  6. Set the Credential to what you configured in an earlier step and Confirm Credential.

  7. Set User Base DN to "cn=Users,dc=example,dc=com" (replace domain part with your domain).

  8. Enable Use Retrieved User Name as Principal.

  9. Set Group Base DN to "cn=Groups,example,dc=com" (replace domain part with your domain).

  10. Click Save.

5.14.2 Improving LDAP Authenticator Performance

You can improve LDAP Authenticator performance:

  • If users are in a flat structure (which is usually the case), set User Search Scope to "onelevel".

  • If the groups for roles are in a flat structure (which is also usually the case), that is, there are no groups in groups, set Group Search Scope to "onelevel", and Set Group Membership Searching to "limited".

Ensure that you save your changes.

5.14.3 Configuring Userservice to work with OID

You must configure Userservice to work with OID:

  1. The ejb-jar.xml packaged in the subscriberdataservices ear file (subscriberdataservices-11.1.1.1.0.ear at $MW_HOME/as11gr1wlcs1/communications/applications)has to be configured to use LDAP instead of jdbc.

  2. Extract the files in the subscriberdataservices ear followed by the files in the userservice jar file.

  3. In ejb-jar.xml under META-INF, comment out the UserServiceDSN, and UserDAOImpl groups. Uncomment the LDAP section, and configure with proper values.

    Set the java.naming.security.principal to orclApplicationCommonName=WLCSInstance1,cn=WLCS,cn=Products,cn=OracleContext,dc=example,dc=com (replace domain part with your domain)

    Set the password defined earlier - for plain text password prepended with a "!". For instance, to set the password to myPassword, configure <env-entry-value><![CDATA[!myPassword]]></env-entry-value>.

    Set the provider LDAP URL. The default port is 389 (non SSL connections).

  4. Save the ejb-jar.xml file with the above changes, repackage the jar file first followed by the ear file. Replace the existing subscriberdataservices ear file under $MW_HOME/as11gr1wlcs1/communications/applications with the modified one.

  5. Restart OWLCS. You should now be able to successfully sign in to OWCLS as test.user1 using Oracle Communicator.