Improve howto for setting up remote user

doc/howto/mod_auth_openidc_feide.rst

@@ -2,6 +2,58 @@
 Authenticating with the apache plugin `mod_auth_openidc <https://github.com/zmartzone/mod_auth_openidc>`_ and Feide
 ===================================================================================================================
 
+Enabling the plugin on Debian
+=============================
+
+First check if the plugin is already installed and enabled::
+
+    $ sudo apache2ctl -M | grep openid
+      auth_openidc_module (shared)
+
+If it is, go straight to `Configuration`_.
+
+If not:
+
+Install the plugin::
+
+    $ sudo apt install libapache2-mod-auth-openidc
+
+This should create the following files::
+
+    /etc/apache2/mods-available/auth_openidc.conf
+    /etc/apache2/mods-available/auth_openidc.load
+    /etc/apache2/mods-enabled/auth_openidc.conf
+    /etc/apache2/mods-enabled/auth_openidc.load
+
+Enable with::
+
+    $ sudo a2enmod auth_openidc
+
+Disable with::
+
+    $ sudo a2dismod auth_openidc
+
+Feide Kundeportal configuration
+===============================
+
+You will need to ask somebody with the correct access-rights at `Feide
+kundeportal <https://kunde.feide.no>`_ for your organization to create an
+OpenID Connect-configuration. Configurations are locked to a specific NAV
+domain name and user group and cannot be shared. If the domainname is updated
+the Feide and Apache2-configurations will need to be updated as well.
+
+The Feide admin will need:
+
+* A name for configuration, we recommend: "NAV: domainname" or "NAV: your organization".
+* An url to redirect to after login, this is the domainname followed by
+  a relative url that is *not served by NAV*. We use ``/oidc`` in this howto.
+
+Also, the ``userid-feide`` scope needs to be turned on at
+*User information > Personal information*.
+
+Apache2 Configuration
+=====================
+
 Apache virtual host configuration::
 
     <Location />
@@ -44,43 +96,73 @@ Apache virtual host configuration::
     </Location>
 
     OIDCProviderMetadataURL https://auth.dataporten.no/.well-known/openid-configuration
-    OIDCClientID XXX
-    OIDCClientSecret YYY
-    OIDCRedirectURI ZZZ/oidc/
+    OIDCClientID SOME-UUID
+    OIDCClientSecret SOME-OTHER-UUID
+    OIDCRedirectURI https://DOMAINNAME/oidc/
     OIDCCryptoPassphrase LONGRANDOMSTRING
-    OIDCOAuthRemoteUserClaim "dataporten-userid_sec"
-    OIDCScope "userid userid-feide openid"
+    OIDCRemoteUserClaim https://n.feide.no/claims/eduPersonPrincipalName
+    OIDCScope "openid userid-feide"
 
-Note the first location block, where two lines need be added to what is already
-there. This locks down the entire site. We haven't found a way with this plugin
-to do it any other way.
+Note the location block ``<Location />``. The "Require"-line replaces any other
+"requires" already there. This locks down the entire site. We haven't found
+a way with this plugin to do it any other way.
 
-The second location block just needs to be a url that is not in use by
-anything else, this is used by the plugin as its edndpoint.
+The second location block (``<Location /oidc>``) just needs to be a relative
+url that is not in use by anything else, this is used by the plugin as its
+endpoint.
 
-The third location block is the url the plugin redirects to after logout.
+The third location block (``<Location /index/logout>``) is the url the plugin
+redirects to after logout.
 
 The remaining location blocks are either public urls (``/doc``, ``/about``),
 parts of NAV that has its own authentication system (``/api``), or must not be
 under the control of the plugin for the web frontend to correctly function
-(``/refresh_session``).
+(``/refresh_session``). If you have added extra pages or apps to the nav-server
+that will not use the NAV auth system you need to mark their urls similarly.
+
+```OIDCClientID`` needs to be set to the fixed generated *client id*, while
+``OIDCClientSecret`` needs to be set to the changeable ``client secret``. Both
+are to be found in `Feide Kundeportal <https://kunde.feide.no>`_.
+
+``OIDCRedirectURI`` is the domain name of the NAV instance as a URI, suffixed
+with the plugin's magic endpoint url, in this case ``/oidc/``. This url needs
+to be registered at the Feide dashboard as a redirect URI under
+*Redirect URI after login*.
 
-In the lines that configure the plugin, **XXX** and **YYY** is generated by
-`Feide at its dashboard <https://dashboard.dataporten.no>`_. **ZZZ** is the
-domain name of the NAV instance, suffixed with the plugin's magic endpoint url.
-The entire url needs to be registered at the Feide dashboard as a redirect URI
-under *Basic info*. Under *Permissions*, the scopes mentioned under
-``OIDCScope`` must be accepted.
-**LONGRANDOMSTRING** is a long, random string without whitespace that can be
-generated by anything.
+``OIDCCryptoPassphrase`` is used as a seed and should be kept secret.
+
+``OIDCOAuthRemoteUserClaim`` is what information will be used as the username.
+The exact claim may change.
+
+``OIDCScope`` must at minimum contain ``"openid userid-feide"``, remember the
+quotes.
+
+NAV configuration
+=================
 
 ``webfront.conf``::
 
     [remote-user]
     enabled = yes
-    varname = HTTP_OIDC_CLAIM_DATAPORTEN_USERID_SEC
+    varname = REMOTE_USER
     logout-url = /oidc/?logout=
     workaround = feide-oidc
+    autocreate = off
+
+"oidc" in the ``logout-url`` points to the same place as the
+``<Location /oidc>``-block in the apache configuration and the redirect URI in
+the Feide dashboard.
+
+By toggling autocreate to "on", users are automatically created on first login
+via OIDC, This is probably not what you want, which is why the  default is
+"off". With it "off" it is necessary to pre-create the users in order to allow
+login.
+
+Gotchas
+=======
+
+When this is in use, local users like "admin" will no longer be available. Therefore, either:
 
-"oidc" in the ``logout-url`` is the same url as the ``oidc``-block in the
-apache configuration and the redirect URI in the Feide dashboard.
+* *before* enabling the plugin create a user that will use OIDC to login then
+  set that user as admin
+* *after* enabling the plugin set a user as admin via the CLI user script, ``navuser``

doc/reference/web_authentication.rst

@@ -21,6 +21,17 @@ Since the password is controlled from a system externally to NAV, the user does
 not have access to change the password from inside NAV. If an account is set to
 invalid in NAV, the user will not be logged in, even if the header is set.
 
+Creating users on first login
+-----------------------------
+
+Earlier versions of this functionality created users on first login. That is no
+longer the case. To enable the previous behaviour, set ``autocreate = on`` in
+the ``[remote-user]`` section in the config-file.
+
+With the default, which is ``off``, it is necessary to pre-create users for
+them to be able to log in. This can be done from the command line with
+``navuser``, or via the web interface.
+
 Workarounds for "strange" `REMOTE_USER` values
 ----------------------------------------------