OpenID Connect (mod_auth_openidc)#

This module configures the Apache web server to operate as an OpenID Connect Relying Party (RP) towards an OpenID Connect Provider (OP) using mod_auth_openidc.

Installation#

Fedora#

$ sudo dnf install mod_auth_openidc
$ sudo systemctl restart httpd

Debian / Ubuntu#

$ sudo apt install libapache2-mod-auth-openidc
$ sudo systemctl restart apache2

Configuration#

OpenID Connect#

The below instructions will show you what to do at the minimum to get your RP working.

You need the following information from your OP:

OIDCProviderMetadataURL: the provider’s metadata URL, e.g.: https://oidc.example.org/.well-known/openid-configuration;
OIDCClientID: the RP client ID, as obtained for your OP;
OIDCClientSecret: the RP client secret, as obtained from your OP.

The following information is needed to register your RP at your OP:

OIDCRedirectURI: https://vpn.example.org/vpn-user-portal/redirect_uri

Replace vpn.example.org with your server’s hostname, and make sure this exactly what your register at your OP and what you set OIDCRedirectURI to.

You MUST generate your own strong password to use for OIDCCryptoPassphrase, e.g.:

$ pwgen -s 64 -n 1

Once you have/know all values configure the “VirtualHost” as mentioned below.

Virtual Host#

Modify your Apache “Virtual Host” by changing /etc/apache2/sites-available/vpn.example.org.conf (Debian / Ubuntu) or /etc/httpd/conf.d/vpn.example.org.conf (Fedora). The below is an example of what it should look like. Replace with your own values.

NOTE: set the OIDCCryptoPassphrase value to the one you generated above, i.e. replace REPLACE_ME with your passphrase and remove the # at the start of the line.

<VirtualHost *:443>

    ...

    OIDCProviderMetadataURL https://oidc.example.org/.well-known/openid-configuration
    OIDCClientID s2kpEtzBpme1b6VU
    OIDCClientSecret z1YGPSHYHU3T8eY8
    OIDCRedirectURI https://vpn.example.org/vpn-user-portal/redirect_uri
    #OIDCCryptoPassphrase REPLACE_ME

    <Location /vpn-user-portal>
        AuthType openid-connect
        Require valid-user
    </Location>

    # do not restrict API Endpoint as used by VPN clients
    <Location /vpn-user-portal/api>
        Require all granted
    </Location>

    # do not secure OAuth Token Endpoint as used by VPN clients
    <Location /vpn-user-portal/oauth/token>
        Require all granted
    </Location> 

    # If you run separete node(s) you MUST allow access to "node-api.php" 
    # without protecting it with mod_auth_openidc
    #<Location /vpn-user-portal/node-api.php>
    #    Require all granted
    #</Location>
    ...

</VirtualHost>

Make sure you restart Apache, on Fedora:

$ sudo systemctl restart httpd

On Debian / Ubuntu:

$ sudo systemctl restart apache2

Using Preferred Username#

If you want to use the claim preferred_username for example, you can request the profile scope and set the OIDCRemoteUserClaim. The @ at the end means the REMOTE_USER field will contain the preferred_username postfixed with the issuer (without https://).

OIDCScope "openid profile"
OIDCRemoteUserClaim preferred_username@

You may also want to request additional scopes, e.g. to receive the groups claim you can also request the groups scope. Refer to your OpenID Connect provider (OP) for what you need to do exactly.

Multi Factor Authentication#

If your OpenID OP supports MFA, you can request it for all authentications like described below. Update the <Location /vpn-user-portal> section like this where the ACR https://refeds.org/profile/mfa is requested and enforced:

<Location /vpn-user-portal>
    AuthType openid-connect
    <RequireAll>
        Require valid-user
        Require claim acr:https://refeds.org/profile/mfa
        # in case your OP supports this, you can enforce the use of e.g. a 
        # "hardware key" (hwk) authentication method
        #Require claim amr:hwk
    </RequireAll>
    OIDCPathAuthRequestParams acr_values=https://refeds.org/profile/mfa
</Location>

NOTE: the <RequireAll> is VERY important, by default (it seems) if you have multiple Require lines the policy is RequireAny.

VPN Portal#

Modify /etc/vpn-user-portal/config.php and set:

'authModule' => 'OidcAuthModule',

Additional configuration, i.e. the userIdAttribute and permissionAttributeList can be done under the OidcAuthModule section, as an example:

'OidcAuthModule' => [
    'userIdAttribute' => 'REMOTE_USER',
    'permissionAttributeList' => ['OIDC_CLAIM_groups'],
],

Debugging#

In case you have configured everything correctly, or as far as you can see it is done correctly, it still may not work. You can create a small script, as shown below that “dumps” all OpenID claims and other information on the screen. This may help you debug and see what exactly your OpenID Provider returns:

$ echo '<?php echo "<pre>"; var_dump($_SERVER); echo "</pre>";' | sudo tee /usr/share/vpn-user-portal/web/dump.php

Next you can visit https://vpn.example.org/vpn-user-portal/dump.php to see all the “headers” you can use for userIdAttribute and permissionAttributeList.

If you do not see what you expect, make sure that you restart Apache after changing the Apache OIDC configuration and login again at your OpenID Provider. You MAY need to restart your browser, or use “incognito” mode to fully reset the session and get the expected values.

NOTE: do not forget to remove the dump.php file after you are done!