Improve howto for 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,66 @@ 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
 
-"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.
+"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.
+
+Gotchas
+=======
+
+When this is in use, local users like "admin" will no longer be available. Therefore, either:
+
+* *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``