[keycloak-dev] Realm Admin Resource SPI

Tue Jul 11 09:21:02 EDT 2017

I wouldn't say it's been greenlit just yet. Firstly, we need to discuss if
it's something we want to add. Personally I'm not convinced it'll get
enough use to justify the amount of time required to implement and test.
Secondly, we need to figure out how it should look like, including trying
to not make it to overly complicated. From your summary below it's sounds
like your after something that'll end up being rather large and complicated.

On 5 July 2017 at 00:33, Dmitry Telegin <mitya at cargosoft.ru> wrote:

> Hi,
>
> This topic has been around for a while, and I'm glad to know that it
> has finally been greenlit. Here we'll discuss the requirements for the
> upcoming Realm Admin Resource SPI, as well as class/method naming and
> any other relevant stuff.

> An admin resource is a privileged (protected) resource that exposes
> Keycloak data model and business logic via REST. A the moment, it is
> possible to create ad-hoc admin resources on top of existing Realm
> Resource SPI, but 1) it requires a lot of boilerplate and workarounds,
> and 2) there are limitations. For a while, we've been developing a
> Keycloak extension that utilizes such ad-hoc admin resources (for those
> interested, it brings into Keycloak support for hardware OTP tokens
> with full lifecycle) . We've tried to summarize our experience in
> BeerCloak [1], where most techniques are demonstrated; I'll refer to
> this example in the process.
>
> Now what makes admin resource different from the regular realm
> resource? I'll talk about some major features; feel free to share your
> thoughts in case I've forgotten something.
>
> Security
> ========
>
> As admin resource most likely introduces some new functionality, it's
> quite natural to limit access to this new functionality by custom
> roles. For example, if we introduce feature "foo", most likely we'll
> want "view-foo" and "manage-foo" roles. This requirement breaks down to
> the following steps:
> * create roles for existing realms. That means adding roles to "*-
> realm" clients of master realm and to "realm-management" client of
> regular realms;
> * ditto for each newly added realm;
> * add roles to the "admin" realm role of master realm;
> * server-side authorization: provide an instance of
> o.k.services.resources.admin.AdminAuth (or subclass) to REST resource
> methods so that they could call AdminAuth::hasAppRole;
> * client-side authorization: add viewFoo and manageFoo properties to
> the "access" AngularJS object.
>
> All of the above is doable on top of Realm Resource SPI (see
> BeerCloak), but the code is 99% boilerplate. In fact, the only thing
> that the provider (ideally) has to do is to declare the two roles. The
> actual implementation could be moved to the SPI. What we need is to
> discuss how the roles should be declared (callback, annotation etc.)
>

I'm not sure adding additional roles really is needed. In most cases I
would think view/manage roles would be sufficient. The focus should rather
be on fine-grained permissions which we recently added.

>
> Logging
> =======
>
> Most likely the admin resource will deal with custom JPA entities
> defined using Entity SPI. Moreover, there will likely be a need to log
> admin events about this entity and its operations. Currently, we are
> limited to 4 generic operation types (see
> o.k.events.admin.OperationType) and a list of 27 hardcoded
> entity/resource types (see o.k.events.admin.ResourceType). This is a
> serious limitation because any provider that defines custom entity
> and/or REST operations will be unable to log its activity with Keycloak
> API and present it with Keycloak GUI. As an example, the aforementioned
> OTP extension would benefit from logging admin events with DEVICE
> resource type and ENROLL/REVOKE/LOCK/UNLOCK/RESYNC additional operation
> types. We can discuss now which way the provider would define its
> custom resource operation and resource types. Under the hood, the
> existing enums should be extended with the supplied values (possibly
> using the extensible enum pattern [2][3]). The values should also
> appear in
> o.k.services.resources.admin.info.ServerInfoAdminResource::ENUMS so
> that log filtering could be applied in the GUI.
>

Rather than bring in additional entities, would it not be better to re-use
generic entities? We have a generic component model for config. We have
generic credentials store. We have attributes on everything. Creating
custom entities is just complicated and hard to maintain.

> Last time when we discussed this, Stian said:
> > Introducing this as part of a admin resource spi would make perfect
> > sense.
>
> I agree that extending OperationType is more pertinent to Admin
> Resource SPI ("I define an operation and I want to be able to log it").
> At the same time, extending ResourceType seems to be more topical for
> Entity SPI ("I define an entity and I want to log everything about
> it"). We should decide if we should extend the said SPIs, or otherwise
> create independent OperationTypeSpi+ResourceTypeSpi that could be mixed
> into any provider, be it entity, admin resource or anything else.
>
> At the moment, this couldn't be implemented without modifying Keycloak
> sources.
>

I'm not sure I like the idea of extending either. I'd rather just have
generic plain old strings in event types, operation types, resource types,
etc.. That is much simpler to extend than trying to "extend" enums.

>
> Relation to FeatureProvider
> ===========================
>
> Bill, once we discussed the potential FeatureProvider:
> >  I was also thinking of having a FeatureProvider that would be an
> > "uber" component that could install sub components.  i.e. an
> > authenticator, user federation provider, etc.
>
> I think we could revisit this topic too, since both SPIs seem to be
> closely related.
>
> Thanks for reading this bulky post! Any feedback welcome,
> Dmitry Telegin
> CTO, CargoSoft LLC
> http://cargosoft.ru/en/rm/about/
>
>
> [1] https://github.com/dteleguin/beercloak
> [2] https://blogs.oracle.com/darcy/mixing-in-an-enum
> [3] https://gist.github.com/KamilT/3192681 id="-x-evo-selection-start-
> marker">
> _______________________________________________
> keycloak-dev mailing list
> keycloak-dev at lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/keycloak-dev