The following sections describe how to configure WebLogic SIP Server to use Digest authentication with a supported LDAP server:
The following sections provide a basic overview of Digest authentication, and describe Digest authentication support and configuration in WebLogic SIP Server 2.0.2.
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 has value can be stored in an LDAP directory. 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 1 for a more detailed explanation of the challenge-response mechanism for a typical request.
WebLogic SIP Server 2.0.2 includes an LDAP Digest Identity Asserter security provider for asserting the validity of a client's Digest. A separate authorization provider is required to complete the authentication process (see Configure an LDAP 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 LDAP Digest Identity Asserter provider requires that user credentials be stored in an LDAP server 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.
Note: The built-in LDAP store for the DefaultAuthenticator provider does not support storage of clear text passwords or pre-calculated hash values. You must make DefaultAuthenticator an optional provider (ControlFlag="SUFFICIENT" or lower) before you can use Digest authentication, or you must configure a separate LDAP store to use for identity assertion.
Figure 1 Digest Authentication in WebLogic SIP Server 2.0.2
Figure 1 shows the basic architecture and use of the LDAP 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.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. Maintaining LDAP stores in this manner is beyond the scope of this documentation.
Figure 2 Multiple LDAP Servers
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 WebLogic SIP Server configuration.
Table 1 summarizes all of the information you will need in order to fully configure your LDAP server for Digest authentication with WebLogic SIP Server 2.0.2.
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.
Table 8 Digest Identity Asserter Checklist
|
The port number of the LDAP server. Port 389 is used by default. |
||
|
A Distinguished Name (DN) that WebLogic SIP Server can use to connect to the LDAP Server. |
||
|
A credential for the above principal name (generally a password). |
||
| 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 |
|
An LDAP search filter that WebLogic SIP Server 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. |
||
|
The base Distinguished Name (DN) of the tree in the LDAP directory that contains users. |
||
|
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. |
||
|
The algorithm that clients will use to create encrypted Digests. WebLogic SIP Server supports both MD5 and MD5-sess algorithms. MD5 is used by default. |
||
|
The Digest authentication timeout setting. By default this value is set to 120 seconds. |
Follow these steps to configure Digest authentication with WebLogic SIP Server 2.0.2:
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 used for Digest verification must store either unencrypted, clear text passwords or pre-calculated hash values. The sections below provide general information about setting up your LDAP server to store the required information. Keep in mind that each 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 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.
WebLogic SIP Server provides a simple method
call to generate a hash of the A1 value from a given username, realm
name, and unencrypted password. The built-in method is available at com.bea.wcp.sip.util.DigestUtils.getHA1("username", "realm-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 LDAP information in this manner is beyond the scope of this documentation.
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:
The LDAP Digest Identity Asserter provider requires a separate LDAP authorization provider to perform authorization for verified users. Follow the instructions in Configuring an LDAP Authentication Provider in the WebLogic Server 8.1 SP4 documentation set to create an LDAP authorization provider for your LDAP server. Use the information from Table 1 to configure the provider.
If you do not require user existence checking or group population, you can configure and use the special "no-op" Identity Assertion Authenticator to avoid an extra round-trip connection to the LDAP server. Note that the provider performs no actual authorization, and that only Digest Identity Assertion (via the LDAP Digest Identity Asserter Provider) will be performed in the system. To configure the "no-op" authorization provider:
Follow these instructions to create the LDAP Digest Identity Asserter provider and associate it with your LDAP server:
Note that stale connections (for example, LDAP connections that are timed out by a load balancer) are automatically removed from the connection pool.
See Configuring Failover for LDAP Authentication Providers in the WebLogic Server 8.1 SP4 documentation for more information about configuring failover.
After configuring Digest authentication using the preceding steps, you can verify the configuration by examining the config.xml file for your domain. Listing 1 shows the security provider configuration in config.xml for a domain that
uses Digest authentication. Note that although the IPlanetAuthenticator
provider was selected, the provider is configured to use an
Oracle Internet Directory Server.
The Administration Console automatically encrypts credential information stored in config.xml. If you are editing config.xml manually, you can use the weblogic.management.EncryptionHelper utility to encrypt the credentials as described in the WebLogic Server 8.1 documentation.
Listing 1 Sample Security Provider Configuration
<weblogic.security.providers.authentication.IPlanetAuthenticator
ControlFlag="SUFFICIENT"
Credential="{3DES}uQtI9MFcc7yR9hqgx39J2g=="
DisplayName="OIDAuthenticator"
GroupBaseDN="cn=Groups,dc=bea,dc=com" Host="lcw2k18.bea.com"
Name="Security:Name=myrealmOIDAuthenticator" Port="389"
Principal="cn=orcladmin" Realm="Security:Name=myrealm"
UserBaseDN="cn=users,dc=bea,dc=com"
UserFromNameFilter="(&(cn=%u)(objectclass=person))"/>
<com.bea.wcp.sip.security.authentication.LdapDigestIdentityAsserter
ActiveTypes="Authorization.DIGEST|WWW-Authenticate.DIGEST"
Credential="{3DES}uQtI9MFcc7yR9hqgx39J2g=="
CredentialAttributeName="middlename"
DigestRealmName="wcp.bea.com" Host="lcw2k18.bea.com"
Name="Security:Name=myrealmLdapDigestIdentityAsserter"
Principal="cn=orcladmin" Realm="Security:Name=myrealm"
UserBaseDN="cn=users,dc=bea,dc=com"UserFromNameFilter="(&(cn=%u)(objectclass=person))"/>
WebLogic SIP Server 2.0.2 enables you to configure one or more trusted hosts for which authentication is not performed. When WebLogic SIP Server receives a SIP message, it calls getRemoteAddress() on the SIP Servlet message. If this address matches an address in the server's trusted host list, no further authentication is performed for the message.
To configure one or more trusted hosts:
host1.mycompany.com,host2.mycompany.com.The trusted host configuration appears as a new XML element in the sipserver.xml configuration file. The following code listing shows an example trusted host configuration:
<filter classname="com.bea.wcp.sip.security.WLSSecurityManagerFilter">
<filter-param>
<param-name>trustedHost</param-name>
<param-value>host1.mycompany.com,host2.mycompany.com</param-value>
</filter-param>
</filter>
Notes: The XML representation of trusted hosts shown above is deprecated, and may change in a future release.
WebLogic SIP Server provides an auditing provider that you can configure to monitor authentication events in the security realm. See Configuring a WebLogic Auditing Provider in the WebLogic Server 8.1 documentation for more information.
