Typo in `state` parameter definition on `Microsoft identity platform and OAuth 2.0 authorization code flow` documentation

Aaron Newton 5 Reputation points
2024-06-19T01:25:33.6533333+00:00

Hello Entra team,

I've noticed what I believe is a typo for the state parameter here:

https://learn.microsoft.com/en-us/entra/identity-platform/v2-oauth2-auth-code-flow#:~:text=A%20value%20included%20in%20the%20request%20that%20is%20also%20returned%20in%20the%20token%20response.

The documentation describes state like so:

"A value included in the request that is also returned in the token response."

This is somewhat misleading. The request this is documented for pertains to the code (i.e., authorization_code) request/response, i.e. https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize. The code returned by this endpoint is then used server-side to request an access_token using credentials via the /{tenant}/oauth2/v2.0/token endpoint. The code response also echos the state property that was provided with the request.

Therefore, stating that the state is returned in the token response is incorrect. The token response examples do not include the state. As far as I understand, the documentation should clarify that the state is provided in the request for the code and is included in the code response.

Can someone please review this and correct the documentation if appropriate.

Kind regards,

Aaron

Microsoft Entra External ID
Microsoft Entra External ID
A modern identity solution for securing access to customer, citizen and partner-facing apps and services. It is the converged platform of Azure AD External Identities B2B and B2C. Replaces Azure Active Directory External Identities.
2,759 questions
0 comments No comments
{count} votes

1 answer

Sort by: Most helpful
  1. Navya 6,615 Reputation points Microsoft Vendor
    2024-06-19T10:33:14.24+00:00

    Hi @Aaron Newton

    Thank you for posting this in Microsoft Q&A.

    Thank you for bringing this to our attention. We have also noticed the same issue with the documentation for the Microsoft Entra Identity Platform, and we appreciate your feedback. We will take this into consideration and work with our team to update the documentation accordingly.

    Hope this helps. Do let us know if you any further queries.

    Thanks,

    Navya.

    0 comments No comments