WSO2 Identity Server X509 authenticator configuration to support ‘X509v3 Subject Alternative Name’ and extract specific string value of certificate’s ‘Subject’ attribute RDN

6 min readJun 30, 2019

Configuring X509 authenticator to extract authenticating subject from the certificate

Add the following configurations to the <IS_HOME>/repository/conf/identity/application-authentication.xml file under the AuthenticatorConfig name=”x509CertificateAuthenticator” tag.

Authenticating using Subject Alternative Names

What is a Subject Alternative Name in x509 Certificate?

The Subject Alternative Name is an identifier placed in a subjectAltName extension. The Subject Alternative name extension is a standard PKIX certificate extension enabling identifiers of various types to be bound to the certificate subject — in addition to, or in place of, identifiers that may be embedded within or provided as a certificate’s subject field. According to the specification [3] [4], when authenticating using the subject attribute, priority should be given to the subject alternative names.

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

Without this configuration the system will not check for the alternative names in the certificate.

When the configuration is present in the application-authentication.xml file, and when there are no alternative names in the certificate or when there are no matching string to the given pattern in alternative names of the certificate or if there is more than one match to the given pattern in alternative names the system will throw an error and authentication process will fail. If there is one match to the given pattern, that match will be used as the username and the systems attempts to authenticate the user. If there is a user in the system with that given username, the user will get authenticated.

Example :

First let’s create a certificate with alternative names:

Create a file named openSSLConfig.conf, add the following configurations to it, and save the file.

[ req ]

default_md = sha256

prompt = no

req_extensions = req_ext

x509_extensions = req_ext

distinguished_name = req_distinguished_name

[ req_distinguished_name ]

0.commonName = Buddhima

1.commonName = wso2is

countryName = SL

stateOrProvinceName = Western

localityName = Colombo

organizationName = WSO2

organizationalUnitName = QA

emailAddress = buddhimah@wso2.com

[ req_ext ]

subjectAltName = @alternate_names

[ alternate_names ]

DNS.0 = buddhimau

DNS.1 = wso2.com

DNS.2 = wso2is

2. Execute the following open ssl commands to create the certificate and private key. Give the export password as ‘wso2carbon’

openssl req -config openSSLConfig.conf -new -x509 -newkey rsa:2048 -nodes -keyout unlimited.key.pem -days 365000 -out unlimited.cert.pem
openssl x509 -in unlimited.cert.pem -text -noout
openssl pkcs12 -inkey unlimited.key.pem -in unlimited.cert.pem -export -out client.p12
openssl pkcs12 -in client.p12 -noout -info

Import the certificate to the WSO2 IS client trust store using following command.

keytool -importcert -alias localcrt -file unlimited.cert.pem -keystore /Users/buddhima/IDS/WSO2/dev/TestWithAltNames/wso2is-5.8.0/repository/resources/security/client-truststore.jks -storepass wso2carbon -noprompt

2. Add the certificate to the browser

For chrome

in your browser, navigate to Settings > HTTPS/SSL > Manage certificates.
Click on Import, select the client.p12 file, and then click Open.
Note that you may have to enter the password that you used to generate the p12 file, (wso2carbon) to open it.

For Firefox

Click on the menu option on the right of the screen and select Preferences.
Click Privacy & Security in the left navigation and scroll down to the Certificates section. Click View Certificates.
In the window that appears, click Import.
Select the client.p12 file, and then click Open .
Note that you may have to enter the password that you used to generate the p12 file, (wso2carbon) to open it.

3. Open the<IS_HOME>/repository/conf/tomcat/catalina-server.xml file and add the truststore path and password.

<Connector

protocol=”HTTP/1.1"

port=“9443” maxThreads=”200"

scheme=”https” secure=”true” SSLEnabled=”true”

keystoreFile=”${carbon.home}/repository/resources/security/wso2carbon.jks”

keystorePass=”wso2carbon”

truststoreFile=”${carbon.home}/repository/resources/security/client-truststore.jks”

truststorePass=”wso2carbon”

clientAuth=”want” sslProtocol=”TLS”/>

4. Configure the authentication endpoint in the application-authentication.xml file found in the <IS_HOME>/repository/conf/identity directory.

<AuthenticatorConfig name=”x509CertificateAuthenticator” enabled=”true”>
<Parameter name=”AuthenticationEndpoint”>https://localhost:9443/x509-certificate-servlet</Parameter>
<Parameter name=”username”>CN</Parameter>
<Parameter name=”AlternativeNamesRegex”>^[a-z]{9}$</Parameter>
</AuthenticatorConfig>

5. Open the certificate-validation.xml file found in the <IS_HOME>/repository/conf/security/ directory and disable the CRLValidator and OCSPValidator.

Go to the registry through Carbon management console, browse for

/_system/governance/repository/security/certificate/validator/ocspvalidator

and /_system/governance/repository/security/certificate/validator/crlvalidator

and disable them.

6. Deploy the travelocity Sample App. For instructions on deploying the sample app, see [5].

7. Log in to the WSO2 IS management console and create a user named ‘buddhimau’

7. Register Travelocity sample as the service provider. Add tavelocity.com as the Service Provider Name.

8. Go to Inbound Authentication > SAML2 Web SSO Configuration and add the following details.

9. Go to Local & Outbound Authentication Configuration and add the following details.

To test the flow

Navigate to the http://localhost:8080/travelocity.com URL on your browser. You will be prompted with the client certificate you added.

Click OK after selecting the relevant certificate. You will be redirected to following page

Click Login and you will be logged in as the user ‘buddhimau’

Authenticate using specific string value of subject DN

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

When this configuration is present in the application-authentication.xml file, the system will get the matching string from the subject DN. That will be used as the username to authenticate. If more than one match found or there are no matches found, the system will throw an error and fail the authentication process.

Example :

First create a certificate with alternative names:

Create a file named openSSLConfig.conf, add the following configurations and save the file.

[ req ]

default_md = sha256

prompt = no

req_extensions = req_ext

x509_extensions = req_ext

distinguished_name = req_distinguished_name

[ req_distinguished_name ]

0.commonName = buddhimau

1.commonName = wso2is

countryName = SL

stateOrProvinceName = Western

localityName = Colombo

organizationName = WSO2

organizationalUnitName = QA

emailAddress = buddhimah@wso2.com

[ req_ext ]

subjectAltName = @alternate_names

[ alternate_names ]

DNS.0 = buddhimau

DNS.1 = wso2.com

DNS.2 = wso2is

3. Execute the following open ssl commands to create the certificate and private key. Give the export password as ‘wso2carbon’

openssl req -config openSSLConfig.conf -new -x509 -newkey rsa:2048 -nodes -keyout unlimited.key.pem -days 365000 -out unlimited.cert.pem
openssl x509 -in unlimited.cert.pem -text -noout
openssl pkcs12 -inkey unlimited.key.pem -in unlimited.cert.pem -export -out client.p12
openssl pkcs12 -in client.p12 -noout -info

4. Import the certificate to the WSO2 IS client trust store using following command.

keytool -importcert -alias localcrt -file unlimited.cert.pem -keystore /Users/buddhima/IDS/WSO2/dev/TestWithAltNames/wso2is-5.8.0/repository/resources/security/client-truststore.jks -storepass wso2carbon -noprompt

5. Add the certificate to the browser

6. Open the<IS_HOME>/repository/conf/tomcat/catalina-server.xml file and add the truststore path and password.

<Connector

protocol=”HTTP/1.1"

port=“9443” maxThreads=”200"

scheme=”https” secure=”true” SSLEnabled=”true”

keystoreFile=”${carbon.home}/repository/resources/security/wso2carbon.jks”

keystorePass=”wso2carbon”

truststoreFile=”${carbon.home}/repository/resources/security/client-truststore.jks”

truststorePass=”wso2carbon”

clientAuth=”want” sslProtocol=”TLS”/>

7. Configure the authentication endpoint in the application-authentication.xml file found in the <IS_HOME>/repository/conf/identity directory.

<Parameter name=”AuthenticationEndpoint”>https://localhost:9443/x509-certificate-servlet</Parameter>

</AuthenticatorConfig>

8. Open the certificate-validation.xml file found in the <IS_HOME>/repository/conf/security/ directory, and disable CRLValidator and OCSPValidator.

Go to the registry through Carbon management console browse for

/_system/governance/repository/security/certificate/validator/ocspvalidator

and /_system/governance/repository/security/certificate/validator/crlvalidator

and disable them.

9. Deploy the travelocity Sample App according to the Doc [5]

10. Log in to WSO2 IS management console and create a user named ‘buddhimau’

Repeat the steps 11–13 from the above example.

Note: If you are authenticating a user in tenant mode,the tenant domain must be present in the certificate and the regex should be capable of extracting the string with the tenant domain. The same applies when the user is in a secondary user store.

Example :

For a user in a tenant domain abc.com

[a-z]{9}@[a-z]{3}.[a-z]{3} — buddhimau@abc.com

For a user in a secondary user store TEST

[A-Z]{4}\/[a-z]{9} — TEST/buddhimau

References

WSO2 Identity Server X509 authenticator configuration to support ‘X509v3 Subject Alternative Name’ and extract specific string value of certificate’s ‘Subject’ attribute RDN

Authenticating using Subject Alternative Names

Authenticate using specific string value of subject DN

Written by Buddhima Udaranga