/***********************************************************************
*
* Copyright (C) 2006 Novell, Inc. All Rights Reserved.
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; version 2.1
* of the License.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Library Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library; if not, Novell, Inc.
*
* To contact Novell about this file by physical or electronic mail,
* you may find current contact information at www.novell.com.
*
* Author: Juan Carlos Luciani <jluciani@novell.com>
*
***********************************************************************/
/***********************************************************************
*
* README for mod_authn_casa
*
***********************************************************************/
INTRODUCTION
mod_authn_casa is an Apache 2.2 Basic Authentication Provider that
can be configured to validate Basic Credentials carrying CASA
Authentication Tokens.
Clients sending CASA Authentication Tokens as part of the Basic Credentials
will format them in the following manner: "username:CasaAuthenticationToken",
where the username is set to "CasaPrincipal" and the CasaAuthenticationToken
is the token string obtained from the CASA Get Authentication Token API..
CONFIGURATION
To use mod_authn_casa as an authentication provider for a specific location
you must first tell Apache that it must load the module, you do this by
placing the module or a link to the module in the Apache server's modules
folder and by placing the following line in the server's httpd.conf file:
LoadModule authn_casa_module modules/mod_authn_casa.so
The following lines show how Apache is configured to use mod_authn_casa
for authenticating requests issued to mod_example:
<Location /example-info>
SetHandler example-handler
AuthType Basic
AuthName "CASA-Authentication"
AuthBasicProvider casa
Require valid-user
</Location>
The AuthName directive specifies the name of the authentication REALM relayed
by the server to HTTP clients when requesting that the they authenticate using
the Basic Authentication scheme. The AuthName can be used by the HTTP client to
realize that the server is expecting CASA Authentication Token materials.
mod_authn_casa supports the following configuration directives:
UsernameCheck - This is a per-directory or per-location directive which
configures whether or not mod_authn_casa must verify that
the username is set to "CasaPrincipal". Possible values
for this directive are 'on' or 'off'. Default is 'off'.
To enable UsernameChack for a particular location using
CASA Authentication, include the following line inside
the location configuration block:
UsernameCheck on
CLIENT PROGRAMMING NOTES
HTTP Clients sending requests to a location being protected by the CASA
Authentication Provider must obtain an Authentication Token from the CASA
Client for authenticating to the Service identified as the "location" being
accessed in the HTTP Server. In the case of mod_example, the service name
would be "example-info". Once the client obtains an Authentication Token
from the CASA Client it must then include it in the HTTP Basic Authentication
header that it must include in the HTTP Request. The HTTP Basic Authentication
credentials should be in the following form:
Base64("CasaPrincipal":"AuthenticationToken")
SERVER PROGRAMMING NOTES
Apache modules being protected by the CASA Authentication Provider can obtain
the following information about the authenticated identity:
username - This is accessed via the r->user variable or by examining the IdentityId
environment variable associated with the request block. The username is the
user's unique id within the authentication realm. When the authentication realm
is an LDAP database, the username consists of the user's fdn.
Name of the source of identity data (Authentication Realm) - This is accessed by
examining the IdentityDataSourceName environment variable associated with the
request block.
URL to the source of identity data - This is accessed by examining the
IdentityDataSourceUrl environment variable associated with the request block.
Attributes of the authenticated identity - The attributes are set as environment
variables associated with the request block. The environment variable names match
the names of the attributes. The attributes associated with the authenticated
identity and expressed as environment variables are configured at the time that
the service is enabled for CASA Authentication.
Note that environment variables are contained in the r->subprocess_env table.
SECURITY CONSIDERATIONS
CASA Authenticatication Tokens when compromised can be used to either impersonate
a user or to obtain identity information about the user. Because of this it is
important that the tokens be secured by applications making use of them. It is
recommended that the tokens be transmitted using HTTPS.
