Rules Doc Page Has Incorrect Info in It

[CatGuardian]

The documentation page for rules has incorrect information in it which is very misleading for anyone who wants to create rules.

The page I'm talking about: https://auth0.com/docs/rules The corresponding file in this repo that needs editing: docs/articles/rules/index.md

Problem Description:

So in the Syntax section it says:

Syntax

A Rule is a function with the following arguments:

• user: the user object as it comes from the identity provider. Check out the User Object in Rules page for a list of the available user properties.

but there is incorrect information in the user description. The user object looks like the linked page when the rule is executed any time EXCEPT when the rule is executed via a token refresh flow. So when the rule is executed because of a token refresh flow, then the user parameter looks different.

Here is an example of the user object I get during a token refresh flow:

{
  name: 'A User's Name Here',
  email: '[email protected]',
  email_verified: true,
  app_metadata: 
   { roles: [ 'claimsAdmin', 'insurer' ],
     type: 'claimsAdmin',
     mySystemUserId: 1 },
  iss: 'https://example.auth0.com/',
  sub: 'auth0|<auth0 id here>',
  aud: '<audience id for my auth0 app>',
  iat: 1566405149,
  exp: 1566441149,
  persistent: {}
}

The user object seems to be the payload of the new JWT that is being created for this refresh token flow.

Problem Resolution (How to Fix The Problem)

So in my mind the documents should be updated to include information about the user object in the event that the rule is executed during a token refresh flow.

Below is one way the documents could be updated, but it isn't the only way. But use the below as a reference for what information should be included in the documentation changes.

My idea is that we should change:

• user: the user object as it comes from the identity provider. Check out the User Object in Rules page for a list of the available user properties.

To:

• user: the user object as it comes from the identity provider. Unless the rule is executed as part of the token refresh flow, in which case the user object is the payload of the new JWT that is about to be created. Check out the User Object in Rules page for a list of the available user properties.

Then the User Object in Rules should be updated to have two sections:

User Object in Rules

When the rule is executed as part of a token refresh flow, then see the User Object in Rules When Executed by a Token Refresh Flow section; otherwise keep reading this section.

and

User Object in Rules When Executed by a Token Refresh Flow

And include the very specific format of the object that is sent when the rule is executed as a token refresh flow.

[CatGuardian]

Ok some more information:

I think I was slightly confused when I wrote up the issue. I wrote the above with the assumption that the token refresh flow is the same as using the legacy delegation endpoint.

So when I say:

Here is an example of the user object I get during a token refresh flow:

I really mean

Here is an example of the user object I get during a call to the delegation endpoint:

And that applies to all of my post. So when you see "token refresh flow" I really mean "delegation endpoint flow".

So there is still an issue with documentation and the documentation should be updated to note that the user object is different when triggered through the use of the delegation endpoint.

ALSO, someone should check to see what the user object looks like when you really do use the token refresh flow. Because I don't know what it looks like when using the token refresh flow as described by that link. I only use the delegation endpoint to exchange an old token for a new token.

So someone should check on that, and if the user object is different when using the token refresh flow, then the documentation should be updated to include what the user object looks like in the token refresh flow instance.

[jeffreylees]

Thanks for the detail in the issue - it will make it much easier for us to follow up with and act on! I'll leave this open until there's a resolution made, but just wanted to comment so you knew it had been seen and would be acted on.

[CatGuardian]

Thank you for leaving that comment! Otherwise I wouldn't have known if it was seen or not.