From 896ea084d2007ef8a29e911ffd39c0b24a668672 Mon Sep 17 00:00:00 2001 From: Hanne Moa Date: Wed, 1 Nov 2023 14:05:08 +0100 Subject: [PATCH] Improve howto for remote user --- doc/howto/mod_auth_openidc_feide.rst | 122 ++++++++++++++++++++++----- 1 file changed, 99 insertions(+), 23 deletions(-) diff --git a/doc/howto/mod_auth_openidc_feide.rst b/doc/howto/mod_auth_openidc_feide.rst index ca5709e195..4c14cb8dfb 100644 --- a/doc/howto/mod_auth_openidc_feide.rst +++ b/doc/howto/mod_auth_openidc_feide.rst @@ -2,6 +2,58 @@ Authenticating with the apache plugin `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 `_ 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:: @@ -44,43 +96,67 @@ Apache virtual host configuration:: 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 ````. 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 (````) 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 (````) 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 `_. + +``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 `_. **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 +````-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``