Sub claim format for M2M tokens

[adamu]

I want to change some behaviour programmatically based on whether a token is for a user or a machine.
The sub claim in the access token seems to be (and is documented as) identity_provider|user_id for users, and (undocumented as far as I can see) client_id@clients for M2M tokens.

My question is: Is the format of the sub claim for M2M tokens documented anywhere? I’d like to have an official source, rather than writing logic based on observed behaviour.

Thanks.

[mathiasconradt]

Your observation is correct, however the sub syntax / pattern isn’t documented in the public docs as far as I can tell.

Side note: I mentioned this pattern before in this post, where there was a question how to be able to differentiate between tokens issued via Client Credentials Grant and else.

Should my API differentiate between tokens?

The authentication flows / grant types used don’t matter to the API, all that matters in the end is the token, which it needs to verify. The verification is based on signature of and claims within the token. That’s all that matters, not in which way the token has been requested. This docs (and further linked pages) describe what standard claims to verify. https://auth0.com/docs/tokens/guides/validate-access-tokens#jwt-access-tokens Luckily the SDKs and libraries available (which you can find …

[adamu]

Thanks for the confirmation Mathias.

Does that mean we can depend on this behaviour of the sub claim being client id@clients to distinguish M2M grants, and it’s unlikely to change in the foreseeable future?

[mathiasconradt]

and it’s unlikely to change in the foreseeable future?

Unlikely to change in the foreseeable future: yes; guaranteed: no

What’s the use case from a business logic perspective, that you need to distinguish here?

Note that you can also go a different route with a rule and hook. Since based on rule/hook, you know the OAuth02 grant type being used, you could consider adding a custom claim to the token.

M2M token requests always go through the Client Credentials Exchange hook, while user authentication requests always go through a Rule.

So, depending where it’s coming from, you could add a custom claim

context.accessToken['https://mynamespace/ism2m'] = true|false

[adamu]

We are actually using a client credentials hook already. I was considering if it’s the best approach.

The business case is that we have an additional layer of permissions for some endpoints on top of the scopes. For those endpoints, we want to allow requests from users with certain roles, or M2M tokens. Both of these are currently managed by creating custom claims (for the users, we use a Rule to add the claim).

The reason I was considering using the sub claim, is that a custom hook requires that we write application-specific logic in Auth0 that applies to all the clients and applications as a whole. Since this is an application-specific requirement, I wanted to implement the logic in the application, rather than at a central level which could potentially affect other APIs and Clients too.

[adamu]

Thinking about this some more.

As the format of the sub claim cannot be guaranteed, and as we are already using a custom claim in Auth0 on top of the user roles, I think the custom claim for the M2M tokens makes the most sense for now (at least while we are using a layer on top of scopes to manage permissions).

Thanks for the discussion.

[mathiasconradt]

Agree, adding the custom claim is close to zero effort and future-proof.