Some discoveries using the documentation for mod_auth_mellon (without uploading an sp-metadata.xml)

Securing applications
1

Hey Folks,

We’re running Keycloak 26.0.8 and are attempting to use mod_auth_mellon under apache 2.4.

I’ve run into a few challenges that I’d like to share with the group, related to both the documentation (https://www.keycloak.org/securing-apps/mod-auth-mellon) as well as some keycloak behaviors.

First, we banged our heads against trying to follow the documentation. In literally the first screen of documentation on Keycloak and Mellon, it says:

If you have already defined and registered the client application within a realm on the Keycloak application server, Keycloak can generate all the files you need except the Apache HTTPD module configuration.

Perform the following procedure to generate the Apache HTTPD module configuration.

And then says “Procedure:” and tells you how to get keycloak to download a zip file.

Maybe I was reading this wrong, but if that’s literally the first “procedure” listed, I assumed that that’s the first step I should do, so I simply created a client, with some sane values like the base URL, and downloaded the zip file. Hey, this looks like it has all the files you just told me I need, cool! Thus began several hours that I won’t get back :slight_smile:

Only much later in the documentation, does it go into getting mod_auth_mellon to create an sp-metadata.xml file, but Keycloak, in the zip file, also gives you an sp-metadata.xml. It’s easy to assume that you have everything you need, without doing that!

Ergo, in the interest of understanding what the XML values would be, I attempted to build a client config without ever importing an sp-metadata.xml, and instead just letting Keycloak build everything for the client to use (It felt simpler than having to copy/upload files in both directions). It mostly worked, with a few very dumb exceptions:

  • The XML Keycloak sends is totally unformatted. (Which definitely made debugging this all more difficult). I understand (but hate) why people WebPack javascript and strip all the whitespace out of it, but there are literally no savings in doing this with an XML, which is expected to be structured cleanly. I had to pipe it through xmllint --format to get it readable. This may have been accepted by mod_auth_mellon, but what absolutely would not have been is the next item.

  • The certificate and key files are not folded on the 64 character boundary like every other cert I’ve seen, and are also missing their -----BEGIN CERTIFICATE---- and -----END-CERTIFICATE----- (or PRIVATE KEY) blocks. I fixed this by manually cating those lines onto the file, as well as passing the files through `fold -w 64… We’ve opened a gitlab issue for this item, since these certificates will crash mod_auth_mellon if used as provided.

  • If you forget to configure it, keycloak will also put the line <md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="ERROR:ENDPOINT_NOT_SET"/> into the sp-metadata.xml that it configures (rather than just leaving this line out. (Remember, this is buried under “Advanced” when you create a client, it’s easy to miss). If Keycloak is going to generate an XML file with errors in it, perhaps it should just refuse to generate the files, instead of handing out broken ones. Also, maybe don’t put the required values that must be in every client under “Advanced”, but ask for them when you create the client.

  • Related to the above: If you do not configure an “Assertion Consumer Service POST Binding URL” (under “Advanced”), when you try to authenticate, Keycloak will give you the error “Invalid Redirect URL”. Not “Invalid POST Binding URL”, but “Invalid Redirect URL”.
    Guess how many things (with/without url-schemes, with/without trailing slashes, with/without wildcards) I put into the list of “Valid Redirect Urls” and how many times I restarted Keycloak because of the way this error was worded?

===

Note that it’s important to us to be able to configure a client without copying up an sp-metadata.xml. In the interest of mass-provisioning a number of clients, I attempted to make it so that one could do this without having each client generate its own xml files. (I can’t find a way in the REST api, which we would want to use with Puppet, to import an sp-metadata.xml, but it may be possible to “manually” create a client via API calls.

Keycloak will happily generate a private key, and a certificate for a client to use, and you only need to manually configure it with the correct values. Here are the values I’ve discovered:

  • In the main client: A client-id (which can be anyting), a IDP-Initiated SSO URL name (typically /mellon/), and a list of valid redirect urls. You need to turn “Include AuthnStatement” and “Force POST binding” on. Also, set “Sign Documents” to “on” and also make sure you set Signature Algorithm to SHA1 (mellon doesn’t support newer at this time).

  • Under Advanced: “Assertion Consumer Service POST Binding URL” and “Logout Service Redirect Binding URL” need to be set.

The above items could probably be added to the documentation.

As could, maybe, putting the bit about having mellon_create_metadata.sh generate the sp-metadata file, way earlier in the doc.

2

Net result: I’ve created a bunch of github issues for these changes I’d like to see.