[keycloak-dev] new URI scheme
Bill Burke
bburke at redhat.com
Wed Dec 9 14:18:04 EST 2015
We can remove /auth, but reworking the rest of the URI scheme depends on
a few things (some we have discussed):
* We need the flexibility to add root resources. {realm} as the root
resource does not play well with JAX-RS if you ahve more specific root
resources you want to add
* There are already specific root resources: /version, and
/js/keycloak.js and /qrcode and /resources and "/"
* There are a number of public URIs under /realms/ i.e. .well-known
Our URIs actually aren't bad:
/admin/realms - admin REST API
/admin/serverinfo - admin REST API describing installed server providers
/admin/{realm}/console - admin console login for a specific realm
/admin - redirects to /admin/master/console
/admin/index.html - redirects to /admin/master/console
/realms/{realm}/account - account service
/realms/{realm}/protocol - protocol specific endpoints for SAML, etc.
/realms/{realm}/broker - broker specific endpoints for SAML, etc.
/realms/{realm}/login-actions - auth flow for reg, auth, reset, etc.
We will want to refactor the admin REST API, but other than that the URI
scheme is ok and allowed us to modularize code into Sub Resource
Locators quite nicely. One thing I might change is the admin console
and make it consistent with account:
/realms/{realm}/console
That's it though.
On 12/9/2015 1:15 PM, Marek Posolda wrote:
> +1
>
> some things like ServerVersionResource or static resources ( keycloak.js
> etc) are just not tight to any specific realm. Removing "/realms" would
> mean that we will need to move all of them under the path specific to
> some realm. For example move keycloak.js under
> "http://localhost:8080/auth/foo/keycloak.js" . But that doesn't seem to
> be very good practice as keycloak.js is not resource specific to realm
> "foo" .
>
> If we want shorter and more user-memorable URLs, we can maybe introduce
> some URLAliasService, where will people have possibility to define short
> URL aliases for some endpoints. This might have support for regexes etc.
> However Apache HTTPD already provides something like this AFAIK
>
> Marek
>
>
> On 09/12/15 15:33, Bill Burke wrote:
>> Once we go to host/{realms} we are stuck with it. The matching rules of
>> JAX-RS will prevent us from adding any top level resource that is more
>> specific. Stian, we might want to reconsider removing "/realms".
>>
>> On 12/8/2015 5:34 AM, Stian Thorgersen wrote:
>>> 'admin' will probably move at some point to be under the realm.
>>>
>>> 'version' would move as well. Although this one should probably be
>>> removed altogether.
>>>
>>> KeycloakSession and SPIs needs to be tied to a specific realm. This
>>> makes everything cleaner.
>>>
>>> Besides it just doesn't make any sense to add arbitrary rest endpoints
>>> to Keycloak. A rest endpoint should be tied to a realm, otherwise it
>>> just doesn't make sense to host it on the Keycloak server.
>>>
>>>
>>>
>>> On 8 December 2015 at 11:18, Erik Mulder
>>> <erik.mulder at docdatapayments.com
>>> <mailto:erik.mulder at docdatapayments.com>> wrote:
>>>
>>> Stian, I can see your point. Using the realm name as the root level
>>> certainly has advantages. It also really fixes everything to a
>>> realm, but I guess that is what you want. So how about the current
>>> ‘/admin’ url, how does that fit in the new picture? Because that
>>> would be my next best target to hook into. Furthermore, there’s
>>> currently a ‘/version’ root path that should end up somewhere else.
>>> Personally, I think it’s not so bad to have a descriptive root
>>> level
>>> like ‘realms’, which leaves open the possibility to add extra root
>>> level paths, like meta data (version) or special contexts (admin,
>>> customPath).____
>>>
>>> __ __
>>>
>>> __ __
>>>
>>> *Van:*Stian Thorgersen [mailto:sthorger at redhat.com
>>> <mailto:sthorger at redhat.com>]
>>> *Verzonden:* dinsdag 8 december 2015 10:32
>>> *Aan:* Greg Jones <gregj at thesoftwarecottage.com.au
>>> <mailto:gregj at thesoftwarecottage.com.au>>
>>> *CC:* Erik Mulder <erik.mulder at docdatapayments.com
>>> <mailto:erik.mulder at docdatapayments.com>>;
>>> keycloak-dev at lists.jboss.org <mailto:keycloak-dev at lists.jboss.org>
>>>
>>>
>>> *Onderwerp:* Re: [keycloak-dev] Add custom REST paths? New SPI?____
>>>
>>> __ __
>>>
>>> -1 To adding rest endpoints to the root level. I'd like to get rid
>>> of 'realms' part as some point and have all rest endpoints sit
>>> underneath a realm. This makes sure the KeycloakSession always
>>> knows
>>> what realm is being handled, so we don't need to pass the realm
>>> around as it can be retrived from the KeycloakContext. It also
>>> means
>>> that the url can be shortened as we can drop the 'realms' part.____
>>>
>>> __ __
>>>
>>> On 8 December 2015 at 10:22, Greg Jones
>>> <gregj at thesoftwarecottage.com.au
>>> <mailto:gregj at thesoftwarecottage.com.au>> wrote:____
>>>
>>> +1 for these changes. We have been looking at a way to add
>>> custom REST endpoints and would be happy to use this approach.
>>>
>>> Regards
>>> Greg Jones____
>>>
>>>
>>>
>>> > On 8 Dec 2015, at 8:17 PM, Erik Mulder
>>> <erik.mulder at docdatapayments.com
>>> <mailto:erik.mulder at docdatapayments.com>> wrote:
>>> >
>>> > Pedro's change (see below) is kindof what I was looking for,
>>> but for my case and for general flexibility I think it's
>>> good to
>>> also have a more basic point to hook into the REST API's.
>>> > I implemented and tested my own suggestion of having an SPI
>>> to be able to add a REST resource at the root level. Combined
>>> with the (coming) ability to freely extend the JPA entities and
>>> DB schema, I think this creates a really powerful extensibility
>>> to Keycloak. When we finish these changes, I can write a blog
>>> post about what we did, why and how as a showcase for custom
>>> extensions to Keycloak.
>>> >
>>> > So are the Keycloak dev's open to a PR with a new SPI that
>>> enables you to add custom REST paths?
>>> > For example, you could create something like:
>>> > http://localhost:8080/auth/myPath/myResource
>>> >
>>> >
>>> > -----Oorspronkelijk bericht-----
>>> > Van: Pedro Igor Silva [mailto:psilva at redhat.com
>>> <mailto:psilva at redhat.com>]
>>> > Verzonden: maandag 7 december 2015 22:18
>>> > Aan: Erik Mulder <erik.mulder at docdatapayments.com
>>> <mailto:erik.mulder at docdatapayments.com>>
>>> > Onderwerp: Re: [keycloak-dev] Add custom REST paths? New
>>> SPI?
>>> >
>>> > It is part of a working in progress around fine-grained
>>> authorization [1].
>>> >
>>> > The new SPI changes [2] specific to Keycloak are located
>>> in a
>>> specific branch [3] in my Keycloak fork.
>>> >
>>> > I need to discuss these changes with Bill and see what he
>>> thinks about it. Depending on his feedback, I can prepare a PR
>>> and send these changes to upstream.
>>> >
>>> > [1] https://github.com/pedroigor/keycloak-authz
>>> > [2]
>>>
>>> https://github.com/pedroigor/keycloak/commit/5e99614aacb70f7840a5ae25cfeaf3fc9d74ac54
>>>
>>> > [3]
>>>
>>> https://github.com/pedroigor/keycloak/tree/keycloak-authz-modified
>>> >
>>> > Regards.
>>> >
>>> > ----- Original Message -----
>>> > From: "Erik Mulder" <erik.mulder at docdatapayments.com
>>> <mailto:erik.mulder at docdatapayments.com>>
>>> > To: "Pedro Igor Silva" <psilva at redhat.com
>>> <mailto:psilva at redhat.com>>
>>> > Sent: Monday, December 7, 2015 5:51:26 PM
>>> > Subject: RE: [keycloak-dev] Add custom REST paths? New SPI?
>>> >
>>> > Great, that's probably all we need!
>>> > I'd like to try it out, but I cannot find any reference to
>>> what you mention on Github. Is it (going to be) a pull request?
>>> Is it going to be part of a future release?
>>> > Can you point me to / provide me with these changes so I can
>>> give it a spin? Thanks!
>>> >
>>> > ________________________________________
>>> > Van: Pedro Igor Silva [psilva at redhat.com
>>> <mailto:psilva at redhat.com>]
>>> > Verzonden: maandag 7 december 2015 16:03
>>> > Aan: Erik Mulder
>>> > CC: keycloak-dev at lists.jboss.org
>>> <mailto:keycloak-dev at lists.jboss.org>
>>> > Onderwerp: Re: [keycloak-dev] Add custom REST paths? New
>>> SPI?
>>> >
>>> > I've done something at this regard, where you can use a SPI
>>> in order to plug additional APIs for:
>>> >
>>> > * Realm Admin RESTFul API (eg.: used by admin console)
>>> > * Realm RESFTFul API (eg.: to plug additional endpoints
>>> for realms)
>>> >
>>> > The two Provider interfaces are very simple and just provide
>>> a single method:
>>> >
>>> > Object getResource(String pathName);
>>> >
>>> > Where pathName is the path that must be resolved to your
>>> custom JAX-RS resource.
>>> >
>>> > The factories are also very simple and allows you to build
>>> those resources for the current Realm and KeycloakSession. Eg.:
>>> >
>>> > RealmResourceProvider create(RealmModel realm,
>>> KeycloakSession keycloakSession);
>>> >
>>> > Do you need something other than that ?
>>> >
>>> > Regards.
>>> > Pedro Igor
>>> >
>>> > ----- Original Message -----
>>> > From: "Erik Mulder" <erik.mulder at docdatapayments.com
>>> <mailto:erik.mulder at docdatapayments.com>>
>>> > To: keycloak-dev at lists.jboss.org
>>> <mailto:keycloak-dev at lists.jboss.org>
>>> > Sent: Monday, December 7, 2015 12:46:39 PM
>>> > Subject: [keycloak-dev] Add custom REST paths? New SPI?
>>> >
>>> > As some of you might know, our team is busy adding data to
>>> the keycloak system to incorporate some custom authorization
>>> information in the access token.
>>> > So far we've successfully extended the JPA entities,
>>> Liquibase table definitions and added a custom mapper to put
>>> that data in the access token. All of this without custom
>>> modifications to the original keycloak sources. This is working
>>> great, thanks for the support so far!
>>> > I know I've promised some PR's for this and they will come,
>>> but first we'd like to get everything fully working, so we know
>>> it's a well functioning whole.
>>> >
>>> > The last piece of the puzzle is extending the REST services
>>> to include CRUD actions for our custom resources. I've been
>>> looking into the way RESTEasy/JAX-RS works and it seems to me
>>> that in the current implementation there is no way to add extra
>>> paths. As I see it now, the KeycloakApplication class will
>>> register some singletons in it's constructor and that's
>>> that. No
>>> way to extend or to 'interfere' there.
>>> >
>>> > So my question is: is there any 'official' way to add extra
>>> REST paths to Keycloak?
>>> >
>>> > If not, is it an idea to add this as a new SPI? The current
>>> code for adding root paths in the KeycloakApplication
>>> constructor lists:
>>> >
>>> > singletons.add(new ServerVersionResource());
>>> > singletons.add(new RealmsResource());
>>> > singletons.add(new AdminRoot());
>>> >
>>> > So just plain contructor calls. That seems like an easy
>>> target for 'SPI-ing' :-).
>>> > Or just leave the current ones 'hardcoded' and add an SPI
>>> for
>>> custom extensions.
>>> > Your thoughts on this please.
>>> >
>>> > As before, I'm happy to implement this myself, but I'd like
>>> to discuss it first, so a future PR will be honored.
>>> >
>>> >
>>> > _______________________________________________
>>> > keycloak-dev mailing list
>>> > keycloak-dev at lists.jboss.org
>>> <mailto:keycloak-dev at lists.jboss.org>
>>> > https://lists.jboss.org/mailman/listinfo/keycloak-dev
>>> >
>>> > _______________________________________________
>>> > keycloak-dev mailing list
>>> > keycloak-dev at lists.jboss.org
>>> <mailto:keycloak-dev at lists.jboss.org>
>>> > https://lists.jboss.org/mailman/listinfo/keycloak-dev
>>>
>>>
>>> _______________________________________________
>>> keycloak-dev mailing list
>>> keycloak-dev at lists.jboss.org
>>> <mailto: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
>>>
>
--
Bill Burke
JBoss, a division of Red Hat
http://bill.burkecentral.com
More information about the keycloak-dev
mailing list