Non-namespaced custom claims deprecation info is unclear

I was sent an email about action required to remove deprecated non-namespaced custom claims usage from several tenants. I am confused about what is affected and what is actually disallowed here, and am hoping to get some clarification.

  • The email says that non-namespaced custom claims are going to be deprecated on 1/30/2023 and that I should follow the instructions outlined in the Custom Claims Migration doc. But the only date in that doc is 7/28/2022 and it pertains to the the allowance of custom claims. It is unclear to me what is required to be done by 1/30/2023 and what is already happening as of 7/28/2022. Can you clarify?
  • The email lists three tenants that may be affected, and recommends searching logs for type:depnote AND description: *Custom*claims* to get details on what is deprecated. However, for two of the three tenants, that search turns up nothing. Nor are those tenants generating claims payloads > 100KB. How can I go about finding out what flagged these tenants as being potentially affected by this deprecation?
  • For the third tenant, that search turns up deprecation events that look like this:
"details": {
    "feature": {
      "grant": "code",
      "id_token_claims_to_be_allowed": [
      "id": "legacy_custom_claims",
      "name": "Custom claims must be namespaced when they are added through rules / actions / hooks."

Indeed, we have a rule in that tenant that adds the non-namespaced id claim to the idToken. However, the details in that deprecation log event show it as id_token_claims_to_be_allowed, and the migration page does not list id in the list of restricted claims. Is the addition of this non-namespaced claim going to be deprecated or will it continue to be allowed? If the latter, is there a way to filter out these messages from the logs so that only truly deprecated claims usage is shown? From this page, the details field appears not to be searchable.

  • Will any. non-namespaced claims be allowed? The Custom Claims Migration doc seems to indicate that non-namespaced custom claims are allowed as long as they are not on the list of restricted claims and are not added to a token whose audience is an Auth0 API. However, the guide recommends testing the deprecation by toggling this button which, according to the email I was sent, will be the enforced behavior after 1/28/2023:

That says that custom claims MUST be namespaced. I don’t see an exception there. Should I expect the behavior suggested in the Custom Claims Migration doc or the text under that button?


Hi there @clandestine!

On 1/30/23 the option to allow custom non-namespaced claims will no longer be available - That is, custom non-namespaced claims will be allowed in all tenants. The new restrictions along with tenants that have rules/actions adding non-namespaced custom claims that currently aren’t added to tokens (haven’t toggled off the setting) will introduce breaking changes when all tenants are moved over to the new behavior. This is the main concern and reason for deprecation language.

On 7/28/2022 the toggle to enforce that custom claims must be namespaced was introduced, and thus the ability to allow custom non-namespaced claims as well. By default, I believe this is toggled “on” for all tenants.

This claim will continue to be allowed - I agree that the messaging is a bit confusing here.

Overall, it’s easiest to think about this as toggled “on” as legacy no custom namespace behavior, and toggled “off” as the new behavior which will be enforced by default come 1/30/2023.

Great questions and I hope this helps to clarify!

1 Like

Thank you. That is helpful.

1 Like

No problem, happy to help!

This topic was automatically closed 14 days after the last reply. New replies are no longer allowed.