add issues

docs/how-to/aws-sso/issues.md

@@ -0,0 +1,55 @@
+# SSO Issues
+
+You may run into issues with SSO login.  Some we have encountered are below.  If you run into an issue,
+and it's not in this document (or the other supporting documents indicating the instructions for use), 
+please let us know.
+
+## OIDC vs Device Code
+
+You may use `aws sso login --profile NAME --no-browser` to authenticate to SSO.  And, maybe now you're
+getting a very different result with an OIDC login:
+
+```console
+% aws sso login --profile ent-gov --no-browser
+Browser will not be automatically opened.
+Please visit the following URL:
+ 
+https://oidc.us-gov-east-1.amazonaws.com/authorize?response_type=code&client_id=5Pdom1odK_RbN8HHJ3qq1HVzLWdvdi1lYXN0LTE&redirect_uri=http%3A%2F%2F127.0.0.1%3A39017%2Foauth%2Fcallback&state=5f54b1f8-2a8a-40ec-892f-48935d33c5c3&code_challenge_method=S256&scopes=sso%3Aaccount%3Aaccess&code_challenge=zE7_8WB7K1-J3bnQHpk0HVxJKXqQ4ucqO7n1pxHUYCM
+```
+
+What's going on here?
+
+Well, a newer version (2.22) of the AWS CLI made the [OIDC flow](https://aws.amazon.com/blogs/developer/aws-cli-adds-pkce-based-authorization-for-sso/) the default option.
+
+This can be reverted to the original method by adding `--use-device-code`, like:
+
+```script
+aws sso login --profile ent-gov --no-browser --use-device-code
+```
+
+Here is what Google AI has to say about it:
+
+> AWS SSO redirects to an OIDC link, rather than a device validation link, when using older versions of the AWS CLI or when using the --use-device-code option, which enables the older OAuth 2.0 device authorization flow. In the newer AWS CLI (v2.22.0 and later), the default authentication flow is the PKCE-based authorization code flow, which redirects to a browser window for authentication. Device validation links are associated with the older device code authorization flow, while the OIDC link is associated with the newer PKCE flow. [1, 1, 2, 2, 3, 4, 5]  
+> Here's a more detailed breakdown: [1, 1]  
+> 
+> • Old AWS CLI (before v2.22.0) and --use-device-code: These scenarios will use the OAuth 2.0 device authorization flow, which involves a device code and a validation link. [1, 6]  
+> • Newer AWS CLI (v2.22.0 and later) and no --use-device-code: This scenario will use the PKCE-based authorization code flow, which opens a browser window for authentication, resulting in an OIDC link. [1, 1, 2, 2]  
+> • Device validation links: These were previously used for device-based authentication, allowing users to initiate authentication from a device with a browser and complete the process on a different device. [1, 1]  
+> • OIDC links: These are associated with the PKCE-based authorization code flow and are typically used for web-based authentication, where the user is redirected to a browser window to complete the authentication process. [1, 1, 2, 2]  
+> 
+> In essence, the choice between a device validation link and an OIDC link depends on the AWS CLI version and the specific configuration options used. The newer AWS CLI defaults to the PKCE-based authorization code flow, which uses OIDC links. To use the older device validation flow, you need to use an older AWS CLI version or specify the --use-device-code option. [1, 2]  
+> 
+> Generative AI is experimental.
+> 
+> [1] https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-sso.html
+> [2] https://aws.amazon.com/blogs/developer/aws-cli-adds-pkce-based-authorization-for-sso/
+> [3] https://github.com/aws/aws-cli/issues/9098
+> [4] https://www.linkedin.com/pulse/mitming-aws-iam-identity-center-oidc-authentication-chaim-sanders
+> [5] https://repost.aws/questions/QUxWTBZAyfTFiSHUJRVnqoEg/problem-with-credentials-when-working-with-aws-cli-commands
+> [6] https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-sso.html
+> 
+
+# CHANGELOG
+
+* 1.0.0 -- 2025-05-09
+  - initial