WDamb Documentation

Last updated: Sept. 13, 1999.

What is WDamb?

WDamb is a broker for handling authentication and authorization requests. It is still in development, so the information posted here is subject to change.

The broker takes requests about whether a user is permitted to access a particular service and answers yes or no, optionally supplying extra information about the user if requested.

What do I need to do to send it requests?

You should be providing a service for Columbia community members. We are not yet ready to do third-party access control.

If you want to run Apache-SSL, we have a Solaris 2.5 binary that talks to the broker. Alternatively, we could provide you with the source to the module and you could compile it yourself. (If you are running on a wildly different platform we may need to port the code first; contact us to see about this.)

Apache-SSL and WDamb

You will need to set up the files ca-certs.db and ca-certs.db.idx, which contain the certificate of our CA, so that you can be sure you are sending user's passwords to our broker and not somewhere else. These should go in the same directory as your httpd config files.

You can steal these copies (they are in tar.gz format).

You will also need to add the following to your httpd.conf file:

#CU WDamb configuration 

WdAuthHost wdamb.columbia.edu
WdAuthCACertDB our-conf-dir/ca-certs.db
WdAuthPort 895
WdCertCacheSize 100

where our-conf-dir is the name of the directory where your httpd configuration files live, relative to your server root. So for example, if your server root is /usr/local/lib/www-ssl and your config files live in /usr/local/lib/www-ssl/conf, you should set

WdAuthCertDB conf/ca-certs.db

Finally, you will need to contact us so we can give your host permission to make requests of the broker. Please send contact information for the name of the person administering the server to cert-auth@columbia.edu; we'll call you to deal with any other configuration issues (for example, whether you need access to certain user attributes, what sort of restrictions your service requires, and so on).

The module directives are documented in htdocs/manual/columbia/mod_auth_wd.html in the Columbia-modified Apache distribution. A sample .htaccess file might look like this:

AuthType Basic
AuthName "WdAuth Test"

WdAuthentication

<Limit GET PUT>
require affiliation CUNIX_rad CUNIX_sy
&l;/Limit>

Line 1: AuthType Basic: Type of authentication; only 'Basic' is supported by HTTP 1.0 and 1.1.
Line 2: AuthName "WdAuth Test": Name of authentication 'realm'; this name is shown to the user when he or she is promted to log in by the browser, and it is also used by the browser to keep a list of user passwords and realms they go with. If you have more than one word in realm name you must surround the name with double quotes as shown here.
Line 3: WdAuthentication: Enable authentication via broker for this resource.
Line 4: <Limit GET PUT>: Restrict all GET and PUT requests for this resource.
Line 5: require affiliation CUNIX_rad CUNIX_sy: Restrict access to those users who are in the unix groups rad and sy. These show up in an ldap lookup as values CUNIX_rad and CUNIX_sy, under the field name 'affiliation'.
Line 6: </Limit>: End of limiting directives.

Special features:

If you want to restrict to users based on some other field you need only specify the name as it shows up in LDAP. For example, to restrict to users based on email addresses, use

require mail ariel@columbia.edu [... other values here ]

Writing your own client

Preliminary requirements

Your client needs to use SSL to communicate with the broker.

Sending a request

The broker expects one null-terminated record, which contains the following:

wdvers=<vers>:rule=<rule>:token=<token>:require=<filter>:want=<list>:refreshtime=<time>

The fields in brackets are defined below.

<vers>: is the version of the protocol you are using. This document describes version 1.0; you should use the string "1.0" as the version in your requests.
<rule>: is the name of a rule that we use to do authentication and validation of a user's credentials. Available rule names currently accepted must start with the string 'basic'. We use 'basic-lap' to do kerberos authentication of the user and password, and ldap retrieval of user information.
<token>: the user's name and password separated by a ':' and then b64-encoded
<filter>: a list of requirements the user must meet in order to access the service. Most general is 'require=*' which simply requires the user to have presented a valid token (valid name and password). For services restricted only to the Columbia community, use 'require=(affiliation=CNETrestricted)'.
<list>: a list of user attributes the client wants returned to it; this field can be omitted if you do not need any extra information about the user. If you do want extra information please contact us; the broker will not give out information on a user without explicit permissions set for it to do so.
<time>: the length of time in seconds for the broker to cache information about a user and the user's credentials before it must check 'live' sources again.

So for example, a complete request might look like:

rule=basic:token=am9lOmJsb3QK:require=*:refresh=3600

Receiving a response

The broker responds by sending one line which indicates the result of processing the user credentials and the requires filter. This line is terminated by a null ('\0').

The broker may then send additional lines, each null-terminated, which contain the name of an attribute and a list of values. The values are b64-encoded.

Finally, the broker will send an empty record terminated again by a null. It will then close the connection.

You may get one of the following initial responses from the broker:

200:0 ok valid user permitted to access service.

401:0 user does not match requirements user and password check but user does not satisfy requires filter

401:1 want query forbidden client asked for attributes it is not permitted to see

401:2 validation query forbidden client used token type not permitted

404:0 invalid/nonexistent user no such user or invalid password

501:1 bad request request formatted wrong or missing mandatory fields

NO response (broker closes connection) An irrecoverable error occurred. You could try submitting your request again. If the problem persists, contact us.

Additional documentation

Though now somewhat out of date, you can look at a draft of a paper on the broker.

200:0 ok	valid user permitted to access service.
401:0 user does not match requirements	user and password check but user does not satisfy requires filter
401:1 want query forbidden	client asked for attributes it is not permitted to see
401:2 validation query forbidden	client used token type not permitted
404:0 invalid/nonexistent user	no such user or invalid password
501:1 bad request	request formatted wrong or missing mandatory fields
NO response (broker closes connection)	An irrecoverable error occurred. You could try submitting your request again. If the problem persists, contact us.