AWS cognito: Add guidance for handling OIDC discovery document changes
Summary
New section advises clients to treat unknown metadata members as optional, avoid hard-coding the set or order of members in the openid-configuration document, and test strict clients against the current document.
Security assessment
Documents forward-compatible/safe parsing of the OpenID Connect discovery document and links to guidance on parsing user pool tokens safely. This is hardening guidance for OIDC client integrations rather than a response to a specific vulnerability, so it is security-adjacent but not tied to a disclosed flaw.
Evidence
+As the OpenID Connect Discovery specification requires, treat metadata members that you don't understand as optional. Don't reject, fail, or throw an error when the document contains a member that your application doesn't use.
Diff
diff --git a/cognito/latest/developerguide/federation-endpoints.md b/cognito/latest/developerguide/federation-endpoints.md index 7366fe1..a4c3a6c 100644 --- a//cognito/latest/developerguide/federation-endpoints.md +++ b//cognito/latest/developerguide/federation-endpoints.md @@ -69,0 +70,21 @@ The updated issuer type is not currently compatible with Application Load Balanc +### Prepare for changes to the discovery document + +The `openid-configuration` document is a standard OpenID Connect discovery document. Amazon Cognito can add metadata entries to it over time to keep it compliant with the OpenID Connect and OAuth 2.0 specifications and to improve compatibility with OIDC client libraries. These additions are backward compatible: Amazon Cognito adds new members, but it does not rename, change the type of, or remove the members that your application already reads. Write your client so that it keeps working as the document grows. + +Ignore members that you don't recognize + + +As the OpenID Connect Discovery specification requires, treat metadata members that you don't understand as optional. Don't reject, fail, or throw an error when the document contains a member that your application doesn't use. + +Don't hard-code the set or order of members + + +Parse the document as a general JSON object rather than a fixed structure. The members can appear in any order, and the set of members can change between requests and over time. Address each member by name, and read each one as the type that the specification defines for it. + +Test strict clients against the current document + + +If your client validates the discovery document strictly, fetch the current document from your user pool's `/.well-known/openid-configuration` endpoint and confirm that your client accepts it before you depend on a specific set of members. + +Amazon Cognito tokens follow the same additive, forward-compatible approach. For more information about parsing the claims in an ID or access token, see [Parse user pool tokens safely](./user-pool-parse-tokens-safely.html). +