How to Set Up Certificate-based Authentication for Convergence 2

Skip to end of metadata
Go to start of metadata

This documentation applies to Communications Suite 7 Update 1 at the time of its release. The most up-to-date documentation is available at the Communications Suite Documentation Home.

How to Set Up Certificate-based Authentication for Convergence 2

The following topics (with the exception of the introduction) are the also tasks required to set up certificate-based authentication and should be performed in the given order.


Introduction to Certificates and SSL

About Digital Certificates

Digital certificates (or simply certificates) are electronic files that uniquely identify people and resources on the Internet. Certificates also enable secure, confidential communication between two entities.

There are different kinds of certificates, such as personal certificates, used by individuals, and server certificates, used to establish secure sessions between the server and clients through secure sockets layer (SSL) technology. For more information on SSL, see About Secure Sockets Layer.

Certificates are based on public key cryptography, which uses pairs of digital keys (very long numbers) to encrypt or encode information so it can be read only by its intended recipient. The recipient then decrypts (decodes) the information to read it.

A key pair contains a public key and a private key. The owner distributes the public key and makes it available to anyone. But the owner never distributes the private key; it is always kept secret. Because the keys are mathematically related, data encrypted with one key can be decrypted only with the other key in the pair.

A certificate is like a passport: it identifies the holder and provides other important information. Certificates are issued by a trusted third party called a Certification Authority (CA). The CA is analogous to passport office: it validates the certificate holder's identity and signs the certificate so that it cannot be forged or tampered with. Once a CA has signed a certificate, the holder can present it as proof of identity and to establish encrypted, confidential communications.

Most importantly, a certificate binds the owner's public key to the owner's identity. Like a passport binds a photograph to personal information about its holder, a certificate binds a public key to information about its owner.

In addition to the public key, a certificate typically includes information such as:

  • The name of the holder and other identification, such as the URL of the Web server using the certificate, or an individual's email address.
  • The name of the CA that issued the certificate.
  • An expiration date.

Digital Certificates are governed by the technical specifications of the X.509 format. To verify the identity of a user in the certificate realm, the authentication service verifies an X.509 certificate, using the common name field of the X.509 certificate as the principal name.

About Certificate Chains

Web browsers are pre-configured with a set of root CA certificates that the browser automatically trusts. Any certificates from elsewhere must come with a certificate chain to verify their validity. A certificate chain is series of certificates issued by successive CA certificates, eventually ending in a root CA certificate.

When a certificate is first generated, it is a self-signed certificate. A self-signed certificate is one for which the issuer (signer) is the same as the subject (the entity whose public key is being authenticated by the certificate). When the owner sends a certificate signing request (CSR) to a CA, then imports the response, the self-signed certificate is replaced by a chain of certificates. At the bottom of the chain is the certificate (reply) issued by the CA authenticating the subject's public key. The next certificate in the chain is one that authenticates the CA's public key. Usually, this is a self-signed certificate (that is, a certificate from the CA authenticating its own public key) and the last certificate in the chain.

In other cases, the CA can return a chain of certificates. In this case, the bottom certificate in the chain is the same (a certificate signed by the CA, authenticating the public key of the key entry), but the second certificate in the chain is a certificate signed by a different CA, authenticating the public key of the CA to which you sent the CSR. Then, the next certificate in the chain is a certificate authenticating the second CA's key, and so on, until a self-signed root certificate is reached. Each certificate in the chain (after the first) thus authenticates the public key of the signer of the previous certificate in the chain.
About Secure Sockets Layer

Secure Sockets Layer (SSL) is the most popular standard for securing Internet communications and transactions. Web applications use HTTPS (HTTP over SSL), which uses digital certificates to ensure secure, confidential communications between server and clients. In an SSL connection, both the client and the server encrypt data before sending it, then decrypt it upon receipt.

When a Web browser (client) wants to connect to a secure site, an SSL handshake happens:

  • The browser sends a message over the network requesting a secure session (typically, by requesting a URL that begins with https instead of http).
  • The server responds by sending its certificate (including its public key).
  • The browser verifies that the server's certificate is valid and is signed by a CA whose certificate is in the browser's database (and who is trusted). It also verifies that the CA certificate has not expired.
  • If the certificate is valid, the browser generates a one time, unique session key and encrypts it with the server's public key. The browser then sends the encrypted session key to the server so that they both have a copy.
  • The server decrypts the message using its private key and recovers the session key.

After the handshake, the client has verified the identity of the Web site, and only the client and the Web server have a copy of the session key. From this point forward, the client and the server use the session key to encrypt all their communications with each other. Thus, their communications are ensured to be secure.

The newest version of the SSL standard is called TLS (Transport Layer Security). The Enterprise Server supports the Secure Sockets Layer (SSL) 3.0 and the Transport Layer Security (TLS) 1.0 encryption protocols.

To use SSL, the Enterprise Server must have a certificate for each external interface, or IP address, that accepts secure connections. The HTTPS service of most Web servers will not run unless a digital certificate has been installed. Use the procedure described in Generating a Certificate Using the keytool Utility to set up a digital certificate that your Web server can use for SSL.

About Ciphers

A cipher is a cryptographic algorithm used for encryption or decryption. SSL and TLS protocols support a variety of ciphers used to authenticate the server and client to each other, transmit certificates, and establish session keys.

Some ciphers are stronger and more secure than others. Clients and servers can support different cipher suites. Choose ciphers from the SSL3 and TLS protocols. During a secure connection, the client and the server agree to use the strongest cipher they both have enabled for communication, so it is usually sufficient to enable all ciphers.

Using Name-based Virtual Hosts

Using name-based virtual hosts for a secure application can be problematic. This is a design limitation of the SSL protocol itself. The SSL handshake, where the client browser accepts the server certificate, must occur before the HTTP request is accessed. As a result, the request information containing the virtual host name cannot be determined prior to authentication, and it is therefore not possible to assign multiple certificates to a single IP address.

If all virtual hosts on a single IP address need to authenticate against the same certificate, the addition of multiple virtual hosts probably will not interfere with normal SSL operations on the server. Be aware, however, that most browsers will compare the server's domain name against the domain name listed in the certificate, if any (applicable primarily to official, CA-signed certificates). If the domain names do not match, these browsers display a warning. In general, only address-based virtual hosts are commonly used with SSL in a production environment.

How to Enable SSL and Client Authentication for a Listener in Oracle GlassFish Server

HTTP Listeners

Each virtual server provides connections between the server and clients through one or more HTTP listeners. Each HTTP listener is a listen socket that has an IP address, a port number, a server name, and a default virtual server.

HTTP listeners must have a unique combination of port number and IP address. For example, an HTTP listener can listen on all configured IP addresses on a given port for a machine by specifying the IP address Alternatively, the HTTP listener can specify a unique IP address for each listener, but use the same port.

Since an HTTP listener is a combination of IP address and port number, you can have multiple HTTP listeners with the same IP address and different port numbers (for example, and, or with different IP addresses and the same port number (for example, and, if your machine was configured to respond to both these addresses).

However, if an HTTP listener uses the IP address, which listens on all IP addresses on a port, you cannot create HTTP listeners for additional IP addresses that listen on the same port for a specific IP address. For example, if an HTTP listener uses (all IP addresses on port 8080), another HTTP listener cannot use

Because the system running the Enterprise Server typically has access to only one IP address, HTTP listeners typically use the IP address and different port numbers, with each port number serving a different purpose. If the system does have access to more than one IP address, each address can serve a different purpose.

By default, when the Enterprise Server starts, it has the following HTTP listeners:

  • Two HTTP listeners named http-listener-1 and http-listener-2, associated with the virtual server named server.
  • An HTTP listener named admin-listener, associated with the virtual server named __asadmin.

All these listeners use the IP address and the port numbers specified as the HTTP server port numbers during installation of the Enterprise Server. If the Enterprise Server uses the default port number values, http-listener-1 uses port 8080, http-listener-2 uses port 8181, and admin-listener uses port 48489.

Each HTTP listener has a default virtual server. The default virtual server is the server to which the HTTP listener routes all request URLs whose host component does not match any of the virtual servers that are associated with the HTTP listener (a virtual server is associated with an HTTP listener by listing the HTTP listener in its http-listeners attribute).

In addition, specify the number of acceptor threads in the HTTP listener. Acceptor threads accept new connections and put them onto a connection queue. Session threads then pick up connections from the queue and service the requests. The server posts more session threads if required at the end of the request.

A set of request processing threads retrieves incoming HTTP requests from the connection queue and processes the requests. These threads parse the HTTP headers, select the appropriate virtual server, and run through the request processing engine to service the request. When there are no more requests to process, but the connection can be kept persistent (either by using HTTP/1.1 or sending a Connection: keep-alive header), the request processing thread assumes the connection to be idle and passes the connection to the Keep-Alive connection management subsystem.

The Keep-Alive subsystem periodically polls such idle connections and queues those connections with activity into the connection queue for future processing. From there, a request processing thread again retrieves the connection and processes its request. The Keep-Alive subsystem is multi-threaded, as it manages potentially tens of thousands of connections. Efficient polling techniques are used, by dividing the number of connections into smaller subsets, to determine which connections are ready with requests and which of those connections have idled for sufficient time to deem them closed (beyond a maximum permissible Keep-Alive timeout).

The HTTP listener's server name is the host name that appears in the URLs the server sends to the client as part of a redirect. This attribute affects URLs the server automatically generates; it does not affect the URLs for directories and files stored in the server. This name is normally the alias name if the server uses an alias. If a client sends a Host: header, that host name supersedes the HTTP listener's server name value in redirects.

Specify a redirect port to use a different port number from that specified in the original request. A redirect occurs in one of these situations:

  • If a client tries to access a resource that no longer exists at the specified URL (that is, the resource has moved to another location), the server redirects the client to the new location (instead of returning a 404), by returning a designated response code and including the new location in the response's Location header.
  • If a client tries to access a resource that is protected (for example, SSL) on the regular HTTP port, the server redirects the request to the SSL-enabled port. In this case, the server returns a new URL in the Location response header, in which the original insecure port has been replaced with the SSL-enabled port. The client then connects to this new URL.

Specify also whether security is enabled for an HTTP listener and what kind of security is used (for example, which SSL protocol and which ciphers).

How to Enable How SSL and client authentication for listener in Oracle GlassFish server 

  1. Log into the GlassFish Administration Console.
  2. Click on Configurations -> server-config -> HTTP Service -> HTTP Listener -> Click the listener where SSL is enabled -> Click on SSL tab in the right pane -> Select the check box "Client Authentication Enabled."
  3. Save Changes.
  4. Restart the GlassFish Application Server.

Accessing a Web Application Deployed on GlassFish Server

To access a web application deployed on the GlassFish Server, use the URL http://localhost:8080/ (or https://localhost:8181/ if it is a secure application), along with the context root specified for the web application. To access the Admin Console, use the URL https://localhost:4848/ or http://localhost:4848/asadmin/ (its default context root).

Because a virtual server must specify an existing HTTP listener, and because it cannot specify an HTTP listener that is already being used by another virtual server, create at least one HTTP listener before creating a new virtual server. The above restriction applies only if the new virtual server has the same host or alias name as one of the virtual servers already bound to the existing HTTP listener.

HTTP listener Sub-elements, Attributes and Properties

For detailed information about the available sub-elements, attributes and properties for the http-listener element, see Tables 1-71 - 1-73.

How to Obtain and Manage Certificates in the GlassFish Server Using Network Security Service (NSS) Tools

The following NSS tools are available to obtain and manage certificates in the GlassFish server:

  • certutil, a command-line utility for managing certificates and key databases.
  • pk12util, a command-line utility used to import and export keys and certificates between the certificate/key databases and files in PKCS12 format.
  • modutil, a command-line utility for managing PKCS #11 module information within secmod.db files or within hardware tokens.

For detailed instructions and examples of how to use the aforementioned utilities, see Using Network Security Service (NSS) Tools.

Certificate Revocation Support in GlassFish Server

There are two types of Certificate Revocation Lists, static and dynamic. The following methods of certificate revocation are supported:

  1. Static Certificate Revocation List (CRL) checking
  2. Dynamic Certificate Revocation List (CRL) checking
  3. Revocation Checking using OCSP (Online Certificate Status Protocol)

For detailed information on how to enable revocation checking, see SSL and CRL Checking in Oracle GlassFish Server

How to Configure the Convergence Certificate Mapper

Introduction to the Certificate Mapper

A certificate mapper is used to map a certificate presented by a client to the user in the directory that should be
associated with that certificate. Certificate mapping determines how Convergence server scans user entries in the LDAP directory. Use the certmap.conf to configure how a client certificate is mapped to an LDAP entry. You can edit the certmap.conf file to add entries to match the structure of your LDAP directory and to list the certificates you want your users to have. Users can be authenticated based on attributes and their corresponding values used in the subjectDN.

The mapping file defines the following information:

  • The LDAP tree location the server from where begins its search (Base DN)
  • Certificate attributes the server should use as search criteria when searching for the entry in the LDAP
  • Whether the server must go through an additional verification process

Mapper file syntax

The file contains one or more named mappings, each applying to a different CA. Note that only lower-case entries can be used in <name>. A mapping has the following syntax:

For example:

The first line specifies a name(s) for the entry. You can use any name for the entry. If a mapper entry for a specific CA (as present in the IssuerDN in the client certificate) does not exist, the default configuration/mapping is used. Thus, it is recommended to configure default mappings.

Properties and Values

The certmap.conf has the following properties:


The certificate authority IssuerDN of the certificates to which the map applies. (DN format as defined in RFC 2253). The IssuerDN must match the IssuerDN of the CA that issued the client certificate. For example, the following two IssuerDN lines have different space separating the attributes, but the server treats these as two separate entries


The following are the valid syntax for IssuerDN:

  • empty - The corresponding map is invalid. The server will fall back to use the default map. (For example: usps.IssuerDN=)
  • commented out/not set - The corresponding map is invalid. The server will fall back to use the default map.
  • Valid RFC 2253 DN - This map will be used for all the certificates, whose IssuerDN matches this DN.


The DNComps property is used to configure the LDAP tree location from where the server begins its search (Base DN)
Specifies a comma separated list of relative distinguished name components of the base DN for an LDAP search to find the user entry matching the certificate. The components are taken from the subject DN of the certificate
The server gathers values for these attributes from the client certificate and uses the values to form an LDAP DN, which determines where the server starts its search in the LDAP directory. For example, if you set DNComps to use the o and c attributes of the DN, the server starts the search from the o=<org>, c=<country> entry in the LDAP directory, where <org> and <country> are replaced with values from the DN in the certificate.

Any attribute for which a mapping is defined but is not contained in the certificate subject is not included in the generated base DN.


The following are the valid syntax for DNComps:

  • empty - The server performs a sub-tree search with base DN as the configured Base DN (dcroot) in convergence
    configuration. (For example: default.DNComps=)
  • commented out - take the existing user's DN from the cert and this becomes the Base DN. (For example: #default.DNComps=ou,o)
  • attribute names - a comma separated list of attributes to form DN. The attribute values are taken from the subject DN
    of the certificate.
    attribute substitutions - attribute and their corresponding LDAP attribute to be used as a substitute while
    constructing the Base DN. The attribute values are taken from the subject DN of the certificate. (For example: default.DNComps=ou=OrgUnit,o)
Supported Attributes

The following specified attributes are supported in this mapper (as listed in RFC 2253 and RFC 5280):

Attribute Keyword Description
cn Common Name
l location
street Street
ou Organization Unit
o Organization
c Country
uid Unique ID
emailaddress RFC 822 Email Address
s State
serialnumber Serial Number for a name
dnq/dnqqualifier DN specific information
t Person's title (rank)
surname Last Name
givenname First Name
initials Initials
generation denoting Jr. 'III', etc.
ip IP address


FilterComps specifies a comma separated list of attributes to form a filter for an LDAP search to find the user entry matching the certificate. The values for the filter are taken from the Subject DN of the client certificate.
If multiple attribute mappings are defined, then the server combines them with an AND search. For example, if two mappings are defined cn and uid, and the server is presented with a certificate having a subject of,CN=John Doe,O=Example Corp,C=US, then it generates a search filter of (&(cn=John Doe)(

Any attribute for which a mapping is defined but is not contained in the certificate subject is not included in the generated search filter. All attributes that can be used in generated search filters should have corresponding indexes in all back-end databases that can be searched by this certificate mapper. For the mapping to be successful, the generated search filter must match one user in the directory (within the scope of the base DNs for the mapper). If no users or multiple users match the generated criteria, the mapping fails.


The following are the valid syntax for FilterComps:

  • empty - The generated search filter is (objectclass=*) (For example: default.FilterComps=)
  • commented out - The generated search filter is (objectclass=*) (For example: #default.DNComps=cn)
  • attribute names - a comma separated list of attributes to form search. The attribute values are taken from the subject DN of the certificate. If multiple attribute mappings are defined, then the server combines them with an AND
  • attribute substitutions - attribute and their corresponding LDAP attribute to be used as a substitute while
    constructing the search filter. The attribute values are taken from the subject DN of the certificate. (For example: default.FilterComps=uid=employeeID,emailaddress=mail)
Supported Attributes

The following specified attributes are supported in this mapper (as listed in RFC 2253 and RFC 5280):

Attribute Keyword Description
cn Common Name
l location
street Street
ou Organization Unit
o Organization
c Country
uid Unique ID
emailaddress RFC 822 Email Address
s State
serialnumber Serial Number for a name
dnq/dnqqualifier DN specific information
t Person's title (rank)
surname Last Name
givenname First Name
initials Initials
generation denoting Jr. 'III', etc.
ip IP address


CmapLdapAttr specifies the name of the LDAP attribute in the directory containing the subject DN of the certificate.
Unless this attribute is empty, the baseDN is the convergence configured Base DN (DC root) with a search filter containing subject DN. For the mapping to be successful, the certificate mapper must match exactly one user (within the scope of the base DNs for the mapper). If no entries or multiple entries match, the server performs a search with the baseDN generated from the corresponding DNComps and the search filter from the corresponding FilterComps.


The following is valid syntax for CmapLdapAttr:

  • attribute name - is a name for the attribute in the LDAP directory that contains subject DNs from all certificates
    belonging to the user. (For example: default.CmapLdapAttr=certSubjectDN)


VerifyCert tells the server whether it should compare the client's certificate with the certificate found in the LDAP directory. It takes two values: on and off. This feature is useful to ensure your end-users have a valid, un-revoked certificate. However, you should only use this property if your LDAP directory contains certificates.
The default behavior is the same as off, meaning client certificates are not checked to be valid and not revoked.


The following is the valid syntax for VerifyCert:

  • on - compare's client certificate with the certificate found in the userCertificate attribute in user's LDAP entry
    (For example: default.VerifyCert=on)

Sample Mappings for the certmap.conf

The certmap.conf file should have at least one entry. The following examples illustrate the different ways you can use the certmap.conf file.

Example 1

This example represents a certmap.conf file with only one default mapping:

default.DNComps=ou, o, c
default.FilterComps= emailaddress=mail, uid

Using this example, the server starts its search at the LDAP branch point containing the entry {{ou=<orgunit>, o=<org>,
c=<country>}} where the text within <> is replaced with the values from the subject's DN in the client certificate.
The server then uses the values for email address and userid from the certificate to search for a match in the LDAP
directory. The search filter would be &(mail=<email>)(uid=<uid>)). When it finds an entry, the server verifies the certificate by comparing the one the client sent to the one stored in the directory.

Example 2

The following example file has two mappings, one for default and another for the US Postal Service (USPS):

When the server gets a certificate from someone other than the USPS, it uses the default mapping, which starts at the
configured base DN (DC root) and searches for an entry matching the client's user ID and email address. If the certificate is from the USPS, the server starts its search at the base DN containing the organizational unit and searches for matching email addresses. Note that if the certificate is from the USPS, the server verifies the certificate; other certificates are not verified.

The IssuerDN in the certificate must be identical to the IssuerDN listed in the first line of the mapping. In the previous example, a certificate from an issuer DN that is o=United States Postal Service,c=US will not match because there is no space between the o and the c attributes.
Example 3

The following example uses CmapLdapAttr to scan the LDAP database for the certSubjectDN attribute whose
value exactly matches the entire subject DN taken from the client certificate.

If the client certificate subject is:
uid=Walt Whitman, o=LeavesOfGrass Inc, c=US

the server first searches for entries that contain the following information:

certSubjectDN=uid=Walt Whitman, o=LeavesOfGrass Inc, c=US

If a matching entry is found, the server verifies the entry. If no matching entries are found, the server uses
DNComps and FilterComps to search for matching entries. In this example, the server would search for uid=Walt Whitman in all entries under o=LeavesOfGrass Inc, c=US.

How to Use the iwcadmin CLI Tool to Enable Certificate Authentication Support

To enable certificate authentication support using the iwcadmin CLI Tool, set the auth.cert.enable option to
=true. For details, see CLI tool Overview

Once you have enabled certificate authentication support, restart the GlassFish Server.

How To Enable Fallback to Form-based Authentication with Certificate-based Authentication Disabled

If the form-based option is set to true, and certificate-based authentication is disabled, when the user accesses Convergence without certificate authentication, a login page is displayed. Additionally, Convergence can be accessed on another port. (This feature will be supported in future releases of GlassFish).

To enable form-based authentication, set auth.cert.enablefallback to true.

wip wip Delete
convergence convergence Delete
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.

Sign up or Log in to add a comment or watch this page.

The individuals who post here are part of the extended Oracle community and they might not be employed or in any way formally affiliated with Oracle. The opinions expressed here are their own, are not necessarily reviewed in advance by anyone but the individual authors, and neither Oracle nor any other party necessarily agrees with them.