granicus.if.org Git - apache-authnz-external/blob - mod_authnz_external/UPGRADE

   1 How to upgrade from mod_auth_external to mod_authnz_external:
   2
   3 (0)  Read the section entitled "Authn / Authz" in the README file.  This will
   4      probably make understanding this new version of the module easier.
   5
   6 (1)  Make sure mod_auth_external is no longer being loaded.  You cannot load
   7      both mod_auth_external and mod_authnz_external without problems.  This
   8      means ensuring that there is no "LoadModule" or "AddModule" line for
   9      mod_auth_external.  You could also remove the mod_auth_external.so file
  10      from the Apache 'modules' directory.
  11
  12 (2)  Install mod_authnz_external as described in the INSTALL file.
  13
  14 (3)  The server-level configuration directives in the httpd.conf file are the
  15      same as before.  There has been no change to the way "AddExternalAuth",
  16      "AddExternalGroup", "AddExternalAuthMethod", and "AddExternalGroupMethod"
  17      work.
  18
  19 (4)  In the per-directory configurations (either in .htaccess files or in a
  20      <Directory> block in httpd.conf) need to include a new directive to tell
  21      mod_auth_basic to use mod_authnz_external for authentication.  For
  22      mod_auth_external, the per-directory configurations normally looked
  23      something this:
  24
  25         AuthType Basic
  26         AuthName <authname>
  27         AuthExternal <keyword>
  28         require valid-user
  29
  30      For mod_authnz_external, you need to add the "AuthBasicProvider" directive.
  31
  32         AuthType Basic
  33         AuthName <authname>
  34         AuthBasicProvider external
  35         AuthExternal <keyword>
  36         require valid-user
  37
  38      The directive "AuthType Basic" tells apache that you want to use the
  39      mod_auth_basic module to do "basic authentiation".  The directive
  40      "AuthBasicProvider external" tells mod_auth_basic to use
  41      mod_authnz_external to check the correctness of passwords.
  42
  43      Note that the "AuthBasicProvider" directive is only needed if you are
  44      using mod_authnz_external for password checking.  If you are using it
  45      only for group checking, then this is not needed.
  46
  47 (5)  If you were using mod_auth_external in a non-authoritative mode, then
  48      your per-directory configuration probably included the directive:
  49
  50         AuthExternalAuthoritative off
  51
  52      This command will no longer work.  If upgrading to Apache 2.2, you
  53      should use one or both of the following commands:
  54
  55         AuthBasicAuthoritative off
  56         GroupExternalAuthoritative off
  57
  58      The "AuthBasicAuthoritative" directive effects password checking, which
  59      is done through mod_auth_basic.
  60
  61      The "GroupExternalAuthoritative" effects only group checking.  That is
  62      if you had both "GroupExternal" directive setting up an external program
  63      for group checking, and an "AuthGroupFile" directive setting up a group
  64      file, then it would control whether the first module to process a
  65      "Require group admin" directive was the only one to run, or whether each
  66      group checker was given a chance to decide if the user was in that group
  67      based on it's group database.
  68
  69      In Apache 2.4, all of this is handled quite differently. I need to
  70      document this.
  71
  72 (6)  If you were using multiple Require directives, the behavior may change
  73      under Apache 2.2.  Suppose you wanted to allow access to user "pete" and
  74      members of the group "admins".  You might have do:
  75
  76         Require group admin
  77         Require user pete
  78
  79      Under Apache 2.0, both of these directives would have been checked by
  80      mod_auth_external, and it would have correctly allowed access if either
  81      of the two conditions were satisfied.  In Apache 2.2, however, only
  82      "Require group" and "Require file-group" directives are checked by
  83      mod_authnz_external.  "Require user" and "Require valid-user" are checked
  84      by mod_authz_user, a standard module that comes with Apache.  How the
  85      two directives interact depends on whether they are authoritative or
  86      not.  mod_authz_user is Authoritative by default, so to get the old
  87      behavior, you will need to do
  88
  89         GroupUserAuthoritative off
  90
  91      Again, in Apache 2.4, all of this is handled quite differently, and this
  92      document needs updating.
  93
  94 (7)  Note that a new type of functionality is available under Apache 2.2 with
  95      mod_authnz_external.  Thanks to mod_authz_owner, you can now do:
  96
  97          Require file-owner
  98      or
  99          Require file-group
 100
 101      The first checks if the name of the authenticated user matches the
 102      name of the unix account that owns the file.  The second checks if,
 103      according to whatever group database has been configured for the
 104      current directory, the currently authenticated user is in a group
 105      with the same name as the Unix group that owns the file.
 106
 107      Normally these are rather strange directives, because normally unix
 108      accounts have no relationship to accounts in whatever database is
 109      being used for http authentication, but for people using 'pwauth'
 110      with mod_authnz_external, these really check if the user has been
 111      authenticated as the unix user who owns the file.
 112
 113      In Apache 2.4, this is the same, except the latter of the two becomes:
 114
 115          Require external-file-group