Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update Keycloak documentation #236

Merged
merged 2 commits into from Mar 14, 2020
Merged
Changes from all commits
Commits
File filter...
Filter file types
Jump to…
Jump to file
Failed to load files.

Always

Just for now

@@ -5,29 +5,60 @@ Two Factor Auth using Duo with Keycloak

These are the steps to setup two factor authentication with Duo using Keycloak.

#. Have Keycloak perform authentication through SSSD running on the Keycloak server.
#. Follow the `Keycloak docs for using SSSD <https://www.keycloak.org/docs/latest/server_admin/index.html#sssd-and-d-bus>`_ except use a modified ``/etc/pam.d/keycloak``:
Install Keycloak Duo SPI
--------------------------------------------------

#. Clone the Keycloak Duo SPI repo

.. code::

git clone https://github.com/OSC/keycloak-duo-spi.git
cd keycloak-duo-spi
git submodule update --init

#. Edit ``pom.xml`` and ensure ``keycloak.version`` matches the version of Keycloak you are running.

#. Build (with Docker) - produces ``target/keycloak-duo-spi-jar-with-dependencies.jar``

.. code::

auth required pam_sss.so
auth required pam_duo.so
account required pam_sss.so
docker run --rm -it -v $(pwd):/keycloak-duo-spi -w /keycloak-duo-spi \
ohiosupercomputer/keycloak_duo_spi_buildbox:latest mvn clean test package

#. Because Keycloak doesn’t actually know there is a possible challenge
response using SSSD you have to configure Duo's ``/etc/duo/pam_duo.conf``
to have ``autopush=yes`` and ``prompts=1`` so that the 2FA automatically
sends a push notification to the person’s phone.
#. Build (without Docker) - produces ``target/keycloak-duo-spi-jar-with-dependencies.jar``

#. (Optional) Require Duo based on group membership or username list
.. code::

If you want to make Duo optional you could do so via group memberships. This works by changing ``groups`` config for ``/etc/duo/pam_duo.conf`` to something like ``groups=ood_duo``.
yum -y install maven
cd build/duo_java/DuoWeb
mvn clean test install
cd ../../..
mvn clean test package

You can also limit based on group membership using the contents of a file that lists users that require Duo. This is done by modifying the keycloak PAM stack. The file ``/etc/security/ondemand-duo.conf`` is a list of usernames, one username per line, that must use Duo to authenticate with Keycloak. The modified PAM configuration at ``/etc/pam.d/keycloak``:
#. Copy the JAR file to Keycloak and instruct Keycloak to install the SPI

.. code::

auth required pam_sss.so
auth [default=1 success=ok] pam_listfile.so onerr=fail item=user sense=allow file=/etc/security/ondemand-duo.conf
auth required pam_duo.so
account required pam_sss.so
sudo install -o keycloak -g keycloak -m 0644 target/keycloak-duo-spi-jar-with-dependencies.jar \
/opt/keycloak-9.0.0/standalone/deployments/keycloak-duo-spi-jar-with-dependencies.jar
sudo install -o keycloak -g keycloak -m 0644 /dev/null \
/opt/keycloak-9.0.0/standalone/deployments/keycloak-duo-spi-jar-with-dependencies.jar.dodeploy

Configure Duo SPI
--------------------------------------------------

#. Log into your Keycloak instance
#. Choose the realm to configure in upper left corner, eg ``ondemand``
#. Choose ``Realm Settings`` in the left menu then ``Security Defenses`` tab
#. Add ``frame-src https://*.duosecurity.com/ 'self';`` to the beginning of the value for ``Content-Security-Policy``
#. Choose ``Authentication`` in the left menu
#. While on ``Flows`` tab ensure the dropdown for the flow name is ``Browser`` and click ``Copy``
#. Name the new flow ``browser-with-duo``
#. For all items below ``Username Password Form`` delete them by choosing ``Actions`` then ``Delete``
#. Choose ``Actions`` for ``Browser-with-duo Forms`` and choose ``Add Execution``
#. Select the ``Duo MFA`` provider and click ``Save``
#. Click ``Actions`` for ``Duo MFA`` and select ``Config``. Fill in all values as appropriate and select ``Save``.
#. Select ``Required`` for ``Duo MFA``
#. Choose the ``Bindings`` tab and set ``Browser Flow`` to ``browser-with-duo`` and choose ``Save``

Users logging into Keycloak will be required to verify their identity using Duo.
@@ -5,11 +5,11 @@ OpenID Connect via KeyCloak on RHEL7

This tutorial shows installing Keycloak as an OpenID Connect Identity Provider and configuring OnDemand as an OpenID Client to authenticate with this provider.

Using ``https://webdev07.hpc.osc.edu`` as the example host with OnDemand installed, at the end of the tutorial:
Using ``https://ondemand-dev.hpc.osc.edu`` as the example host with OnDemand installed, at the end of the tutorial:

#. Keycloak is running and accessible at ``https://webdev07.hpc.osc.edu:8443``
#. In both cases Apache is handling requests. Apache proxies requests for ``https://webdev07.hpc.osc.edu:8443`` to the Keycloak server running on the default port of 8080.
#. Attempting to access OnDemand at ``https://webdev07.hpc.osc.edu`` redirects the user to ``https://webdev07.hpc.osc.edu:8443`` to first authenticate.
#. Keycloak is running and accessible at ``https://ondemand-idpdev.hpc.osc.edu``
#. In both cases Apache is handling requests. Apache proxies requests for ``https://ondemand-idpdev.hpc.osc.edu`` to the Keycloak server running on the default port of 8080.
#. Attempting to access OnDemand at ``https://ondemand-dev.hpc.osc.edu`` redirects the user to ``https://ondemand-idpdev.hpc.osc.edu`` to first authenticate.

At OSC in production we do two things differently from this tutorial:

@@ -22,16 +22,15 @@ the same host as OnDemand, we don't need to provision separate SSL certificates
and host, which simplifies the tutorial.

If your site is interested in either of these things and needs assistence,
please let us know by starting the discussion on the
`mailing list <https://lists.osu.edu/mailman/listinfo/ood-users>`__.
please let us know by contacting us on the OnDemand Discourse at https://discourse.osc.edu/c/open-ondemand.

.. warning::

In production we recommend installing Keycloak on a separate host from OnDemand.

.. note::

This tutorial has only been verified to work with Keycloak 4.8.3.
This tutorial has only been verified to work with Keycloak 9.0.0.



@@ -45,3 +44,4 @@ please let us know by starting the discussion on the
tutorial-oidc-keycloak-rhel7/configure-keycloak-webui
tutorial-oidc-keycloak-rhel7/install_mod_auth_openidc
tutorial-oidc-keycloak-rhel7/add-custom-theme
tutorial-oidc-keycloak-rhel7/configure-cilogon
@@ -5,21 +5,19 @@ Add Custom Theme

Custom themes are added to a realm by

1. adding the theme directory to ``/opt/keycloak-4.8.3.Final/themes``
1. adding the theme directory to ``/opt/keycloak-9.0.0/themes``
2. selecting the theme via Admin Web UI >> Realm Settings >> Themes

Each theme is selectable based on the directory name of the theme. Themes can
extend other themes.

Here are two links to get started with a custom theme:

1. Currently version `v2.0.0 of OSC's Keycloak theme <https://github.com/OSC/keycloak-theme/tree/v2.0.0>`__
1. Currently version `v2.3.1 of OSC's Keycloak theme <https://github.com/OSC/keycloak-theme/tree/v2.3.1>`__
can be used as a starting point for modification. This theme is based off of
the default ``keycloak`` theme which itself is based off the ``base`` theme.
Files to modify include:

- ``login/login.ftl`` file for the footer links:
https://github.com/OSC/keycloak-theme/blob/v2.0.0/login/login.ftl#L63-L73
- ``login/resources/img/ondemand-logo.png`` add a logo with this name here
- ``login/resources/img/favicon.ico`` replace with your own or remove
- ``login/messages/messages_en.properties`` replace text with text
@@ -0,0 +1,69 @@
.. _authentication-tutorial-oidc-keycloak-rhel7-configure-cilogon:

Configure Keycloak with CILogon
===============================

We will now use Keycloak's admin Web UI to setup the ability to log existing users in with CILogon.

When a user logs in with CILogon for the first time they will be redirected back to Keycloak to log in with their local (ie LDAP)
credentials. This performs a mapping of their CILogon identity with their Keycloak identity.

.. warning::

CILogon can only map a single external identity to a Keycloak account. This means if a user logs in with Institution A they
must remove their mapping in order to log in with Institution B.

Register your Keycloak instance with CILogon
---------------------------------------------

#. Go to ``https://cilogon.org/oauth2/register`` and fill out the form

#. The Home URL will be the base URL of your Keycloak instance, eg: ``https://ondemand-idpdev.hpc.osc.edu``.
#. The callback URL will be ``https://ondemand-idpdev.hpc.osc.edu/auth/realms/<REALM>/broker/cilogon/endpoint``.
Replace ``https://ondemand-idpdev.hpc.osc.edu`` with your Keycloak instance
#. The box for "Is this a public client?" should not be checked
#. For "Scopes" be sure to check "profile" and "org.cilogon.userinfo"

You will be provided a Client ID and a Client Secret, be sure to save these values.
Your registered client will not be usable until you receive an email from CILogon stating your client has been approved.

Add the CILogon Identity Provider
------------------------------------------

#. Log into ``https://ondemand-idpdev.hpc.osc.edu`` as the admin user
#. Select your desired realm in the upper left corner
#. Choose "Identity Providers" in the left menu
#. Select the "Add provider..." drop down and choose "OpenID Connect v1.0"
#. Fill in the fields as noted below

#. Alias: cilogon (This must be cilogon as this alias is used in the callback URL)
#. Display Name: CILogon
#. Enabled: ON
#. First Login Flow: browser
#. Authorization URL: https://cilogon.org/authorize
#. Token URL: https://cilogon.org/oauth2/token
#. User Info URL: https://cilogon.org/oauth2/userinfo
#. Client Authentication: Client secret sent as post
#. Client ID: <Client ID provided by CILogon at registration>
#. Client Secret: <Client Secret provided by CILogon at registration>
#. Default Scopes: "openid profile org.cilogon.userinfo"

#. Click "Save"

Support users removing CILogon mappings
------------------------------------------

In order for a user to remove an existing CILogon mapping in Keycloak they must navigate to ``https://ondemand-idpdev.hpc.osc.edu/auth/realms/<REALM>/account/identity``.
Replace ``ondemand-idpdev.hpc.osc.edu`` with the web URL for your Keycloak instance.

The URL can be added to the OnDemand Help dropdown with custom text to make it easier for users to access their Keycloak identity page.

#. Add ``OOD_DASHBOARD_HELP_CUSTOM_URL`` to ``/etc/ood/config/apps/dashboard/env`` that points to the URL of the identity page for your Keycloak instance.
Example: ``https://ondemand-idpdev.hpc.osc.edu/auth/realms/osc/account/identity``
#. Update ``/etc/ood/config/locales/en.yml`` with the text to be used for the Identity provider Help link

.. code::

en:
dashboard:
nav_help_custom: Manage Federated Identity
@@ -9,7 +9,7 @@ OIDC client that will authenticate with Keycloak.
Add a new realm
------------------------------------------

#. Log into ``https://webdev07.hpc.osc.edu:8443`` as the admin user
#. Log into ``https://ondemand-idpdev.hpc.osc.edu`` as the admin user
#. Hover over "Master" on left and click "Add Realm"
#. Type in name "ondemand" and click "Create". The new realm is loaded.
#. Click Login tab, then adjust parameters:
@@ -48,9 +48,8 @@ Add OnDemand as a client

#. Choose Clients, then click Create in top right corner

#. Client ID: webdev07.hpc.osc.edu
#. Client ID: ondemand-dev.hpc.osc.edu
#. Client Protocol: openid-connect
#. Client Template: ondemand-clients
#. Save (leave Root URL blank)

#. Then edit Settings for the newly created client:
@@ -59,13 +58,13 @@ Add OnDemand as a client
#. Direct Access Grants Enabled: off
#. Valid Redirect URIs: Press the ``+`` button to the right of the URI field so you can insert two URLs:

#. ``https://webdev07.hpc.osc.edu/oidc``
#. ``https://webdev07.hpc.osc.edu``
#. ``https://ondemand-dev.hpc.osc.edu/oidc``
#. ``https://ondemand-dev.hpc.osc.edu``

#. Scroll to bottom and click "Save"

#. Finally, get the client secret to use with OnDemand installation:

#. Select the "Credentials" tab of the "Client" you are viewing i.e. "Clients >> webdev07.hpc.osc.edu"
#. Select the "Credentials" tab of the "Client" you are viewing i.e. "Clients >> ondemand-dev.hpc.osc.edu"
#. Copy the value for "secret" for future use in this tutorial (and keep it secure).

@@ -1,9 +1,8 @@
Listen 8443
<VirtualHost *:8443>
ServerName webdev07.hpc.osc.edu
<VirtualHost *:443>
ServerName ondemand-idpdev.hpc.osc.edu

ErrorLog "logs/webdev07.hpc.osc.edu_keycloak_error_ssl.log"
CustomLog "logs/webdev07.hpc.osc.edu_keycloak_access_ssl.log" combined
ErrorLog "logs/keycloak_error_ssl.log"
CustomLog "logs/keycloak_access_ssl.log" combined

SSLEngine On
SSLCertificateFile "/etc/pki/tls/certs/webdev07.hpc.osc.edu.crt"
@@ -19,5 +18,5 @@ Listen 8443
## Request header rules
## as per http://httpd.apache.org/docs/2.2/mod/mod_headers.html#requestheader
RequestHeader set X-Forwarded-Proto "https"
RequestHeader set X-Forwarded-Port "8443"
RequestHeader set X-Forwarded-Port "443"
</VirtualHost>
@@ -16,13 +16,13 @@ installing Keycloak on the same host as OnDemand, which is webdev07.hpc.osc.edu.
Initial Installation Steps
--------------------------

#. Download and unpack Keycloak 4.8.3 (from http://www.keycloak.org/archive/downloads-4.8.3.html)
#. Download and unpack Keycloak 9.0.0 (from https://www.keycloak.org/downloads.html)

.. code-block:: sh
cd /opt
sudo wget https://downloads.jboss.org/keycloak/4.8.3.Final/keycloak-4.8.3.Final.tar.gz
sudo tar xzf keycloak-4.8.3.Final.tar.gz
sudo wget https://downloads.jboss.org/keycloak/9.0.0/keycloak-9.0.0.tar.gz
sudo tar xzf keycloak-9.0.0.tar.gz
#. Add keycloak user and change ownership of files
@@ -42,14 +42,14 @@ Initial Installation Steps

.. code-block:: sh
sudo chown keycloak: -R keycloak-4.8.3.Final
sudo chown keycloak: -R keycloak-9.0.0
#. Restrict access to keycloak-4.8.3.Final/standalone, which will contain
#. Restrict access to keycloak-9.0.0/standalone, which will contain
sensitive data for the Keycloak server

.. code-block:: sh
cd keycloak-4.8.3.Final
cd keycloak-9.0.0
sudo -u keycloak chmod 700 standalone
@@ -60,13 +60,13 @@ Initial Installation Steps
sudo yum install java-1.8.0-openjdk-devel
#. Added 'admin' to '/opt/keycloak-4.8.3.Final/standalone/configuration/keycloak-add-user.json', (re)start server to load user.
#. Added 'admin' to '/opt/keycloak-9.0.0/standalone/configuration/keycloak-add-user.json', (re)start server to load user.

If you are not already there:

.. code-block:: sh
cd /opt/keycloak-4.8.3.Final
cd /opt/keycloak-9.0.0
Generate a password to use for the admin user:

@@ -84,7 +84,7 @@ Initial Installation Steps
.. code-block:: sh
sudo -u keycloak ./bin/jboss-cli.sh 'embed-server,/subsystem=undertow/server=default-server/http-listener=default:write-attribute(name=proxy-address-forwarding,value=true)'
sudo -u keycloak ./bin/jboss-cli.sh 'embed-server,/socket-binding-group=standard-sockets/socket-binding=proxy-https:add(port=8443)'
sudo -u keycloak ./bin/jboss-cli.sh 'embed-server,/socket-binding-group=standard-sockets/socket-binding=proxy-https:add(port=443)'
sudo -u keycloak ./bin/jboss-cli.sh 'embed-server,/subsystem=undertow/server=default-server/http-listener=default:write-attribute(name=redirect-socket,value=proxy-https)'
Or you can use a config.cli file that contains these commands. We have
@@ -116,7 +116,7 @@ Start Keycloak Server
Type=idle
User=keycloak
Group=keycloak
ExecStart=/opt/keycloak-4.8.3.Final/bin/standalone.sh -b 0.0.0.0
ExecStart=/opt/keycloak-9.0.0/bin/standalone.sh -b 0.0.0.0
TimeoutStartSec=600
TimeoutStopSec=600
@@ -163,38 +163,29 @@ Place Apache in front of Keycloak
Add ``/opt/rh/httpd24/root/etc/httpd/conf.d/ood-keycloak.conf``, making changes
for the appropriate SSL certificate locations. Notice we are proxying
``https://webdev07.hpc.osc.edu:8443`` to ``http://localhost:8080`` which is the default
``https://ondemand-idpdev.hpc.osc.edu`` to ``http://localhost:8080`` which is the default
port the Keycloak webserver runs as.
.. literalinclude:: example-keycloak-apache.conf
You may need to modify iptables to open up access to Keycloak the same way
that you did so with port 80 and 443 for OnDemand:
.. code-block:: sh
sudo iptables -I INPUT -p tcp -m multiport --dports 8443 -m comment --comment "08443 *:8443" -j ACCEPT
.. note::
We can use the same host because Keycloak properly scopes all cookies it sets to the
realm. For example, if I have a realm called "ondemand", then the Keycloak login
page will be at ``https://idp.osc.edu/auth/realms/ondemand/protocol/openid-connect/auth``
page will be at ``https://ondemand-idpdev.hpc.osc.edu/auth/realms/ondemand/protocol/openid-connect/auth``
and cookies set during authentication will be set with the path ``/auth/realms/ondemand``,
including ``KEYCLOAK_SESSION``, ``KEYCLOAK_STATE_CHECKER``,
``KEYCLOAK_IDENTITY``, and ``KC_RESTART``.
#. Now you should be able to access Keycloak: ``https://webdev07.hpc.osc.edu:8443``
#. Now you should be able to access Keycloak: ``https://ondemand-idpdev.hpc.osc.edu``
Differences if installing Keycloak on separate host
---------------------------------------------------
When installing Keycloak on a separate host, the difference between this
tutorial would be:
#. throughout the rest of the tutorial replace ``https://webdev07.hpc.osc.edu:8443`` with the keycloak host
#. use a different Apache config, listening instead on 443 instead of 8443 and
proxying that to Keycloak
#. throughout the rest of the tutorial replace ``https://ondemand-idpdev.hpc.osc.edu`` with the keycloak host
#. possibly use Apache 2.4 default distribution instead of software collections,
meaning that configuration would be at /etc/httpd/conf.d/ instead of
/opt/rh/httpd24/root/etc/httpd/conf.d/ and starting the
ProTip! Use n and p to navigate between commits in a pull request.
You can’t perform that action at this time.