[keycloak-dev] Design of Auth Server startup from subsystem

[Stian Thorgersen]

----- Original Message -----
> From: "Stan Silvert" <ssilvert at redhat.com>
> To: keycloak-dev at lists.jboss.org
> Sent: Wednesday, 1 October, 2014 10:50:07 PM
> Subject: Re: [keycloak-dev] Design of Auth Server startup from subsystem
> 
> On 10/1/2014 4:07 PM, Bill Burke wrote:
> > Theme support is unaffected?
> The short answer is yes, no affect except that you can now put a custom
> theme in a jar and place in /overlays/<auth-server-name>/other-spi.
> 
> However, concerning themes, the current location for themes will
> probably not work in a domain environment because it lives in
> standalone/configuration/themes.  I'm not sure about the consequences of
> that.  Are there default themes available inside the auth-server.war?

Themes are loaded from "${jboss.server.config.dir}/themes", but this is configurable through keycloak-server.json. We also bundle the themes in a jar in auth-server.war. Exploded themes (${jboss.server.config.dir}/themes) override those in the war, but if someone deletes them then they're loaded from the war.

I propose we simplify the way theme jars are created and make this the recommended way to add themes in a domain. This should only take a few hours to do. Currently a theme jar has to provide an implementation of theme provider, but we'd change that to simply a jar with:

  META-INF/theme.json
  META-INF/themes/<theme type>/<theme name>

contents of theme.json would be:

  { 
    "type": "login",
    "name": "mytheme",
    "parent": "keycloak",
    "styles": [ ... ]
  }

Main reason to change it to a json file instead of properties file is to allow multiple themes in the same jar:

  [ { "type": "login", "name": "mytheme" }, { "type": "account", "name": "mytheme" } ]

> 
> 
> >
> > On 10/1/2014 10:27 AM, Stan Silvert wrote:
> >> After lots of experimentation, I think I've finally settled on a
> >> design.  Though this whole effort has taken longer than expected, I
> >> don't think the coding will take that long since I've got experimental
> >> code that does the hard stuff.  I just need to rearrange it and clean it
> >> up.
> >>
> >> Here is the design.  I appreciate your feedback.
> >>
> >> _*Design Goals*_
> >> * Support auth-server running in a WildFly domain.
> >> * Eliminate deployment from /deployments directory to make it a proper
> >> service instead of an ordinary app.
> >> * Eliminate need to explode or crack open auth-server.war.  Keep it
> >> intact so it doesn't need to be hacked up.
> >> * Load user-provided overlays for keycloak-server.json, SPI jars, and
> >> theme jars.
> >> * Allow uploading overlays from CLI.
> >> * Allow more than one auth-server in a WildFly instance.
> >> * Compatibility with EAP6, EAP7, WildFly8, and WildFly9.
> >>
> >>
> >> _*Management Model*_
> >> The Keycloak subsystem introduces a new resource called, "auth-server".
> >> You can define more than one auth-server if you like.  The simplest form
> >> just looks like this:
> >> <subsystem xmlns="urn:jboss:domain:keycloak:1.1">
> >>               <auth-server name="my-auth-server-name"/>
> >> </subsystem xmlns="urn:jboss:domain:keycloak:1.1">
> >>
> >> On startup, this deploys my-auth-server-name.war with web context "auth".
> >>
> >> There are two optional attributes under <auth-server>.  They are
> >> "enabled" and "web-context".  Here is an example:
> >> <subsystem xmlns="urn:jboss:domain:keycloak:1.1">
> >>               <auth-server name="auth-server1"/>
> >>               <auth-server name="auth-server2">
> >>                        <enabled>true<enabled/>
> >>                        <web-context>auth2</web-context>
> >>               </auth-server>
> >> </subsystem xmlns="urn:jboss:domain:keycloak:1.1">
> >>
> >> In a domain environment, there is an additional resource.  You assign
> >> the auth server to one or more server groups:
> >> <subsystem xmlns="urn:jboss:domain:keycloak:1.1">
> >>               <auth-server name="my-auth-server-name">
> >>                        <server-group name="group1"/>
> >>                        <server-group name="group2"/>
> >>               </auth-server>
> >> </subsystem xmlns="urn:jboss:domain:keycloak:1.1">
> >>
> >> _*Loading the Auth Server*_
> >> The auth-server.war will be loaded from the Keycloak subsystem module.
> >> This is just a convenient place to put it.  We could actually load it
> >> from anywhere.  Note that it no longer needs to be exploded.
> >>
> >> _*Using Overalys*_
> >> The Keycloak subsystem can overlay or add to the auth-server.war.
> >> Overlays do not touch the original content of auth-server.war.
> >>
> >> To define an overaly, you just drop your files in the proper directories
> >> on the file system.  The layout is:
> >>
> >> /overlays/<auth-server-name>/server-config/
> >> /overlays/<auth-server-name>/account-spi/
> >> /overlays/<auth-server-name>/login-spi/
> >> /overlays/<auth-server-name>/other-spi/
> >>
> >> /server-config optionally contains a single json file that replaces
> >> keycloak-server.json
> >> /account-spi optionally contains a single jar file that replaces
> >> keycloak-account-freemarker.jar.
> >> /login-spi optionally contains a single jar file that replaces
> >> keycloak-login-freemarker.jar
> >> /other-spi optionally contains one or more spi jar files to be added to
> >> WEB-INF/lib.  Theme jars also go here.
> >>
> >> _*Location of SPI jars and other user-defined overalys*_
> >> For now, I'm planning to have the /overlays directory in the Keycloak
> >> subsystem module.  They could, for instance, go in a /keycloak directory
> >> such as <wildfly-home>/keycloak.   Any thoughts on this?
> >>
> >> _*Uploading overlays from CLI*_
> >> It is already possible to create overalys via CLI.  You upload the
> >> content and assign it to deployments and server-groups.  The CLI
> >> commands for this are rather complicated and you really need to know
> >> what you are doing.
> >>
> >> We could make this easier by adding simpler CLI operations to the
> >> Keycloak subsystem.  However, I think we should hold off on this until
> >> we find out if the directory-based approach is acceptable to users.  In
> >> the mean time, we can just document the CLI commands needed to upload
> >> overlays.
> >>
> >>
> >> _______________________________________________
> >> keycloak-dev mailing list
> >> keycloak-dev at lists.jboss.org
> >> https://lists.jboss.org/mailman/listinfo/keycloak-dev
> >>
> 
> _______________________________________________
> keycloak-dev mailing list
> keycloak-dev at lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/keycloak-dev
>