Configuring and Managing WebLogic SIP Server

Configuring Client-Cert Authentication

The following sections describe how to configure WebLogic SIP Server to use Client-Cert authentication:

Overview of 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 WebLogic SIP Server 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:

X509 Certificate from SSL—In the most common case, an X509 certificate is derived from a client token during a two-way SSL handshake between the client and the server. The SIP Servlet can view the resulting certificate in the javax.servlet.request.X509Certificate request attribute. This method for performing Client-Cert authentication is the most common and is described in the SIP Servlet specification (JSR-116). WebLogic SIP Server provides two security providers that can be used to validate the X509 certificate; see Configuring SSL and X509 for WebLogic SIP Server.
WL-Proxy-Client-Cert Header—WebLogic SIP Server provides an alternate method for supplying a Client-Cert token that does not require a two-way SSL handshake between the client and server. Instead, the SSL handshake can be performed between a client and a proxy server or load balancer before reaching the destination WebLogic SIP Server. The proxy generates the resulting X509 certificate chain and encrypts it using base-64 encoding, and finally adds it to a special WL-Proxy-Client-Cert header in the SIP message. The server hosting the destination SIP Servlet then uses the WL-Proxy-Client-Cert header to obtain the certificate. The certificate is also made available by the container to Servlets via the javax.servlet.request.X509Certificate request attribute.

To use this alternate method of supplying client tokens, you must configure WebLogic SIP Server to enable use of the WL-Proxy-Client-Cert header; see Configuring WebLogic SIP Server to Use WL-Proxy-Client-Cert. You must also configure an X509 Identity Asserter provider as described in Configuring SSL and X509 for WebLogic SIP Server.

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 Supporting Perimeter Authentication with a Custom IA Provider for a summary of steps required to implement perimeter authentication.

Configuring SSL and X509 for WebLogic SIP Server

WebLogic SIP Server 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, WebLogic SIP Server 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 WebLogic SIP Server Network Resources if you have not yet configured a secure transport.

See 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 Configuring the LDAP X509 Identity Asserter.

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 WebLogic SIP Server, or you can create a custom user name mapper class as described in Configuring a User Name Mapper in the WebLogic Server 8.1 Documentation.

Follow these instructions to configure the Default Identity Asserter:

In the left pane of the Console, expand the Security->Realms->myrealm->Providers->Authentication node.

Select the Authentication node in the left pane.

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

In the Types table, select X.509 and use the arrow to move this type to the Chosen column.

Select Base64 Decoding Required if the client token is being passed via two-way SSL or a WL-Proxy-Client-Cert header.

Click Apply to apply the change.

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:

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

Click Apply.

To use the default user name mapper:

Click the Details tab.

Select Use Default User Name Mapper

In the Default User Name Mapper Attribute Type field, select either CN-Common Name or E-Email Address depending on the user name attribute you have stored in the security realm.

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.

Click Apply.

Configuring the LDAP X509 Identity Asserter

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

In the left pane of the Console, expand the Security->Realms->myrealm->Providers->Authentication node.

Select the Authentication node in the left pane.

In the right pane of the Console, select Configure a new LDAP Digest p Asserter...

Enter a name for the new provider in the Name field, or accept the default, and click Create.

In the Active Types Chooser area, select X.509 and use the arrow to move this type to the Chosen column.

Click Apply to create the new provider.

Select the Details tab in the right pane to further configure the new provider.

In the Details tab, enter LDAP server information into the fields as follows:

User Field Attributes: Enter an LDAP search filter that WebLogic SIP Server 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.
Username 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.
Base64 Decoding Required: Select this field if the client token is being passed via two-way SSL or a WL-Proxy-Client-Cert header.
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 hostname:port value for each server separated by spaces. For example: ldap1.mycompany.com:1050 ldap2.mycompany.com:1050

See Configuring Failover for LDAP Authentication Providers in the WebLogic Server 8.1 SP5 documentation 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 WebLogic SIP Server and the LDAP Server.
Principal: Enter the name of a principal that WebLogic SIP Server 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.

Click Apply to apply your changes.

Reboot the server to realize the changed security configuration.

Configuring WebLogic SIP Server to Use WL-Proxy-Client-Cert

In order for WebLogic SIP Server 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 WebLogic SIP Server 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:

In the left pane, expand the Servers node and select a server to configure. (Alternately, expand the Clusters node and select a cluster name to configure WL-Proxy-Client-Cert use for the entire cluster.)

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

Select Client Cert Proxy Enabled.

Click Apply to apply your changes.

Follow the instructions under Configuring SSL and X509 for WebLogic SIP Server to configure either the default identity asserter or the LDAP Identity Asserter provider to manage X509 certificates. Select the Base64 Decoding Required option to decode the token passed in the WL-Proxy-Client-Cert header.

Reboot the server to realize the changed configuration.

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

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).

WebLogic SIP Server 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 WebLogic SIP Server 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 Identity Assertion Providers in Developing Security Providers for WebLogic Server (WebLogic Server 8.1 Documentation) for information about creating providers for handling tokens passed with perimeter authentication.