Say you’re building a static website with content that users must log in to view and you host the site on an Apache server. Instead of managing the authentications yourself, you can use the Apache module mod_auth_openidc to authenticate and authorize users against an OpenID Connect Provider hosted by WebSphere Liberty.

Authors: Yun Jie Zhou (, Chunlong Liang (

OpenID Connect (OIDC) is becoming the accepted Internet Single Sign-on (SSO) protocol, and it works well with cloud, mobile, and native applications. OIDC lets a client (in this case, the HTTP server) request the identity of the user as an ID token in a standardized, REST-like manner.

The mod_auth_openidc module enables an Apache HTTP server to operate as an OpenID Connect Relying Party (RP); that is, the HTTP server can rely on the Liberty OpenID Connect Provider (OP) to do its user authentication. The RP receives user identity information from the OP and passes the identity information in the ID token to the back-end Liberty application server in the HTTP Request header. The application server can extract user identity information from the HTTP header to perform further authorization.

Some of the benefits of using Liberty as the OP are:

  • Liberty OP can be integrated with the Liberty LDAP user registry.
  • Liberty OP can be configured as token services by delegating user authentication to SAML identity provider or another OpenID Connect provider.
  • Liberty OP is highly customizable, and you can customize the claims in ID Token, userinfo, login form, consent form.

To find out more, see the developerWorks article Using OpenID Connect in WebSphere Application Server Liberty Profile.

In this article, we describe how to configure Apache mod_auth_openidc to work with the Liberty OpenID Connect Provider.

Before you start

Install WebSphere Liberty V8.5.5.8 with the OIDC features. Go to the <liberty_root>/bin folder, and issue the following command:

  featureManager install openidConnectServer-1.0 --when-file-exists=ignore

Set up the Liberty OpenID Provider (OP)

First, you need to set up a Liberty server instance as the OpenID Provider (OP) (for more information, see the beta Knowledge Center):

  1. Create a Liberty server instance for the OIDC provider by running the following command from the <liberty_root>/bin folder:

    server create <server_name>

  2. Configure the Liberty OpenIDConnect provider by following the instructions in the article Tutorial: Liberty OIDC architecture, functions, and configuration.
  3. Copy the following sample server.xml to overwrite your server.xml. You can edit the server.xml to customize your OP. For example, you can add the Liberty feature ldapRegistry-3.0 to configure LDAP as the OP’s user registry. In a production system that serves large number of clients, you might want to configure the database as an OAuth client and token store.
        <basicRegistry id="basic" realm="OpBasicRealm">
            <user name="testuser" password="testuserpwd" />
            <user name="user1" password="security" />
            <user name="user2" password="security" />
        <keyStore id="defaultKeyStore" password="keyspass" />
        <httpEndpoint host="" httpPort="80" httpsPort="443" id="defaultHttpEndpoint"/>
                <special-subject type="ALL_AUTHENTICATED_USERS" /> 
        <openidConnectProvider id="OP" oauthProviderRef="Oauth" >
        <oauthProvider id="Oauth"  >
                <client name="rp" secret="{xor}LDo8LTor"
                    scope="openid profile scope1 email phone address"

Configure the Apache HTTP server as OpenID Connect Relying Party (RP)

Next, you need to configure the Apache HTTP server as the OpenID Connect Relying Party (RP). The following commands are shown on Ubuntu; adapt the instructions for your operating system and package manager:

  1. Install the Apache HTTP server:

    sudo apt-get install apache2

  2. Install the Apache HTTP OpenID Connect module:

    1. Get the module build package:
    2. Install the dependency libraries:
      sudo apt-get install -y libjansson4 libhiredis0.10 libcurl3
    3. Install the mod_auth_openidc:
      sudo dpkg -i libapache2-mod-auth-openidc_1.8.0-1_amd64.deb
  3. Enable SSL on the Apache server:
    1. Generate the key and certificate:
      openssl genrsa -out vhost.key 2048
      openssl req -new -x509 -key vhost.key -out vhost.crt -days 365

    2. Add the following segment to your apache2.conf file (e.g. in /etc/apache2/apache2.conf):

       LoadModule ssl_module /usr/lib/apache2/modules/
       Listen 443
       <VirtualHost *:443>
         #    ServerName
         DocumentRoot /var/www/html
         SSLEngine on
         SSLCertificateFile "vhost.crt"
         SSLCertificateKeyFile "vhost.key"
  4. Add a few OpenID Connect entries to apache2.conf:

    LoadModule auth_openidc_module modules/
    OIDCProviderIssuer https://localhost:9443/oidc/endpoint/OP
    OIDCProviderAuthorizationEndpoint https://localhost:9443/oidc/endpoint/OP/authorize
    OIDCProviderTokenEndpoint https://localhost:9443/oidc/endpoint/OP/token
    OIDCClientID rp
    OIDCClientSecret secret
    OIDCSSLValidateServer Off
    OIDCRedirectURI https://localhost/redirect_uri
    OIDCCryptoPassphrase test4ever
    <Location />
       AuthType openid-connect
       Require valid-user
       LogLevel debug

Testing and verifying the Relying Party (RP) configuration

To verify your Relying Party (RP) configuration on the Apache HTTP server, try directly accessing a static website that is served by the HTTP server. When you try to access the static website, you should be redirected to the Liberty OP and should access the website only after you have been authenticated by the Liberty OP.

Your Apache HTTP server should now be configured so that when users visit a static website hosted on that server, they are redirected to authenticate with the Liberty OP before they can access the content of the website.

Reference articles

Join The Discussion

Your email address will not be published. Required fields are marked *