preliminary docs for SAML

doc/howto/mod_auth_mellon_feide.rst

@@ -0,0 +1,169 @@
+================================================================================================================
+Authenticating with the apache plugin `mod_auth_mellon <https://github.com/latchset/mod_auth_mellon>`_ and Feide
+================================================================================================================
+
+Enabling the plugin on Debian
+=============================
+
+First check if the plugin is already installed and enabled::
+
+    $ sudo apache2ctl -M | grep mellon
+      auth_mellon_module (shared)
+
+If it is, go straight to `Configuration`_.
+
+If not:
+
+Install the plugin::
+
+            $ sudo apt install libapache2-mod-auth-mellon
+
+This should create the following files::
+
+    /etc/apache2/mods-available/auth_mellon.conf
+    /etc/apache2/mods-available/auth_mellon.load
+    /etc/apache2/mods-enabled/auth_mellon.conf
+    /etc/apache2/mods-enabled/auth_mellon.load
+
+Enable with::
+
+    $ sudo a2enmod auth_mellon
+
+Disable with::
+
+    $ sudo a2dismod auth_mellon
+
+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
+a service and a SAML 2.0 configuration for that service. 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 the service, 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 ``/mellon`` in this howto.
+
+Also, the ``userid-feide`` scope needs to be turned on at
+*User information > Personal information*.
+
+Apache2 Configuration
+=====================
+
+You need to download the idp metadata for use by apache.
+
+* `Test metadata <https://idp-test.feide.no/simplesaml/saml2/idp/metadata.php>`_
+* `Production metadata <https://idp.feide.no/simplesaml/saml2/idp/metadata.php>`_
+
+Save the file as ``/etc/apache2/mellon/idp-metadata.xml`` on the NAV host.
+
+Apache virtual host configuration::
+
+    <Location />
+        .
+        .
+
+        AuthType mellon
+        Require valid-user
+
+        MellonEnable "auth"
+        MellonSecureCookie On
+        MellonUser "NAME_ID"
+        MellonSessionIdleTimeout 28800  # auto logout after 8 hours
+        MellonSPMetadataFile /etc/apache2/mellon/sp-metadata.xml
+        MellonSPPrivateKeyFile y
+        MellonIdPMetadataFile /etc/apache2/mellon/idp-metadata.xml
+    </Location>
+
+    <Location /mellon>
+        SetHandler none
+        AuthType mellon
+        Require valid-user
+
+    </Location>
+
+    <Location /index/logout>
+        AuthType None
+        Require all granted
+    </Location>
+
+    <Location /about>
+        AuthType None
+        Require all granted
+    </Location>
+
+    <Location /refresh_session>
+        AuthType None
+        Require all granted
+    </Location>
+
+    <Location /api>
+        AuthType None
+        Require all granted
+    </Location>
+
+    <Location /doc>
+        AuthType None
+        Require all granted
+    </Location>
+
+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 (``<Location /mellon>``) 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 (``<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``). 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*.
+
+``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 = REMOTE_USER
+    logout-url = /mellon/logout?returnTo
+
+"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``