Web App Authentication/Example setup

In this text we will assume the identity provider used is IPA server and we will look at the setup and modifications that might be needed in typical web application to be able to use these central identities. We will explore how Kerberos authentication can be added, how IPA server-backed host-based access control (HBAC) can be configured for the Kerberos authentication on per-service basis, how the user identity (and its password) in the IPA server can be used for application's login-form validation while preserving application's standard look and feel, and how the application can obtain additional information about the externally-authenticated user.

Example application

Let us assume we have an existing web application which uses HTTP cookie-based sessions to preserve authentication results across request. An example can be found at fedorapeople.org/cgit/adelton/public_git/CGI-sessions.git/tree/?id=start. It is plain CGI application written in Perl. Assuming you have the Apache HTTP Server, perl, and the CGI module installed with command like

Configure it to "live" in /application location (for example, http://wikiapp.example.com/application) via ScriptAlias directive
in /etc/httpd/conf/httpd.conf or in some configuration file in /etc/httpd/conf.d/*.conf:

ScriptAlias /application /var/www/app.cgi

Then restart the Apache HTTP daemon:

service httpd restart

The application when deployed at wikiapp.example.com/application and accessed from browser will show a very simple page:

Application

This is a test application; public view, not much to see.

Log in

You can also use command line tools to test the application:

curl -i http://wikiapp.example.com/application

or locally

curl -i http://$( hostname )/application

The link Log in leads to wikiapp.example.com/application/login which will display a login-form:

Log in to application

Login: [ . . . . . . . . . ]

Password: [ * * * * * * * ]

< Log in >

Back to application

Login-form submission leads back to the page wikiapp.example.com/application/login and upon success (we just test that the password is the login name reversed) it will set HTTP cookie the-test-cookie to contain the name of the user (the cookie value when bob logs in in the example bellow will be ok:bob) and then redirect to the main page:

Logged in as bob

You will be redirected to the home page

Back to application

Application authenticated (bob)

Test application; logged in as user bob. There is much more content for authenticated users. There is much more content for authenticated users. There is much more content for authenticated users. There is much more content for authenticated users. There is much more content for authenticated users. There is much more content for authenticated users. There is much more content for authenticated users. There is much more content for authenticated users. There is much more content for authenticated users. There is much more content for authenticated users.

Log out

Real applications will probably do a lookup of the user and password in the database and create session record in the database and store that session's key in the cookie. Or at the least they would store the identity of the user in the cookie together with some cryptographical signature to prevent user to impersonate someone else. Remember: this is just an example to show additional setups later.

Clicking Log out will just set the cookie value to xx meaning no active user, and redirect back to wikiapp.example.com/application.

Enrolling the web machine to IPA server

We assume that the machine on which the wikiapp is hosted is enrolled to an IPA server. The commands

yum install /usr/sbin/ipa-client-install -y
ipa-client-install

can be used to achieve the enrollment -- ipa-client-install will configure sssd and other components of the system to know about the IPA server. It will ask questions about the name of the IPA server and other parameters, or you can explore its --help option and man page.

Kerberos

The IPA server serves as a Kerberos Key Distribution Center, among others. Users that have access to the Kerberos server for the example.com domain can use

kinit

to obtain their ticket-granting ticket which can then be used by applications to obtain tickets to authenticate against other services. Our goal will be to Kerberize wikiapp.example.com/application. In typical setup, the tickets are in a realm matching the domain name, usually written in upper case, in our case EXAMPLE.COM.

We will need Apache module mod_auth_gssapi or mod_auth_kerb installed and configured. We will also need to obtain keytab from the IPA server for our HTTP service. On the IPA server:

kinit admin # or other user with permissions to create new service for wikiapp.example.com
ipa service-add HTTP/wikiapp.example.com

Successful Negotiate

We can restart the Apache now

service httpd restart

and try to access the login page either from browser or via command line

curl -i --negotiate -u : http://$( hostname )/application/login

When the user has valid Kerberos ticket in the EXAMPLE.COM realm and clicks the Log in link leading to wikiapp.example.com/application/login, mod_auth_gssapi/mod_auth_kerb will return with status 401 and header WWW-Authenticate: Negotiate. The browser will try to obtain the ticket for HTTP/wikiapp.example.com@EXAMPLE.COM and resubmit the request with appropriate Authorization header. In the /var/log/httpd/access_log will see that we have authenticated correctly

However, the application will still show the same login form, rather than understanding that the user has already authenticated using Kerberos. To achieve that, we need to change the application to understand the REMOTE_USER environment variable which is set by Apache authentication modules when their authentication attempt passes: trust REMOTE_USER, apply with curl using

With the above changes in place, application will consult the REMOTE_USER environment variable and it will skip any attempt of internal validation of login and password and just consider the user logged-in:

Logged in as bob@EXAMPLE.COM

You will be redirected to the home page

Back to application

Application authenticated (bob@EXAMPLE.COM)

Test application; logged in as user bob@EXAMPLE.COM. There is much more content for authenticated users. There is much more content for authenticated users. [...]

Log out

No login form will be shown.

Failed Negotiate

Note the ErrorDocument client-side redirect to /application/login2 -- it is there as a fallback to the login form in case the user has no valid ticket:

With the application now, the wikiapp.example.com/application/login2 will display

Application

This is a test application; public view, not much to see.

Log in

This is not right. Clearly, the application does not know that the login2 location is also supposed to display a login page.

For the fallback to work, we need to make sure wikiapp.example.com/application/login2 is location for the same logon-form logic as wikiapp.example.com/application/login. In our case, we just modify the application to consider any path starting with login as login application: support login2, apply with curl using

In real applications, this part can either go to the application code, application/framework mapping, or to the Apache configuration.

With the change applied, if the browser cannot obtain the ticket, it will just show the content of the document with we've configured with the ErrorDocument directive to be a redirect to /application/login2. After a short message

Kerberos authentication did not pass.

the login form will be displayed from wikiapp.example.com/application/login2 and the user can log in as usual, with their login and password.

Additional yum repo

The following sections of this document describe software which is already part of Fedora and RHEL/CentOS 6. The upstream repositories with packages for popular OSes (namely RHEL 7) are at http://copr.fedoraproject.org/coprs/adelton/identity_demo/ -- click on the adelton-identity_demo*.repo link in the line matching your OS and version and store the .repo file in /etc/yum.repos.d.

You can also retrieve the .repo file via curl: for example, for RHEL 7:

or perhaps indirectly from host/user-group, the Kerberos authentication will still fail and logon form will be shown.

Access control with user groups using pam_access

The host-based access control (HBAC) in IPA can control access of users to services running on various hosts. The HBAC rules can use user groups in IPA. Sometimes, the admin might not want to manage the access centrally and might prefer to locally set the list of groups that can access the web application. Eventually, sssd will provide way to set up access control on per-PAM service basis. For now, with mod_authnz_pam, we have all the PAM modules at our disposal, including pam_access. For example, adding line

account required pam_access.so accessfile=/etc/http-access.conf

to /etc/pam.d/wikiapp will enable the access control using file /etc/http-access.conf. If the content of that file is

+ : (wiki-group-test) : ALL
- : ALL : ALL

only users in the wiki-group-test group will be granted access. Both local groups from /etc/group and the IPA-managed groups are considered for this access control check.

External identities for login form

With module mod_intercept_form_submit, the same PAM service wikiapp that we used to run access check for the Kerberos authentication can be used to silently try authentication against the IPA server (via PAM and sssd) whenever the user submits the login form. The module needs to be installed

With /etc/pam.d/wikiapp in place and mod_intercept_form_submit, the application will see REMOTE_USER populated whenever the authentication via the PAM stack succeeds.

If it fails, the application will still have a chance to run local authentication.

Test with ipa hbacrule-remove-user and ipa hbacrule-add-user that the authentication using the mod_intercept_form_submit, observes the access control just like mod_authnz_pam does for Kerberos. In fact, mod_intercept_form_submit is calling mod_authnz_pam internally.

Note that we configure the module on /application/login2 because with Kerberos on /application/login, that is where the for submission will run. If we omitted the Kerberos configuration, we would want mod_intercept_form_submit configured on /application/login.

Storing external users in internal databases

Our example CGI script does not use any database and it simulates the users by accepting any reasonable login name and matching password. For externally authenticated users, it accepts whatever value is set in REMOTE_USER.

Real application would have users stored in the database and even for externally authenticated users, it will probably want to store these external users in its database, albeit with some "external" flag, for referential integrity to work. So in reality, the change of application code to process REMOTE_USER would probably create the user in the database first and then create session for this new user.

Additional attributes

Applications expect not just the login name of a user to be present -- they might need their email address to send them notifications, they might want to know their full name just to make the user interface less cryptic. When the user is created and stored by the application, the application has full control over what fields (attributes) it will require to be present -- without it the user record will not be allowed.

However, when the user authentication happens against external identity provider, asking user for their email address and name that they already have correctly filled in the central server might not be ideal. It would not only slow user's work down, it could also lead to inconsistencies, and in some enterprises, only dedicated departments can modify the personnel information in the central identity store.

With module mod_lookup_identity and sssd-dbus package, sssd can retrieve additional attributes from the IPA server and make them available to the to the module and thus to the application during authentication using Apache module.

In our simple application, we just store the values in the cookie to show later.

Application authenticated (Robert Puk (bob: bob@example.com))

Test application; logged in as user Robert Puk (bob@example.com). There is much more content for authenticated users. There is much more content for authenticated users. There is much more content for authenticated users. There is much more content for authenticated users. There is much more content for authenticated users. There is much more content for authenticated users. There is much more content for authenticated users. There is much more content for authenticated users. There is much more content for authenticated users. There is much more content for authenticated users.

Log out

Please note that the additional attributes are retrieved by Apache modules and it does not matter if the user has authenticated using Kerberos (mod_auth_gssapi or mod_auth_kerb) or via mod_intercept_form_submit -- the mod_lookup_identity module takes the authentication result and uses it to get the values.

Real applications can use these attributes from central identity provider to have the same set of information as their internal users, typically storing the attributes in their internal user databases when populating the record for the externally authenticated users. Typical list of attributes that the applications might be interested in is proposed at http://www.freeipa.org/page/Environment_Variables#Proposed_Additional_Variables.

Application-level roles

Web applications make it very easy to handle and add new users but most applications will sooner or later need to start distinguishing different roles for different users. As with user identities themselves, applications will typically store them in a database, and as with external authentication, even application-level roles may need to be partially managed.

In IPA server, the easiest way to assign quality to a user is via groups. The mod_lookup_identity module makes it easy to retrieve group membership into REMOTE_USER_GROUPS or similar environment variable. The group membership can then be expanded into roles that the applications uses. Admin of the application will need to set the initial mapping of groups to roles but after then, upon each login, roles can be updated from the central identity provider.

That means, that if a company hires new sysadmin and they set their group membership in sysadmin's group correctly in the central IPA server, system management tools across the company can retrieve this group memebership on the fly and make the new employee no only able to log in to the system management tools but also assign correct roles and permissions to them.

Passing information to applications

In this example application, we have used CGI script and environment variables that are populated by Apache modules and then inherited by the CGI script when it is forked and run.

In real deployments, CGI scripts are rarely used these days, primarily for performance reasons. Typically, the applications are either loaded in the context of the Apache server, or they run in daemon fashion in parallel to Apache and control is handed over to them over sockets or via other means.

Many of these frameworks will pass environment variables behind the scenes and applications can consult them just like they would in the CGI scenario.

In some cases, only the REMOTE_USER information (or the internal value r->user of the Apache request) is passed by the framework and additional attributes need to be handled separately. For example, when mod_proxy_ajp is used to hand over the request from Apache to tomcat, only REMOTE_USER and then environment variables that start with AJP_ are passed. So the environment variables populated by mod_lookup_identity need to be prefixed with AJP_. In Apache configuration:

In case of deployments that use mod_proxy_balancer where no out-of-band information passing is available, headers of the HTTP request can be used. Of course, caution is needed to properly clear any headers of the same name in the incoming HTTP request to prevent the end user from breaching the authentication/access control:

On the application end, in case of CGI script, the incoming HTTP request headers are presented as environment variables prefixed with HTTP_, with dashes turned into underscores, so the application code would need to be along the lines of

Conclusion

On a simple example CGI application, we have shown how relatively small changes to the application code can make use of the REMOTE_USER environment variable and additional variables with extended attributes, making it possible to use central identity provider like IPA server for Kerberos and login/password authentication. We have also shown the configuration of mod_auth_gssapi/mod_auth_kerb and of new modules, mod_authnz_pam, mod_intercept_form_submit, and mod_lookup_identity can can together form flexible solution to meet the needs of web applications deployed in environments with central user management.

In the section below, links to changes that went to real-life projects to make some of these changes possible are shown.