Unit 5: Web application authentication and authorisation
********************************************************

**Prerequisites**:

* Unit 3: User management and Kerberos authentication

* Unit 4: Host-based access control (HBAC)

You can configure many kinds of applications to rely on FreeIPA's
centralised authentication, including web applications.  In this unit
you will configure the Apache web server to use Kerberos
authentication to authenticate users, PAM to enforce HBAC rules, and
"mod_lookup_identity" to populate the request environment with user
attributes.

All activities in this unit take place on "client" unless otherwise
specified.  **Access the host via ``vagrant ssh client``** to ensure
you have "sudo" access.

The demo web application is trivial.  It just reads its request
environment and responds in plain text with a list of variables
starting with the string ""REMOTE_"".  It should be up and running
already:

   [client]$ curl http://client.ipademo.local
   NOT LOGGED IN

   REMOTE_* REQUEST VARIABLES:

     REMOTE_ADDR: 192.168.33.20
     REMOTE_PORT: 34356


Create a service
================

Create a *service* representing the web application on
"client.ipademo.local".  A service principal name has the service type
as its first part, separated from the host name by a slash, e.g.
"HTTP/www.example.com".  The host part must be a host enrolled in
FreeIPA.

You must be getting the hang of FreeIPA by now, so I'll leave the rest
of this step up to you.  (It's OK to ask for help!)


Retrieve Kerberos keytab
========================

The service needs access to its Kerberos key in order to authenticate
users.  Retrieve the key from the FreeIPA server and store it in a
*keytab* file (you will need a TGT for "admin"):

   [client]$ ipa-getkeytab -p HTTP/client.ipademo.local -k app.keytab
   Keytab successfully retrieved and stored in: app.keytab

We also have to move the file, change its ownership and apply the
proper SELinux labels to the keytab file so that the Apache process
which runs under the confined "apache" user may read it:

   [client]$ sudo mv app.keytab /etc/httpd
   [client]$ sudo chown apache:apache /etc/httpd/app.keytab
   [client]$ sudo restorecon /etc/httpd/app.keytab


Enable Kerberos authentication
==============================

In this section we will use mod_auth_gssapi to enable Kerberos
Negotiate / SPNEGO authentication for a web application.

The Apache configuration for the demo application lives in the file
"/etc/httpd/conf.d/app.conf".  Update the configuration (use "sudo vi"
or "sudo nano") to enable Kerberos authentication:

   <VirtualHost *:80>
     ServerName client.ipademo.local
     WSGIScriptAlias / /usr/share/httpd/app.py

     <Location />
       AuthType GSSAPI
       AuthName "Kerberos Login"
       GssapiCredStore keytab:/etc/httpd/app.keytab
       Require valid-user
     </Location>

     <Directory /usr/share/httpd>
       <Files "app.py">
         Require all granted
       </Files>
     </Directory>
   </VirtualHost>

When the configuration is in place, restart Apache:

   [client]$ sudo systemctl restart httpd

To test that Kerberos Negotiate authentication is working, "kinit" and
make a request using "curl":

   [client]$ kinit bob
   Password for bob@IPADEMO.LOCAL:

   [client]$ curl -u : --negotiate http://client.ipademo.local/
   LOGGED IN AS: bob@IPADEMO.LOCAL

   REMOTE_* REQUEST VARIABLES:

     REMOTE_ADDR: 192.168.33.20
     REMOTE_USER: bob@IPADEMO.LOCAL
     REMOTE_PORT: 42499

The "REMOTE_USER" variable in the request environment indicates that
there is an authenticated user, and identifies that user.


Populating request environment with user attributes
===================================================

Applications need to know more than just the username of a logged-in
user.  They want to know the user's name, to send mail to their email
address and perhaps to know their group memberships or other
attributes.  In this section, we will use mod_lookup_identity to
populate the HTTP request environment with variables providing
information about the authenticated user.

"mod_lookup_identity" retrieves user attributes from SSSD (via D-Bus).
Edit "/etc/sssd/sssd.conf"; enable the SSSD "ifp" *InfoPipe*
responder, permit the "apache" user to query it, and configure the
attributes that you want to expose.  Add the following configuration
to "sssd.conf":

   [domain/ipademo.local]
   ...
   ldap_user_extra_attrs = mail, givenname, sn

   [sssd]
   services = nss, sudo, pam, ssh, ifp
   ...

   [ifp]
   allowed_uids = apache, root
   user_attributes = +mail, +givenname, +sn

Restart SSSD:

   [client]$ sudo systemctl restart sssd

If you had not added an email address to your users when you created
them, you will need to empty the SSSD cache:

   [client]$ sudo sss_cache -E

You can test the SSSD InfoPipe directly via the "dbus-send" utility:

   [client]$ sudo dbus-send --print-reply --system \
       --dest=org.freedesktop.sssd.infopipe /org/freedesktop/sssd/infopipe \
       org.freedesktop.sssd.infopipe.GetUserAttr string:alice array:string:mail
   method return time=1528050430.867333 sender=:1.147 -> destination=:1.150 serial=5 reply_serial=2
      array [
         dict entry(
            string "mail"
            variant             array [
                  string "alice@ipademo.local"
               ]
         )
      ]

Now update the Apache configuration to populate the request
environment.  The "LookupUserXXX" directives define the mapping of
user attributes to request environment variables.  Multi-valued
attributes can be expanded into multiple variables, as in the
"LookupUserGroupsIter" directive.  Do not forget the "LoadModule"
directive at the top!

   LoadModule lookup_identity_module modules/mod_lookup_identity.so

   <VirtualHost *:80>
     ServerName client.ipademo.local
     WSGIScriptAlias / /usr/share/httpd/app.py

     <Location />
       AuthType GSSAPI
       AuthName "Kerberos Login"
       GssapiCredStore keytab:/etc/httpd/app.keytab
       Require valid-user

       LookupUserAttr mail REMOTE_USER_MAIL
       LookupUserAttr givenname REMOTE_USER_FIRSTNAME
       LookupUserAttr sn REMOTE_USER_LASTNAME
       LookupUserGroupsIter REMOTE_USER_GROUP
     </Location>

     ...
   </VirtualHost>

Default SELinux policy prevents Apache from communicating with SSSD
over D-Bus.  Set "httpd_dbus_sssd" to "1":

   [client]$ sudo setsebool -P httpd_dbus_sssd 1

Restart Apache:

   [client]$ sudo systemctl restart httpd

Now make another request to the application and observe that user
information that was injected into the request environment by
"mod_lookup_identity" is reflected in the response:

   [client]$ curl -u : --negotiate http://client.ipademo.local/
   LOGGED IN AS: alice@IPADEMO.LOCAL

   REMOTE_* REQUEST VARIABLES:

     REMOTE_USER_GROUP_N: 2
     REMOTE_ADDR: 192.168.33.20
     REMOTE_USER_FIRSTNAME: Alice
     REMOTE_USER_LASTNAME: Able
     REMOTE_USER: alice@IPADEMO.LOCAL
     REMOTE_USER_GROUP_2: ipausers
     REMOTE_USER_GROUP_1: sysadmin
     REMOTE_PORT: 42586
     REMOTE_USER_EMAIL: alice@ipademo.local


HBAC for web services
=====================

The final task for this unit is to configure Apache to use FreeIPA's
HBAC rules for access control.  We will use mod_authnz_pam in
conjunction with SSSD's PAM responder to achieve this.

First add an *HBAC service* named "app" for the web application. You
can do this as "admin" via the Web UI or CLI.  **Hint:** the "hbacsvc"
plugin provides this functionality.

Next, add an HBAC rule allowing members of the "sysadmin" user group
access to "app" (on any host):

   [client]$ ipa hbacrule-add --hostcat=all sysadmin_app
   ------------------------------
   Added HBAC rule "sysadmin_app"
   ------------------------------
     Rule name: sysadmin_app
     Host category: all
     Enabled: TRUE

   [client]$ ipa hbacrule-add-user sysadmin_app --group sysadmin
     Rule name: sysadmin_app
     Host category: all
     Enabled: TRUE
     User Groups: sysadmin
   -------------------------
   Number of members added 1
   -------------------------

   [client]$ ipa hbacrule-add-service sysadmin_app --hbacsvcs app
     Rule name: sysadmin_app
     Host category: all
     Enabled: TRUE
     User Groups: sysadmin
     Services: app
   -------------------------
   Number of members added 1
   -------------------------

Next, define the PAM service on "client".  The name must match the
"hbacsvc" name (in our case: "app"), and the name is indicated by the
*name of the file* that configures the PAM stack.  Create
"/etc/pam.d/app" with the following contents:

   account required   pam_sss.so

Finally, update the Apache configuration.  Find the line:

   Require valid-user

Replace with:

   Require pam-account app

Also add the "LoadModule" directive to the top of the file:

   LoadModule authnz_pam_module modules/mod_authnz_pam.so

Once again, we must set a special SELinux boolean to allow
"mod_authnz_pam" to work:

   [client]$ sudo setsebool -P allow_httpd_mod_auth_pam 1

Restart Apache and try and perform the same "curl" request again as
"alice".  Everything should work as before because "alice" is a member
of the "sysadmin" group.  What happens when you are authenticated as
"bob" instead?

This unit is now concluded.  Now that you have mastered web app
authentication, you'll want to configure TLS for your site.  Proceed
to Unit 6: Service certificates.
