Postgrest: Why do we have to use the jwt claim role

Created on 8 Jul 2017  ·  34Comments  ·  Source: PostgREST/postgrest

It'd be helpful if we can do custom as now you need to namespace returns in the id_token. Maybe we can just define the namespace?

enhancement
Source
picture posix4e

Most helpful comment

Details ++

Overview

Things are getting rowdy over at Auth0, but it’s all in the name of progress.

In order to bring their authentication process in line with published standards, Auth0 is making an effort to push people to a new authentication flow. A recent change, noted in this memo, makes the new flow the default. The process described on postgrest.com is only compatible with the now-”legacy” authentication process for reasons detailed below.

Auth0’s push here is to register services, such as postgrest, and give them their own oauthy-type access token JWTs instead of generic JWTs.

Key Terms

JSON Web Token (JWT) -- Signed token fitting the jwt spec
ID Token -- A JWT containing user profile information. Intended for use by the _client_.
Access Token -- A bearer token to use to access an OAuth resource server.
Open ID Connect (OIDC) -- the standard the that adds authentication to OAuth. OAuth provides the authorization mechanism.

Current Status

The “legacy” authentication process is no longer default, the docs need to instruct the user to turn off OIDC-strict mode. PR here.

Existing “legacy” integrations will continue to work. Integrations will break if they switch to the new flow. The new flow is used if an audience parameter is included in the authentication request OR the developer manually enables the OIDC-compliant toggle in Auth0’s client settings dashboard.

“Legacy” Flow Overview

img_20170830_105216b

  1. User authentication provided by google to Auth0
  2. Auth0 grants a generic JWT to the web app
  3. Web app uses JWT to make requests to postgrest

OIDC-strict Flow Overview

img_20170830_134417b

  1. User authentication provided by google to Auth0
  2. Auth0 issues optionally two tokens to web app

    • Identity Token -- to use in the browser app. Contains user profile information. _Not to be passed on to APIs_

    • Access Token -- to use as a bearer token making calls to postgrest. Contains only an arbitrary user identifier in the sub claim

  3. Web app uses Access Token to make request to postgrest

OIDC-strict Requirements

For Auth0 applications:

  • Role information will need to be provided in a different claim. The role claim will now be filtered out by Auth0. Two options seem viable:

    • Namespace role, so that it is not filtered out.

      Eg. https/my-postgrest/role: basic_user

    • Use the scopes claim to determine a user’s role

      Not sure what the mechanics would be here. Scopes are conventionally split up by read / write and resource. But looking for a role:<user-role> in the scope part of the JWT might give us what we want.

  • An aud claim will be included in these new access tokens; per #955, this requires a way to match on that expectation. A setting in the config file seems like the way to do this. The same setting could be used to namespace other claims, such as role.

For non-Auth0 applications:

  • These will of course continue to work as they always have. Outside a speculative threat of token misappropriation, there’s no reason for users to configure a token’s audience. role is an acceptable name for a claim if developers assemble their own JWTs.

Integration Process from Developer’s Perspective (Draft)

The steps to integrate with the _new_ OIDC pipeline are similar, but with some changes and additions:

  1. NEW: An ‘API’ must be created in the Auth0 dashboard
    This will be our postgrest api.
  2. UNCHANGED: A ‘client’ must be created in the Auth0 dashboard
    Eg. a single page app (SPA) that will access our postgrest api
  3. CHANGED: Integrate client with Auth0
    Now, we acquire an ‘access token’ instead of an ‘id token’
    Lock.js does this pretty elegantly, just as before. However, new rules limit which claims can be added to this token, so role information will have to be stored elsewhere.
  4. CHANGED: Add a rule to Auth0 processing such that the role information is added to the access token. This information can be included in a namespaced claim, eg. https://my-postgrest/role, in one of the ~20 standard claims, or in token metadata, eg. scope
  5. NEW: Add an jwt-audience value to the postgrest configuration file
    OIDC access tokens always have an aud field. So unless we match it appropriately, we'll see the error noted in #955

I'm pretty confident there's a solution here that doesn't require any additional thought on the part of the developer, but it will take some work here.

picture willscripted on 30 Aug 2017
👍9

All 34 comments

As I am new to the project, I do not really know where to look for the code to change this configuration, but I too am eager to allow arbitrary extraction of of information from a JWT for roles and other information, rather than being bound to using scope, especially as to be OIDC compliant custom scopes are now expected to be namespaced.

Where might one start on this? Are there any plans in progress for setting runtime variables in Postgres from arbitrary information in a JWT?

fluffybonkers picture fluffybonkers on 17 Jul 2017

can you be more specific as to what exactly you want to accomplish and why the key role in hte jwt payload is not good enough?

ruslantalpa picture ruslantalpa on 17 Jul 2017

My understanding of this article is that we should not use role, we should use, for example, "https://www.example.com/role": "admin" so that roles/claims are collision resistant and JWTs are OIDC compliant.

fluffybonkers picture fluffybonkers on 17 Jul 2017

so why can't role be thought of as "private claim"?

ruslantalpa picture ruslantalpa on 17 Jul 2017

It could be, but then the claim, as I understand it, is not collision resistant and role is possibly a common key.

Perhaps none of this matters, but I have just always understood it to be recommended that claims be namespaced and I think Auth0 suggest this in a few different bits of their documentation.

fluffybonkers picture fluffybonkers on 17 Jul 2017

If you'll be using the same jwt across multiple servers I guess there's the chance of a conflict for a name like role, but I'm not eager to change it and break compatibility. This is especially true since JWT has been an area of postgrest that already confuses people.

begriffs picture begriffs on 17 Jul 2017
👍1

Joe you need to fix this if you want to use auth0 with its new API. In
addition there's a question of whether or not assuming role is standards
complain private claim. Nowadays people namespace non standardized claims.

Perhaps make a note of what versions you support and tell people we are
broken with the new auth0 API. By the way this stuff works fine in
postgraphql. If we don't fix it I'll have to fork, switch to postgraphql or
make the change myself.I guess it's a good excuse to learn Haskell! Have we
sufficiently explained why Postgrest no longer works with auth0. Afaiac
being broken is bad no matter if we are right or not.

Alex
On Mon, Jul 17, 2017 at 7:52 AM Joe Nelson notifications@github.com wrote:

If you'll be using the same jwt across multiple servers I guess there's
the chance of a conflict for a name like role, but I'm not eager to
change it and break compatibility. This is especially true since JWT has
been an area of postgrest that already confuses people.

—
You are receiving this because you authored the thread.
Reply to this email directly, view it on GitHub
https://github.com/begriffs/postgrest/issues/906#issuecomment-315774262,
or mute the thread
https://github.com/notifications/unsubscribe-auth/AAxN2yiWKcPWz0n1co4aTgIhFMx4ZfR3ks5sO3FYgaJpZM4OR3x3
.

posix4e picture posix4e on 17 Jul 2017

I see, I had overlooked the consequences for Auth0. I can't dedicate the time to think about this at the moment, but am flagging it for more thorough review.

begriffs picture begriffs on 17 Jul 2017

@begriffs Thanks for the quick reply. I am happy to test this for people and update the documentation v.v. auth0. I am happy to make the patch but I am such a haskell noob that it will probably take more mentoring than it's worth.

posix4e picture posix4e on 17 Jul 2017

Any updates?
On Mon, Jul 17, 2017 at 9:58 AM Joe Nelson notifications@github.com wrote:

I see, I had overlooked the consequences for Auth0. I can't dedicate the
time to think about this at the moment, but am flagging it for more
thorough review.

—
You are receiving this because you authored the thread.
Reply to this email directly, view it on GitHub
https://github.com/begriffs/postgrest/issues/906#issuecomment-315812067,
or mute the thread
https://github.com/notifications/unsubscribe-auth/AAxN25jP9r9DDBrw3HycnF-ZfTLN85V8ks5sO5E1gaJpZM4OR3x3
.

posix4e picture posix4e on 31 Jul 2017

Can you point me to an example of the new auth0 api, like a howto guide? I can use that to learn more about how postgrest should fit in.

One piece of good news is that there is now a PR ready (except for a performance improvement) which allows asymmetric encryption keys, which I thought someone mentioned is another new auth0 requirement.

begriffs picture begriffs on 6 Aug 2017

Great will do . https://github.com/posix4e/reserve-my-life should have it
but I haven't checked the code in a while.
On Sat, Aug 5, 2017 at 4:52 PM Joe Nelson notifications@github.com wrote:

Can you point me to an example of the new auth0 api, like a howto guide? I
can use that to learn more about how postgrest should fit in.

One piece of good news is that there is now a PR ready (except for a
performance improvement) which allows asymmetric encryption keys, which I
thought someone mentioned is another new auth0 requirement.

—
You are receiving this because you authored the thread.
Reply to this email directly, view it on GitHub
https://github.com/begriffs/postgrest/issues/906#issuecomment-320476881,
or mute the thread
https://github.com/notifications/unsubscribe-auth/AAxN21FOAsIs7T4qF6rjvpSjqYHWxA8iks5sVQBDgaJpZM4OR3x3
.

posix4e picture posix4e on 6 Aug 2017

Details ++

Overview

Things are getting rowdy over at Auth0, but it’s all in the name of progress.

In order to bring their authentication process in line with published standards, Auth0 is making an effort to push people to a new authentication flow. A recent change, noted in this memo, makes the new flow the default. The process described on postgrest.com is only compatible with the now-”legacy” authentication process for reasons detailed below.

Auth0’s push here is to register services, such as postgrest, and give them their own oauthy-type access token JWTs instead of generic JWTs.

Key Terms

JSON Web Token (JWT) -- Signed token fitting the jwt spec
ID Token -- A JWT containing user profile information. Intended for use by the _client_.
Access Token -- A bearer token to use to access an OAuth resource server.
Open ID Connect (OIDC) -- the standard the that adds authentication to OAuth. OAuth provides the authorization mechanism.

Current Status

The “legacy” authentication process is no longer default, the docs need to instruct the user to turn off OIDC-strict mode. PR here.

Existing “legacy” integrations will continue to work. Integrations will break if they switch to the new flow. The new flow is used if an audience parameter is included in the authentication request OR the developer manually enables the OIDC-compliant toggle in Auth0’s client settings dashboard.

“Legacy” Flow Overview

img_20170830_105216b

  1. User authentication provided by google to Auth0
  2. Auth0 grants a generic JWT to the web app
  3. Web app uses JWT to make requests to postgrest

OIDC-strict Flow Overview

img_20170830_134417b

  1. User authentication provided by google to Auth0
  2. Auth0 issues optionally two tokens to web app

    • Identity Token -- to use in the browser app. Contains user profile information. _Not to be passed on to APIs_

    • Access Token -- to use as a bearer token making calls to postgrest. Contains only an arbitrary user identifier in the sub claim

  3. Web app uses Access Token to make request to postgrest

OIDC-strict Requirements

For Auth0 applications:

  • Role information will need to be provided in a different claim. The role claim will now be filtered out by Auth0. Two options seem viable:

    • Namespace role, so that it is not filtered out.

      Eg. https/my-postgrest/role: basic_user

    • Use the scopes claim to determine a user’s role

      Not sure what the mechanics would be here. Scopes are conventionally split up by read / write and resource. But looking for a role:<user-role> in the scope part of the JWT might give us what we want.

  • An aud claim will be included in these new access tokens; per #955, this requires a way to match on that expectation. A setting in the config file seems like the way to do this. The same setting could be used to namespace other claims, such as role.

For non-Auth0 applications:

  • These will of course continue to work as they always have. Outside a speculative threat of token misappropriation, there’s no reason for users to configure a token’s audience. role is an acceptable name for a claim if developers assemble their own JWTs.

Integration Process from Developer’s Perspective (Draft)

The steps to integrate with the _new_ OIDC pipeline are similar, but with some changes and additions:

  1. NEW: An ‘API’ must be created in the Auth0 dashboard
    This will be our postgrest api.
  2. UNCHANGED: A ‘client’ must be created in the Auth0 dashboard
    Eg. a single page app (SPA) that will access our postgrest api
  3. CHANGED: Integrate client with Auth0
    Now, we acquire an ‘access token’ instead of an ‘id token’
    Lock.js does this pretty elegantly, just as before. However, new rules limit which claims can be added to this token, so role information will have to be stored elsewhere.
  4. CHANGED: Add a rule to Auth0 processing such that the role information is added to the access token. This information can be included in a namespaced claim, eg. https://my-postgrest/role, in one of the ~20 standard claims, or in token metadata, eg. scope
  5. NEW: Add an jwt-audience value to the postgrest configuration file
    OIDC access tokens always have an aud field. So unless we match it appropriately, we'll see the error noted in #955

I'm pretty confident there's a solution here that doesn't require any additional thought on the part of the developer, but it will take some work here.

willscripted picture willscripted on 30 Aug 2017
👍9

@will-ob great research, helps A LOT with implementing this compatibility
Well done, this will surely speed things up 👍

ruslantalpa picture ruslantalpa on 30 Aug 2017

@ruslantalpa of course :)

I think aud will be figured out shortly in #955. So really, if we want to go forward with supporting Auth0, the only decision here is to decide how role information will be passed.

In scope, or in a configurable claim like https://mypgst/role, are the two options that jumped out at me.

Most of the work will be in updating the documentation, I suspect.

willscripted picture willscripted on 1 Sep 2017

So excited that y'all are working on this.
On Fri, Sep 1, 2017 at 9:07 AM will-ob notifications@github.com wrote:

@ruslantalpa https://github.com/ruslantalpa of course :)
I think aud will be figured out shortly in #955
https://github.com/begriffs/postgrest/issues/955. So really, if we want
to go forward with supporting Auth0, the only decision here is to decide
how role information will be passed.

In scope, or in a configurable claim like https://mypgst/role, are the
two options that jumped out at me.

Most of the work will be in updating the documentation, I suspect.

—
You are receiving this because you authored the thread.
Reply to this email directly, view it on GitHub
https://github.com/begriffs/postgrest/issues/906#issuecomment-326620241,
or mute the thread
https://github.com/notifications/unsubscribe-auth/AAxN25q6FwKc_SVKFDbN9VhPhVFJFke0ks5seCu_gaJpZM4OR3x3
.

posix4e picture posix4e on 2 Sep 2017
👍1

It appears that the scope claim encodes which actions (read/write/delete) are permitted on which API endpoints. In PostgREST this is managed inside the database and cannot be specified by the client except indirectly by identifying the desired database role. Therefore I think using a custom claim is more appropriate for specifying the role.

As for which custom claim in particular, OIDC specifies:

other Claims MAY be used in conjunction with the standard Claims. When using such Claims, it is RECOMMENDED that collision-resistant names be used for the Claim Names

However Auth0 goes a step further and mandates that additional claims must be a well-formed url:

Any non-Auth0 HTTP or HTTPS URL can be used as a namespace identifier, and any number of namespaces can be used. The namespace URL does not have to point to an actual resource, it’s only used as an identifier and will not be called by Auth0.

If we were namespacing our role claim, I would have preferred a name like postgrest/role, but I guess the Auth0 gods have decreed otherwise. (Might be worth investigating Okta or Keycloak if Auth0 gets increasingly draconian.) To use the url style, I could imagine picking our actual documentation domain name, or a shorter one, one of these:

Does it need to include an actual top-level domain? If not we could also use https://postgrest/role

begriffs picture begriffs on 6 Sep 2017

@begriffs or forget all of that, and just provide a config value like
role-claim-key = 'role'
where the default is the old name (backward compatible) and then each user can choose his own custom key (be that url or anything else)

ruslantalpa picture ruslantalpa on 6 Sep 2017

That sounds nice, just let them use whatever they want. 👍

begriffs picture begriffs on 6 Sep 2017

Therefore I think using a custom claim is more appropriate for specifying the role.

That makes sense to me :+1:

Does it need to include an actual top-level domain?

It does not. It actually doesn't even allow . periods in the 'domain name' oddly enough

or forget all of that, and just provide a config value

I like this. Especially if role is the default value. Then existing postgrest users need not worry about additional configuration.

Might be worth investigating Okta or Keycloak if Auth0 gets increasingly draconian

With 10k stargazers, Okta or Keycloak might invest some engineering attention themselves. This would be a great opportunity for them to expand their product reach. I quite like Auth0, but I would not have discovered them if not for these docs.

willscripted picture willscripted on 6 Sep 2017

I think specifying a config value as @ruslantalpa suggested is the best approach. However, I'd like it to be flexible enough to handle whatever the structure of the JWT (not just a top level claim key). To do this, I think using jspath would be a good choice.

So if you want to select the top level key "role" (the default) you could specify it as:

role-claim-key = '.role'

But if you'd prefer to have a nested key, e.g. {... "postgrest": {"role": "foo"} ... } then:

role-claim-key = '.postgrest.role'
russelldavies picture russelldavies on 18 Sep 2017

I do like the idea of being able to specify the path. As an example, here is how keycloak exposes roles for realms and for clients (where I was specifically configuring a "member" role in keycloak that I want to line up with the member role I defined in postgrest):

{
  "exp": 1505488999,
  "nbf": 0,
  "iat": 1505488699,
  "iss": "http://localhost:2015/auth/realms/havendev",
  "aud": "havendev",
  ... some stuff removed
  "realm_access": {
    "roles": [
      "member",
      "uma_authorization"
    ]
  },
  "resource_access": {
    "havendev": {
      "roles": [
        "member"
      ]
    },
    "account": {
      "roles": [
        "manage-account",
        "manage-account-links",
        "view-profile"
      ]
    }
  },
  "name": "User1 One",
  "preferred_username": "[email protected]",
  "email": "[email protected]"
}
statik picture statik on 19 Sep 2017

@statik I also use Keycloak so this is exactly the reason I suggested it although I was also thinking about other systems.

russelldavies picture russelldavies on 19 Sep 2017

ANy updates here?

posix4e picture posix4e on 17 Oct 2017

I wish I'd stumbled upon this earlier. In my case I just changed the role claim directly in the postgrest code and built it from source again. Adding this as a parameter in the config file would be awesome.

marsouin picture marsouin on 26 Oct 2017
👍4

Updates on this?

Sebastianbrg picture Sebastianbrg on 15 Mar 2018

Hello everyone. I ran into this today, and it seems to be a showstopper. Even after disabling OIDC compliance in Auth0, I am unable to set non-namespaced keys on new clients. (Reference to forum discussion).

I would be glad to implement one of the suggestion here in a PR. Adding a configuration field to customize the name seems simple enough. It's probably worth deciding about json-path first though—it'd be great to hear from one of the maintainers on that!

Thanks

kofigumbs picture kofigumbs on 21 Mar 2018

Couldn't get the proposed jspath lib to work, so I implemented a subset of the jspath dsl, now is possible to use the role-claim-key config value like:

# for this jwt
# {.."postgrest":{"roles": ["other", "author"]}..}
role-claim-key = ".postgrest.roles[1]"

# {.."https://www.example.com/role": "author"..}
role-claim-key = ".\"https://www.example.com/role\""
# non (alphanumerical or one of "_$@") chars can go inside quotes

Anyone can checkout #1091 and see if it works for its use case.

steve-chavez picture steve-chavez on 8 Apr 2018

@steve-chavez Hey, I've been working on this bug too. I'll check it out.

jxv picture jxv on 8 Apr 2018

@jxv @hkgumbs Did the PR work for your use cases?

steve-chavez picture steve-chavez on 23 Apr 2018

I'll consider the PR enough for all the use cases.

steve-chavez picture steve-chavez on 30 Apr 2018

If anyone has a working example of the new role-claim-key config working with the new Auth0 flow please consider adding it to the docs https://github.com/begriffs/postgrest-docs/issues/85.

steve-chavez picture steve-chavez on 3 May 2018

Is there any way to remove the default role-claim-key? We handle setting the role via pre-request and would like to disable the default mechanism. For now I'm setting role-claim-key to a bogus key, which works, but that's just a hack, of course…

witsch picture witsch on 29 Jan 2019

@witsch No way to disable the default jwt mechanism, maybe open another issue with your use case to discuss.

steve-chavez picture steve-chavez on 4 Feb 2019
Was this page helpful?
0 / 5 - 0 ratings

Related issues

sscarduzio picture sscarduzio  ·  30Comments
tomberek picture tomberek  ·  19Comments
isairz picture isairz  ·  24Comments
ric2b picture ric2b  ·  21Comments
timbod7 picture timbod7  ·  20Comments