133 lines
5.4 KiB
Plaintext
133 lines
5.4 KiB
Plaintext
/***********************************************************************
|
|
*
|
|
* 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.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|