Soooo, after hundreds of LoC and hundreds of grey hair later, I finally managed to get the Apereo CAS working with NetXMS Web UI.
In order to help other users, who also struggle to get this to work on their setup, I answer my questions from the original post by myself, give brief tips and try to keep it as general as possible.
You will need the following Server Configuration variables set on your NetXMS server:
"
CASHost" - The hostname/IP facing to the CAS server; in case it is behind a proxy, configure the proxy let this hostname point to the CAS server (or the root folder of it's .war)
"
CASPort" - The port which will be appended to 'CASHost' for the https-request (Again, when behind a proxy, use the port, which is configured in the proxy to point towards the server)
"
CASService" - The 'serverId' configured in CAS, NetXMS uses to identify intself at CAS
"
CASTrustedCACert" - The path to the CA certificate of the CAS server (actually, I'm not 100% sure about that, but it worked for me to just use the .crt file, which I generated for the CAS-domain)
"
CASValidateURL" - The path extension to append to hostname and port to get
CASHost:CASPort/CASValidateURL. At this resource, NetXMS requests CAS to validate the received service ticket. (With CAS 6.0.x, this is by default '
/cas/serviceValidate')
(From this point, I will use cas.example.com as CAS-hostname and netxms.example.com as NetXMS-WebUI hostname -> this will also be its serviceId at CAS)
1. "How does the Webapp handle the SSO session?":
- After loggin into CAS at cas.example.com/cas/login?service=netxms.example.com, CAS will redirect to netxms.example.com?ticket=ST-[...]-something
- The Webapp then attempts to connect to the NetXMS server defined either in nxmc.properties or by the 'server' query parameter (otherwise, 127.0.0.1 is chosen) and provides the service ticket to be used as SSO login.
- The NetXMS server then tries to connect to the CAS server's service validation endpoint defined by the three variables above, using HTTPS and to verify its SSL certificate (here: cas.examlpe.com/cas/serviceValidate?service=netxms.example.com&ticket=ST-[...]-something
- The provided parameters 'service' and 'ticket' are used for validation. If they are valid, NetXMS tries to extract the XMS tags <cas:authenticationSuccess> for confirmation and <cas:user> to determine the username, from CAS-server's response.
- Successful login is only possible, if the username extracted from <cas:user> is present in the NetXMS user database, otherwise, access will not be granted.
1.1 "Is there a special URL to which CAS needs to redirect upon successful login?": More or less:
netxms.example.com?ticket=ST-[...]-something (The URL to reach the login-page of the NetXMS WebUI, extended by a query string containing at least the ticket-parameter)
This is done by default by CAS, so nothing to do here.
1.2 "Which attributes are needed from and for CAS?": From CAS, only the service ticket (and optionally, the NetXMS server, but this can by set in
nxmc.properties)
To CAS, serviceId (CASService configuration variable) and ticket, additionally, the username in CAS should also be present in NetXMS user database
1.3 "Is SLO (single log out) also implemented?": So far, I did not see anything like this. After logging out from a NetXMS SSO session, the current service ticket may be expired (depending on the CAS configuration), but the TGT (Ticket granting ticket) is not, so logging in again via the CAS interface will not prompt the login dialog of CAS, until
cas.example.com/cas/logout is requested.
2 "How is the user management handled?: "The username extracted from the validation response (
<cas:user>, which is basically the principal id) is used to determine the representing user within the NetXMS database. Basically, it is just as logging in as this user.
2.1 "Does te user still need to be present in the NetXMS database?: "Yes :D
2.2 "If not, how are access rights handled?: "As 2.1 returns 'Yes', this is pretty self explaining, given that you know how NetXMS internal user-/group management works.
3 "Can the official documentation be extended with this topic?": I don't know, they could refer to this forum thread, maybe ;D
Hopefully, this helps some people setting up their CAS/NetXMS infrastructure. (Btw.: Debug level 9 in server logs gives some good information about this. Keep an eye open for SSO error codes (0,-1,-2,-10 ... -20 ...) and messages - their handling can be checked in the file '
cas_validator.cpp' of the sourcecode, which can provide some help in determining, what is going on).
The file '
ApplicationWorkbenchAdvisor.java' in
[SourceCodeRoot]/webui/webapp/Core/src/org/netxms/ui/eclipse/console/ shows, how the login method is chosen, depending on the URL parameters provided upon accessing the login page of the WebUI.
Another tip: Service ticket validation needs to be done via HTTPS - a self-signed certificate is sufficient in a testing environment.
Feel free to ask, if questions come up :)
Thank you and kind regards,
fbu