...
Click on the Client option on the left-hand menu and then the Create button at the top right above the list of existing clients. Let's call the new client "apache" ; save it. The only required field here is the and set the access type to "confidential". Enter a redirect URL (towards the bottom of the page) . Enter a URL within the area URL namespace that will be protected by Keycloak and save. You can also put just the host's root URL and a wildcard : (e.g. http://server/*). Save the client.
On the credentials tab (second tab at the top of the page), make a note of the client secret: it's a UUID that will be needed when setting up Apache.
Adding users and groups manually
Click on the group menu item on the left-hand menu and then at the top right click "New" to add new groups.
Click on the user menu item on the left-hand menu and then at the top right "Add user". Enter the desired username and save. On the credentials tab you can then enter a new password. Turn off the temporary password feature and reset the password. Go to the group tab at the top and add groups to the created user.
Installing mod_auth_openidc
The latest release of the module and its dependencies is available at https://github.com/pingidentity/mod_auth_openidc/releases/latest (2.0.0 at the time of writing).
The Apache module relies on the cjose library (for decoding JWTs) and libhiredis for the optional Redis shared session cache. (I had a small problem when installing on Fedora 24 as the binary release required libhiredis.so.0.12 but the installed version on my machine was 0.13. I got around this by creating a symbolic link from 0.12 to 0.13 on an assumption of backward compatibility. You might not be affected by this.)
Configuring Apache
The Apache configuration needs to be set up to talk to Keycloak. There is an Apache configuration file fragment at https://github.com/Health-Education-England/TIS-SECURITY/blob/master/keycloak/httpd_openidconnect.conf.
The main elements to configure manually are:
| Directive | Value |
|---|---|
| OIDCProviderMetadataURL | The URL for the OpenID Connect configuration on Keycloak. http://localhost:8080/auth/realms/heeadmin/.well-known/openid-configuration |
| OIDCClientID | The name of the client created when setting up Keycloak |
| OIDCClientSecret | The secret for the client (available from the client's credentials page). For Keycloak, this will be a UUID |
| OIDCRedirectURI | A redirect URL within the area of the redirect URL set up on the Keycloak client page |
| ServerName | The Apache virtual host. (Apache will default to the first virtual host in a file if no virtual host name matches) |
| ProxyPass | The URL of the back-end application you want to protect |
| ProxyPassReverse | The same as ProxyPass. (This is used by Apache to change the Location header in 302 responses) |
Setting up permissions
Access control rules can be put into the Apache config file to limit access to certain URLs to users with a given set of permissions (granted via groups).
<Location />
AuthType openid-connect
Require claim groups:supervisor
ProxyPass http://localhost:8082/
ProxyPassReverse http://localhost:8082/
</Location>
Note that Apache's authorisation by default looks for any of the Require rules to pass (i.e. it ORs the rules). If you want to enforce all of the claims (such as being a member of two groups) then you should use a <RequireAll> block. Rules based on HTTP methods can also be defined either with "Require method GET" or with <Limit GET>. Be careful that <Limit methods...> applies the contained rules only to the named methods so you may want to use <LimitExcept methods...> instead. See the Apache documentation at https://httpd.apache.org/docs/2.4/mod/mod_authz_core.html for further details on Require and https://httpd.apache.org/docs/2.4/mod/core.html#limit for details on Limit.