mod_idcheck apache run-time configuration directives.

These settings can be used in a client webserver that has mod_idcheck.so loaded in. To load in the module place the following somewhere sensible in your apache config files. Note that the file path will depend on which OS you are running.

LoadModule idcheck_module /usr/lib/apache2/modules/mod_idcheck.so

There are two main types of configuration directive. Ones that you use in the main virtual host or server configuration sections and ones that you can use in limit blocks (e.g. <directory> or <location>) to limit access to certain groups of user.</location></directory>

Main apache server config

(i.e. outside of limit blocks like <directory>):</directory>

IdcheckLoginUrl

Arguments: the URL of the idcheck server.

This is normally the login page of the idcheck server. It is the page to which the user will be redirected if they are not presenting a valid idcheck cookie for the website they are trying to get into.

Note that the scope of the registration request cookie (i.e. the cookie domain) is set to the domain of the login_url. So its not possible to run a server with idcheck.foo.bar.example.com. you must run it as idcheck.example.com.

You must ensure that this page is SSL protected, even if the website you are protecting is not as the cookie that is negotiated between the browser and the idcheck server is the most important one.

Example:

IdcheckLoginUrl https://idcheck.example.com/idcheck

IdcheckCheckUrl

Arguments: the URL of the idcheck server.

mod_idcheck.so uses this URL to check cookie requests against the URL of the main server.

This can be non-https... but only if you trust your internal network and the value of the data that you are keeping on the mod_idcheck.so server is not essential. e.g. a large intranet that can be viewed by thousands of people. If security is important here then this needs to be a HTTPs URL.

Example:

IdcheckCheckUrl http://idcheck.example.com/idcheck

IdcheckAllowRequest

Arguments: One or more URL paths.

Allows requests that match this regexp. This can be used to prevent robots.txt, image and favicon.ico requests from generating request cookies.

Example:

IdcheckAllowRequest /robots.txt$ /favicon.ico$

IdcheckNoAccessBehaviour

Argument: Either "server" or a URL.

Redirect to the server page (with argument "server") or to a specified URL (give URL as argument) if authorisation directives (IdcheckAllowData and IdcheckAllowUser) fails.

Example:

IdcheckNoAccessBehavior server

IdcheckRedirectUrl

Argument: a URL.

Forces the idcheck server to redirect elsewhere after authentication. It overrides the default behavior which redirects the user back to the page they were attempting to access.

Example:

   IdcheckRedirectURL http://somewhere.else.com/foo

IdcheckSetEnv

Arguments: VAR REGEXP SUBSTITUTION

This is useful if you want to pass idcheck data to a PHP or CGI script to make use of it. By default. In addition to REMOTE_USER, idcheck also sets a number of IDCHECK_DATAXX variables that are available to the script. This option is a way of providing a nicer environment variable.

Can be used to set additional environment variables based on idcheck authorisation data. Arguments are the variable name, a regular expression and a substitution pattern.

These environment variables can be seen in the standard php info page if it is protected with mod_idcheck.

Example:

IdcheckSetEnv NAME "ldap:cn=(.+)$" "$1"
IdcheckSetEnv MAIL "ldap:attribute=mail: (.+)$" "$1"

IdcheckGuestMode and IdcheckGuestModeUser

Arguments: Boolean (IdcheckGuestMode) and username (IdcheckGuestModeUser).

Setting this option allows anyone in, but tells the webserver that the logged in user is "guest" unless they have already negotiated a cookie and have some other username.

IdcheckGuestModeUser lets you set the username that will be assumed. The username does not have to exist outside of mod_idcheck configuration (though you should probably check that it really doesnt).

Use this to let idcheck assign a fake username (IdcheckGuestModeUser) and permit access to the page if authentication would otherwise fail."),

Note that this directive can be used in combination with a limit block elsewhere on the server that is fully protected and whose contents simply redirect back to the public area. In this case, you can present a page and also supply a log in link that just links to the fully protected area. Users will be "guest" when they arrive and after using the link will have their proper username. Applications can be adapted to make use of this.

Example:

IdcheckGuestMode on
IdcheckGuestModeUser guest

IdcheckBindAddress

Argument: IPv4 or IPv6 address.

The local IP address that is used to connect to the idcheck server. This is only useful if your server has multiple ethernet interfaces or ip aliases.

IdcheckBindAddress 192.168.99.1

IdcheckDebug

Argument: Boolean on/off.

Turns on debug mode (and fills your error log up).

Example:

IdcheckDebug on

IdcheckSecure

Argument: Boolean on/off.

Lies to the apache server. Set this to true if your website is operating over HTTPS but the SSL offloading is done by a load balancer elsewhere and the apache server itself is only running on HTTP. It adds the secure flag to the cookies if the servers are running over plain HTTP. If the apache server is running as HTTPS this option is not required as mod_idcheck auto detects that and sets the secure flags in that case.

Example:

IdcheckSecure on

IdcheckCertificateAuthority

Arguments: file path.

This is a file holding one or more certificates to verify the idcheck server with when mod_idcheck checks cookies over https (in IdcheckCheckUrl). By default mod_idcheck uses curl and so will use a libcurl cacert bundle (see the libcurl option CURLOPT_CAINFO). Setting this will set an alternative CA and the default libcurl bundle will not be used. It is only used if IdcheckCertificateVerify is set. PEM format works, others might too.

Example:

IdcheckCertificateAuthority /etc/ssl/certs/MyOwnCA.pem

IdcheckCertificateVerify

Arguments: Boolean on/off.

Set to on if you want to verify the SSL certificates presented by the idcheck server when mod_idcheck checks its cookies. By default, certs will be checked against the default CA bundle provided with libcurl on your operating system. If you want to override this then see IdcheckCertificateAuthority directive.

Example:

IdcheckCertificateVerify on

Directives that can be used inside a limit block.

Idcheck

Argument: Boolean on/off

Switch on idcheck for a limit block.

Example:

<Directory>
  Idcheck on
  ...
<Directory>

IdcheckAllowUser

Arguments: one or more usernames.

Permit specified users by their username. Multiple usernames can be specified on a single directive or in multiple directives.

Example:

IdcheckAllowUser martin kieran tom terry

IdcheckAllowData

Arguments: multiple idcheck data strings.

The idcheck server, when it has checked a cookie will return data about the user to
the webserver that is requesting the check. This will include a set of strings that may specify things like the department the user is working for. These strings can be viewed
on the idcheck-info url when logged in.

This directive permits users with the specified data authorisation strings access to a resource.

Multiple arguments are ANDed. Multiple directives are ORed. Arguments can be prefixed with a ! to NOT them.

This authorisation list will be passed down to any paths below the one where it is defined. Sometimes this is not what is wanted. See IdcheckClearAllowLists.

Example:

# Permit IT staff and physics students only.
IdcheckAllowData "ldap:unit=IT" "ldap:container=ou=staff"
IdcheckAllowData "ldap:unit=Physics" "ldap:container=ou=students"

IdcheckAllowRegex

Arguments: Multiple regular expressions.

Similar to IdcheckAllowData except that it uses a perl compatible regular expression.

Note that these directives cannot be ORed on separate lines like IdcheckAllowData.

Example:

# allow physics or maths staff in.
IdcheckAllowRegex "^ldap:unit=(Physics|Maths)$" "^ldap:container=ou=staff$"

IdcheckClearAllowLists

Arguments: none.

Use this to clear any idcheck access control lists already present at this location. Use this if you need to tighten access controls.

Example:

<Directory /var/www/intranet>
  ...
  # Permit IT staff and physics students only.
  IdcheckAllowData "ldap:unit=IT" "ldap:container=ou=people"
  IdcheckAllowData "ldap:unit=Physics" "ldap:container=ou=students"
  ...
</Directory>

<Directory /var/www/intranet/staff-only>
  ...
  # Permit IT staff only.
  IdcheckClearAllowLists
  IdcheckAllowData "ldap:unit=IT" "ldap:container=ou=people"
  ...
</Directory>

IdcheckUserRequestHeader

Arguments: A HTTP header.

This can be used to set a custom header in the input table to contain the username. Some web applications might want this.

Example:

<Directory ...>
   Idcheck on
   IdcheckUserRequestHeader x-webobjects-remote-user
   ...
</Directory>

Deprecated options:

Do not use these options unless you know what you are doing.

IdcheckCheckIP

Was used in a very old version of the idcheck protocol. The source IP address which will be allowed to check the cookies. This is probably the primary IP address of the origin webserver. Set this only if you want to use trusted request cookies - which you probably do not.

FIN.