Versions Compared

Old Version 122

changes.mady.by.user Former user

Saved on

compared with

New Version Current

changes.mady.by.user Former user

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Info

X509Certificate Authenticator is supported by WSO2 Identity Server versions 5.1.0 , - 5.2.0, 5.3.0, 5.4.0, 5.4.1 and 5.5.010.0.

Table of Contents
maxLevel3
minLevel3

...

  1. Download the WSO2 Identity Server.

  2. Replace your keystore file path, keystore password, trust store file path and trust store password (you can use the keystore and truststore, which you created under the Working with Certificate section) in the following configuration and add it to  <IS_HOME>/repository/conf/tomcat/catalina-server.xml file.

    Code Block
    languagexml
    <Connector
        protocol="HTTP/1.1"
        port="8443" maxThreads="200"
        scheme="https" secure="true" SSLEnabled="true"
        keystoreFile="/path/to/keystore.jks" keystorePass="keystorepwd"
        truststoreFile="/path/to/truststore.jks" truststorePass="truststorespassword"
		bindOnInit = "false"
        clientAuth="want" sslProtocol="TLS"/>
    Note
    • To function properly, this connector should come first in the order. Otherwise, when mutual SSL takes place, the already existing connector (9443) will be picked up and the certificate will not be retrieved correctly.
    • The clientAuth attribute causes the Tomcat to require the client with providing a certificate that can be configured as follows.

      • true: valid client certificate required for a connection to succeed

      • want: use a certificate if available, but still connect if no certificate is available

      • false: no client certificate is required or validated

    • The truststoreFile attributes specifies the location of the truststore that contains the trusted certificate issuers.

  3. Download the authenticator .jar file and the artifacts from the WSO2 store.

  4. Place the authenticator .jar file in the <IS_HOME>/repository/components/dropins directory. 

    Note

    If you want to upgrade the X509 Certificate Authenticator in your existing IS pack, please refer upgrade instructions.

  5. Place the x509certificateauthenticationendpoint.war file in the <IS_HOME>/repository/deployment/server/webapps directory.

...

Table of Content Zone
locationtop

Authenticating using the Subject Alternative Name

Info
titleAbout Subject Alternative Name

The Subject Alternative Name (SAN) is an extension to the X.509 certificate format that enables securing multiple hostnames such as CN, IP, DNS and email, using a single certificate.

Note
titleHow SAN works in WSO2 Identity Server
  • If SAN is not enabled, the system does not check for alternative names in the certificate.
  • If SAN is enabled with either of the following, the system throws an error fails the authentication process:
    • Alternative names are not defined in the certificate.
    • No matching string is found for the alternative name pattern that is defined in the certificate.
    • There are multiple matching strings found for the alternative name pattern that is defined in the certificate.
  • If SAN is enabled where a single match is found for the alternative name pattern that is defined in the certificate, that match is used as the user name and the system begins user authentication. When a user with the given user name is found in the system, the user gets authenticated.ated. 

To enable SAN in WSO2 Identity Server, set the following configuration under the AuthenticationConfig name="x509CertificateAuthenticator" tag in the application-authentication.xml file in the <IS_HOME>/repository/conf/identity directory.

Code Block
 <Parameter name="AlternativeNamesRegex">^[a-zA-Z]{3}$</Parameter>

Authenticating using the RDN

expand
Info
titleAbout RDN and DN

  • Relative Distinguished Name (RDN)
    An RDN comprises one or more certificate attribute-value pairs in the form of <attribute>=<value>.

    Code Block
    titleSample RDN
    cn=John Doe+o=WSO2

    In the above example, the two attribute-pairs, cn=John Doe and c=US are separated by a plus (+) sign.

  • Distinguished Name (DN)
    A DN is a sequence of comma-separated RDNs, i.e., RDNs are the components of a DN.

    Code Block
    titleSample DN
    cn=Jon Doe+o=WSO2, c=US
Note
titleHow DN/RDN works in WSO2 Identity Server

When this is configured, the system checks for a matching string from the subject DN. Once found, it is used as the user name to proceed with user authentication. If more than one matching values or no matching values are found, the system throws an error and fails the authentication process.

To enable subject DN in WSO2 Identity Server, set the following configuration under the AuthenticationConfig name="X509CertificateAuthenticator" tag in the application-authentication.xml file in the <IS_HOME>/repository/conf/identity directory.

Code Block
<Parameter name="UsernameRegex">[a-zA-Z]{3}</Parameter>