The following sections describe how to configure Oracle Communications Converged Application Server to use Digest authentication with a supported LDAP server or RDBMS:
The following sections provide a basic overview of Digest authentication, and describe Digest authentication support and configuration in Oracle Communications Converged Application Server.
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, password, the nonce value from the challenge, the SIP method, and the requested URI.
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 2-1 for a more detailed explanation of the challenge-response mechanism for a typical request.
Oracle Communications Converged Application Server 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 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:
The LDAP Digest Identity Asserter is compatible with any LDAP provider that permits storage of a clear text password or pre-calculated hash value.
Notes: | 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. |
Note: | 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 2-1 shows the basic architecture and use of an Identity Asserter provider for a typical client request:
sip-xml
deployment descriptor. See
Controlling Access to SIP Servlet Resources.)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. |
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 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 2-2. Maintaining LDAP stores in this manner is beyond the scope of this documentation. |
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 Communications Converged Application Server configuration.
Table 2-1 summarizes all of the information you will need in order to fully configure your LDAP server for Digest authentication with Oracle Communications Converged Application Server.
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 Steps for Configuring Digest Authentication.
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.
|
||
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 Configure the LDAP Server or RDBMS.
|
||
Follow these steps to configure Digest authentication with Oracle Communications Converged Application Server:
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”. |
The sections that follow describe each step in detail.
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.
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:
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.
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:
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 Communications Converged Application Server provides a simple utility to generate a hash of the A1 value from a given username, realm name, and unencrypted password. The utility is packaged as com.bea.wcp.sip.security.utils.PreCalculatedHash
. Use the syntax:
java com.bea.wcp.sip.security.utils.PreCalculatedHash
user_namerealm_name
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.
Oracle Communications Converged Application Server 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 com.bea.wcp.sip.security.utils.JSafeEncryptionUtil
and is packaged in the wlss.jar
file in the WLSS_HOME/telco/lib
directory.
To view usage instructions and syntax:
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:
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 Configuring LDAP Authentication Providers in the Oracle WebLogic Server 10g Release 3 documentation set to create an LDAP authentication provider for your LDAP server. Use the information from Table 2-1, Digest Identity Asserter Checklist, on page 2-6 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:
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:
Follow these instructions to create a new LDAP Digest Identity Asserter Provider:
PLAINTEXT
, PRECALCULATEDHASH
, or REVERSIBLEENCRYPTED
.ldap1.mycompany.com:1050 ldap2.mycompany.com:1050
See Configuring Failover for LDAP Authentication Providers in the Oracle WebLogic Server 10g Release 3 documentation for more information about configuring failover.
Note that stale connections (for example, LDAP connections that are timed out by a load balancer) are automatically removed from the connection pool.
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.
Follow these instructions to create a new RDBMS Digest Identity Asserter Provider:
SELECT G_NAME FROM groupmembers WHERE G_MEMBER = ?
.PLAINTEXT
, PRECALCULATEDHASH
, or REVERSIBLEENCRYPTED
.
You can use Oracle Communications Converged Application Server’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.
To create new users with password information in the existing “description” field:
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 Configure an LDAP Digest Identity Asserter Provider:
Listing 2-1 shows the security provider configuration in config.xml
for a domain that uses LDAP implementation embedded in Oracle Communications Converged Application Server. Note that such a configuration is recommended only for testing or development purposes. Listing 2-1 highlights values that you must define when configuring the provider using the instructions in Configure an LDAP Digest Identity Asserter Provider.
<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>