Modifying Apache directives for authentication

Centrify for Apache authentication and access control is handled through extensions to the standard Apache directives that appear in the Apache httpd.conf or apache2.conf and .htaccess files.

Note:   On some platforms, httpd.conf is apache2.conf, instead. Your platform has one or the other, and they serve the same purpose.

Once the Centrify for Apache authentication module is loaded into the Apache server, it enables the following extensions to the Apache directives:

Extensions to Apache Directives
Directive Settings
AuthName

The name of the domain (realm) under which Basic authentication is performed. This string is used only by the browser in prompting the user for a user name and password.

If the name you want displayed contains blank spaces, you must use quotes in the directive. For example:

AuthName “Zen Communications”
AuthType

The authorization type must be specified as CENTRIFYDC, in all uppercase letters.

CheckPamFirst

Set true to authenticate the user using PAM first and then Active Directory. This directive is used only if EnableBasicAuth and EnablePamAuther are both true.

The default value, if you do not set this directive, is false.

CheckpwdLoggerName

Set to the logger name for the program set in CheckpwdPath to use for logging messages about PAM authentication. This directive is used only if EnableBasicAuth and EnablePamAuther are both true.

If not set, the default is

com.centrify.dc.apache.checkpwd
CheckpwdPath

Set to the full path to the program to call to authenticate users when EnablePamAuth is true. If not set the default is

/usr/share/centrifydc/apache/bin/checkpwd.
CustomAttributes

Set to a list of LDAP attributes, separated by white space, to fetch for the authenticated user.

The values of the given user's LDAP attributes (if non-empty) will be set in environment variables (if SetAuthUserInfo is set to env) or in HTTP headers (if SetAuthUserInfo is set to httpheaders). The form for environment variables is:

CUSTOM_ATTR_attr-name = value

The form for HTTP headers is:

HTTP_CUSTOM_ATTR_attr-name = value

For example, if you enter the following attributes, when SetAuthUserInfo is set to env (assuming a username of webuser1):

CustomAttributes   cn displayName samAccountName

the following environment variables are set:

CUSTOM_ATTR_cn = webuser1
CUSTOM_ATTR_displayName = webuser1
CUSTOM_ATTR_sAMAccountName = webuser1
EnableBasicAuth

Set to true to enable Basic authentication, false otherwise.

The default value, if you do not set this directive, is false.

EnableKerberosAuth

Set to true to enable Kerberos authentication, false otherwise.

The default value, if you do not set this directive, is false.

EnableNtlmAuth

Set to true to enable NTLM authentication, false otherwise.

The default value, if you do not set this directive, is false.

EnablePamAuth

Set to true to enable basic username and password authentication using PAM, false otherwise.

The default value, if you do not set this directive, is false.

EnableKerberosReprompt

Set to true to enable reprompting the client with NTLM or Basic authentication after a Kerberos validation failure so the client can authenticate as a different user using NTLM or Basic if the Kerberos ticket is invalid. The directives, EnableNtlmAuth and EnableBasicAuth must also be set to true to enable NTLM and Basic reprompting.

Set to false to disable the server from letting the client attempt login using a different method (NTLM or Basic) when the Kerberos ticket is invalid.

The default, if you do not set this directive, is to reprompt (true).

EnableNtlmReprompt

Set to true to enable reprompting the client with Basic authentication after an NTLM validation failure so the client can authenticate as a different user using Basic. The directive, EnableBasicAuth must also be set to true to enable Basic reprompting.

Set to false to disable the server from letting the client attempt login using a different method (Basic) when NTLM authentication fails.

The default, if you do not set this directive, is to reprompt (true).

EnableBasicReprompt

Set to true to enable reprompting the client with Basic authentication again after a Basic validation failure so the client can authenticate as a different user but still using Basic. The directive, EnableBasicAuth must also be set to true to enable Basic reprompting.

Set to false to disable the server from letting the client attempt login again.

The default, if you do not set this directive, is to reprompt (true).

EnableReAuth

Set to true to enable reprompting the client when authorization fails. Use the directive, Require, to specify a list of authorized users or groups.

Set to false to disable the server from reprompting the client for authorization.

The default, if you do not set this directive, is not to reprompt (false).

HttpHeaderPrefix 

Set to PREFIX to configure a prefix to be added to the HTTP headers to avoid possible conflicts with other proprietary HTTP headers on the server. This directive is ignored if SetAuthUserInfo is not set to httpheader.

IdentityType

Set to one of the following key words to identify the type of authenticated name to set for REMOTE_USER:

  • UPN — Sets REMOTE_USER to the authenticated user’s Universal Principal Name (UPN). This is the default if you do not specify an IdentityType.
  • SAMAccountName — Sets REMOTE_USER to the authenticated user’s SAMAccountName (the short name).
  • CommonName — Sets REMOTE_USER to the authenticated user’s CN attribute.
  • FromInput — Sets REMOTE_USER to the user name as entered by the user in Basic user name and password authentication. For Kerberos and NTLM authentication, REMOTE_USER is set to the authenticated user’s UPN.
  • Custom:attribute-name — Sets REMOTE_USER to the authenticated user's attribute-name Active Directory attribute. For example,

    IdentityType Custom:mail

  • PAM — Sets REMOTE_USER to the user name as entered by the user in PAM user name and password authentication.

    If EnablePamAuth is true and the user was authenticated by PAM, the IdentityType is set to PAM regardless of what is set in httpd.conf or apache2.conf file or .htaccess.

PamService

If EnablePamAuth is true, you can set this directive to identify the PAM service to use. For example:

/etc/pam.d/passwd

If no service is set, the default is login.

Require option

Set to limit which users and group members have access. If no Require directive is included, all Active Directory or PAM users have access.

The Require syntax you use depends upon the Apache version.

  • Apache 2.0 and 2.2

    Require user userID

    Require group groupID

    Require valid-user

  • Apache 2.4

    Require centrify-dc-user userID [userID]

    Require centrify-dc-group groupID [groupID]

    Require centrify-dc-valid-user

Use the UPN to specify the userID. Use a space to separate multiple user names. For example:

Require centrify-dc-user ray@zen.com star@zen.com

Use the full canonical name to specify the groupID. Use a space to separate multiple group names. If the group name contains a space enclose the full canonical name in double quotation marks. For example:

Require group "zen.com/Users/HR Staff"

Use valid-user to permit access to any authenticated domain user. For example:

Require valid-user

If you are using PAM authentication, the user or group name must be preceded by the Pam: prefix. Directives that start with Pam: are ignored for Active Directory users. For example:

Require centrify-dc-user Pam:<unixuser>
Require centrify-dc-group Pam:<unixgroup>
SetGroupMembership

Set true to get all groups that the user is a member of and set them in the REMOTE_GROUPS environment variable or the HTTP_REMOTE_GROUPS header.

If not set the default is true.

Note: Set to false for faster performance

ReturnStatusForbidden

Set to true to change the return status to Forbidden (error 403) instead of Unauthorized (401) on authorization failure or on final authentication failure.

If not set the default is true.

UseCache

Set to true use the cache in the adclient daemon when checking for user group membership for authorization.

If not set, the default is false.

You can place these directives in either the httpd.conf (or apache2.conf) or .htaccess file, depending on your needs. For example, if you centrally manage the configuration for different directories in the main configuration file, you can add these directives where needed in a single file and maintain them in a single location.

Alternatively, you can provide these directives in separate .htaccess files so that different administrators can set their own directives for the directories they manage without making changes to the main configuration file. If you decide to place the directives in individual .htaccess files, however, you must include the AllowOverride directive in the httpd.conf (or apache2.conf) file, and be sure that this directive is set to All or, at a minimum, set to allow AuthConfig directives.

The following is an example of the Centrify for Apache directives set for a specific directory in the main httpd.conf (or apache2.conf) file:

<Directory “usr/local/apache2/htdocs/sample-dir”>
   AuthType                 CENTRIFYDC
   AuthName                 zen.com
   EnableBasicAuth          true
   EnableKerberosAuth       true
   EnableNtlmAuth           true
   EnableKerberosReprompt   true
   Require                  valid-user
   SetAuthUserInfo          httpheader
</Directory>

The following is an example of the Centrify for Apache directives in a sample .htaccess file for an Apache 2.4 server:

AuthType                  CENTRIFYDC
AuthName                  zen.com
EnableBasicAuth           true
EnableKerberosAuth        true
EnableNtlmAuth            true
EnableKerberosReprompt    true
Require centrify-dc-group zen.com/groups/ApacheGroup
SetAuthUserInfo           httpheader