Upgrade from 1.9 to 2.0¶
Attention
2.0 is a major release, lot of things have been changed. You must read this document before upgrade.
Upgrade order from 1.9.*¶
As usual, if you use more than 1 server and don’t want to stop SSO service AND IF YOU HAVE NO INCOMPATIBILITY MENTIONED IN THIS DOCUMENT, upgrade must be done in the following order:
servers with handlers only;
portal servers (all together if your load balancer is stateless (user or client IP) and if users use the menu);
manager server
Attention
You must revalidate your configuration using the manager.
Installation¶
Attention
French documentation is no more available. Only English version of this documentation is maintained now.
This release of LL::NG requires these minimal versions of GNU/Linux distributions:
Debian 9 (stretch)
Ubuntu 16.04 LTS
CentOS 7
RHEL 7
For SAML features, we require at least Lasso 2.5 and we recommend Lasso 2.6.
Configuration¶
lemonldap-ng.ini requires some new fields in portal section. Update yours using the one given installed by default. New requires fields are:
staticPrefix (manager and portal): the path to static content
templateDir (manager and portal): the path to templates directory
languages (manager and portal): accepted languages
Portal skins are now in
/usr/share/lemonldap-ng/portal/templates
. See skin customization to adapt your templates.User module in authentication parameters now provides a “Same as authentication” value. You must revalidate it in the manager since all special values must be replaced by this (Multi, Choice, Proxy, Slave, SAML, OpenID,…)*
“Multi” doesn’t exist anymore: it is replaced by Combination, a more powerful module.
Apache and Nginx configurations must be updated to use FastCGI portal
URLs for mail reset and register pages have changed, you must update configuration parameters. For example:
mailUrl => 'http://auth.example.com/resetpwd',
registerUrl => 'http://auth.example.com/register',
Option
trustedProxies
was removed, you must now configure your Web Server to manageX-Forwarded-For
header, see how to run LL::NG behind a reverse proxy.
Attention
Apache mod_perl has got lot of troubleshooting problems since 2.4 version (many segfaults,…), especially when using MPM worker or MPM event. That’s why LL::NG doesn’t use anymore ModPerl::Registry: all is now handled by FastCGI (portal and manager), except for Apache2 Handler.
For Handlers, it is now recommended to migrate to Nginx, but Apache 2.4 is still supported with MPM prefork.
Configuration refresh¶
Now portal has the same behavior than handlers: it looks to configuration stored in local cache every 10 minutes. So it has to be reload like every handler.
Attention
If you want to use reload mechanism on a portal only
host, you must install a handler in Portal host to be able to refresh
local cache. Include handler-nginx.conf
or handler-apache2.conf
for example
LDAP connection¶
Now LDAP connections are kept open to improve performances. To allow that, LL::NG requires an anonymous access to LDAP RootDSE entry to check connection.
Kerberos or SSL usage¶
A new Kerberos authentication backend has been added since 2.0. This module solves many Kerberos integration problems (usage in conjunction with other backends, better error display,…). However, you can retain the old integration manner (using Apache authentication module).
For SSL, a new Ajax option can be used in the same idea: so SSL can be used in conjunction with other backends.
Logs¶
Syslog: logs are now configured in
lemonldap-ng.ini
file only. If you use Syslog, you must reconfigure it. See logs for more.Apache2: Portal doesn’t use anymore Apache2 logger. Logs are always written to Apache error.log but Apache “LogLevel” parameter has no more effect on it. Portal is now a FastCGI application and doesn’t use anymore ModPerl. See logs for more.
If you are running behind a proxy, make sure LemonLDAP::NG can see the original IP address of incoming HTTP connections
Security¶
LLNG portal now embeds the following features:
CSRF protection (Cross-Site Request Forgery): a token is built for each form. To disable it, set requireToken to 0 (portal security parameters in the manager)
Content-Security-Policy header: portal build dynamically this header. You can modify default values in the manager (Général parameters » Advanced parameters » Security » Content-Security-Policy)
Handlers¶
Apache only:
Apache handler is now Lemonldap::NG::Handler::ApacheMP2 and Menu is now Lemonldap::NG::Handler::ApacheMP2::Menu
because of an Apache behaviour change, PerlHeaderParserHandler must no more be used with “reload” URLs (replaced by PerlResponseHandler). Any “reload url” that are inside a protected vhost must be unprotected in vhost rules (protection has to be done by web server configuration).
CDA, ZimbraPreAuth, SecureToken and AuthBasic are now Handler Types. So there is no more special file to load: you just have to choose “VirtualHost type” in the manager/VirtualHosts.
SSOCookie: Since Firefox 60 and Chrome 68, “+2d, +5M, 12h and so on…” cookie expiration time notation is no more supported. CookieExpiration value is a number of seconds until the cookie expires. A zero or negative number will expire the cookie immediately.
Rules and headers¶
hostname() and remote_ip() are no more provided to avoid some name conflicts replaced by `$ENV{}`)
$ENV{<cgi_variable>} is now available everywhere: see Writing rules and headers
some variable names have changed. See Variables document
Opening conditions¶
Rule and message fields have been swaped. You have to modifiy and validate again your access rules.
Supported servers¶
Apache-1.3 files are not provided now. You can build them yourself by looking at Apache-2 configuration files
Ajax requests¶
Before 2.0, an Ajax query launched after session timeout received a 302
code. Now a 401 HTTP code is returned. WWW-Authenticate
header
contains: SSO <portal-URL>
SOAP/REST services¶
SOAP server activation is now split in 2 parameters (configuration/sessions). You must set them else SOAP service will be disabled
Notifications are now REST/JSON by default. You can force old format in the manager. Note that SOAP proxy has changed: http://portal/notifications now.
If you use “adminSessions” endpoint with “singleSession*” features, you must upgrade all portals simultaneously
SOAP services can be replaced by new REST services
Attention
AuthBasic Handler uses now REST services instead of SOAP.
CAS¶
CAS authentication module no more use perl CAS client, but our own code. You can now define several CAS servers in a specific branch in Manager, like you can define several SAML or OpenID Connect providers.
CAS issuer module has also been improved, you must modify the configuration of CAS clients to move them from virtual host branch to CAS client branch.
Developer corner¶
APIs¶
Portal has now many REST features and includes an API plugin. See Portal manpages to learn how to write auth modules, issuers or other features.
Portal overview¶
Portal is no more a single CGI object. Since 2.0, It is based on Plack/PSGI and Mouse modules. Little resume
Portal object
|
+-> auth module
|
+-> userDB module
|
+-> issuer modules
|
+-> other plugins (notification,...)
Requests are independent objects based on Lemonldap::NG::Portal::Main::Request which inherits from Lemonldap::NG::Common::PSGI::Request which inherits from Plack::Request. See manpages for more.
Handler¶
Handler libraries have been totally rewritten. If you’ve made custom handlers, they must be rewritten, see customhandlers.
If you used self protected CGI, you also need to rewrite them, see documentation.