This chapter describes 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 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, realm, 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 3-1, "Digest Authentication in Converged Application Server" for a more detailed explanation of the challenge-response mechanism for a typical request.
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:
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 "Configure the LDAP Server or RDBMS" for more information.
Reverse-Encrypted Passwords. 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.
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 3-1 shows the basic architecture and use of an Identity Asserter provider for a typical client request:
The client makes an unauthorized request for a protected application resource. (You protect SIP Servlet resources by specifying the @SipSecurity
annotation. See RFC 359, sections 22.3.10.)
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.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.
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.
The generated Digest string is compared to the client's Digest to verify the user's identity.
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 "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 @SipConstraint
annotation inside the @SipSecurity
annotation. See RFC 359, sections 20.8, 23.3.10.1 and 23.3.10.2.
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 3-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 Converged Application Server configuration.
Table 3-1, "Digest Identity Asserter Checklist" summarizes all of the information you will need in order to fully configure your LDAP server for Digest authentication with 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".
Table 3-1 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 Converged Application Server 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 Converged Application 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. |
(&(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 "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. Converged Application Server 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 |
Follow these steps to configure Digest authentication with Converged Application Server:
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".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. Be aware 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:
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.
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.
Converged Application Server provides a simple utility (PreCalculatedHash) 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_name 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 the password information in this manner is beyond the scope of this documentation.
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 WebLogic_Home/sip/server/lib
directory, where WebLogic_Home
is the directory where the WebLogic Server component of Converged Application Server is installed.
To view usage instructions and syntax:
Add wlss.jar
to your classpath. The default path is:
export CLASSPATH=$CLASSPATH:~/oracle/Middleware/Oracle_Home/wlserver/sip/server/lib/wlss.jar
Execute the utility without specifying options:
java com.bea.wcp.sip.security.utils.JSafeEncryptionUtil
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:
Log in to the Administration Console for the Converged Application Server domain you want to configure.
In the left pane of the Console, select the Security Realms node.
Select the name of your security realm in the Realms table in the right pane of the Console.
Select the Providers tab, then select the Authentication subtab.
Select the DefaultAuthenticator provider.
Select the Configuration tab and then select the Common subtab.
Choose SUFFICIENT from the Control Flag drop down list.
Click Save to save your changes.
Restart the server.
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 provided in Oracle Fusion Middleware Securing Oracle WebLogic Server to create an LDAP authentication provider for your LDAP server. Use the information from Table 3-1, "Digest Identity Asserter Checklist" 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:
Log in to the Administration Console for the Converged Application Server domain you want to configure.
In the left pane of the Console, select the Security Realms node.
Select the name of your security realm in the Realms table in the right pane of the Console.
Select Providers, then select the Authentication subtab.
Click New.
Enter a name for the new provider, and select IdentityAssertionAuthenticator from the Type drop down list.
Click OK.
Select the name of the new provider from the Authentication Providers table.
Select the Configuration tab and then select the Common subtab.
Choose SUFFICIENT from the Control Flag drop down list.
Click Save to save your changes.
Restart the server.
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:
Log in to the Administration Console for the Converged Application Server domain you want to configure.
In the left pane of the Console, select the Security Realms node.
Select the name of your security realm in the Realms table in the right pane of the Console.
Select Providers, then select the Authentication subtab.
Click New.
Enter a name for the new provider, and select LdapDigestIdentityAsserter from the Type drop down list.
Click OK.
Select the name of the new provider from the list of providers.
Select Configuration, then select the Provider Specific subtab in the right pane.
On the configuration page, enter LDAP server and Digest authentication information into the fields as follows (use the information from Table 3-1, "Digest Identity Asserter Checklist"):
User From Name Filter: Enter an LDAP search filter that Converged Application 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.
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 Converged Application Server 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 Converged Application Server and the LDAP Server.
Principal: Enter the name of a principal that Converged Application Server 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.
Click Save to save your changes.
Select the Performance tab in the right pane.
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 Converged Application Server. To view the current number of configured threads, right-click on the Converged Application Server 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.
Click Save to save your changes.
Restart the server.
Follow these instructions to create a new RDBMS Digest Identity Asserter Provider:
Log in to the Administration Console for the Converged Application Server domain you want to configure.
In the left pane of the Console, select the Security Realms node.
Select the name of your security realm in the Realms table in the right pane of the Console.
Select Providers, then select the Authentication subtab.
Click New.
Enter a name for the new provider, and select DBMSDigestIdentityAsserter as the type.
Click OK.
Select the name of the new provider from the Authentication Providers table.
Select Configuration, then select the Provider Specific subtab in the right pane.
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.
Click Save to save your changes.
Restart the server.
You can use 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:
Log in to the Administration Console for the Converged Application Server domain you want to configure.
In the left pane of the Console, select the Security Realms node.
Select the name of your security realm in the Realms table in the right pane of the Console.
Select the Users and Groups tab, then select the Users subtab.
Click New.
Enter a name for the new user in the Name field.
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.
Enter an 8-character password in the Password and Confirm Password fields. You cannot proceed without adding a standard password entry.
Click OK.
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":
Log in to the Administration Console for the Converged Application Server domain you want to configure.
In the left pane, click the name of the domain you are configuring.
Select the Security tab in the right pane, then select the Embedded LDAP subtab.
Enter the password you would like to use in the Credential and Confirm Credential fields.
Click Save.
Reboot the server.
Example 3-1 shows the security provider configuration in config.xml
for a domain that uses LDAP implementation embedded in Converged Application Server. Note that such a configuration is recommended only for testing or development purposes. Example 3-1 highlights values that you must define when configuring the provider using the instructions in "Configure an LDAP Digest Identity Asserter Provider".
Example 3-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>server.example.com</ext:host> <ext:port>7001</ext:port> <ext:principal>cn=Admin</ext:principal> </sec:authentication-provider>