tmpl docs: update readme for sso and ssh over ssm changes

Author: johnalotoski

templates/cardano-parts-project/README.md

@@ -32,14 +32,57 @@ Note that the nix version must be at least `2.17` and `fetch-closure`,
 
 ## AWS
 
-Create an AWS user with your name and `AdministratorAccess` policy in the
-$REPO organization, then store your access key in
-`~/.aws/credentials` under the profile name `$REPO`:
+From the parent AWS org, create an IAM identity center user with your name and
+`AdministratorAccess` to the AWS account of the `$REPO` deployment, then store
+the config in `~/.aws/config` under the profile name `$REPO`:
+
+    [sso-session $PARENT_ORG_NAME]
+    sso_start_url = https://$IAM_CENTER_URL_ID.awsapps.com/start
+    sso_region = $REGION
+    sso_registration_scopes = sso:account:access
+
+    [profile $REPO]
+    sso_session = $PARENT_ORG_NAME
+    sso_account_id = $REPO_ARN_ORG_ID
+    sso_role_name = AdministratorAccess
+    region = $REGION
+
+The `$PARENT_ORG_NAME` can be set to what you prefer, ex: `ioe`.  The
+`$IAM_CENTER_URL_ID` and `$REGION` will be provided when creating your IAM
+identity center user and the `$REPO_ARN_ORG_ID` will be obtained in AWS as
+the `$REPO` org ARN account number.
+
+If your AWS setup uses a flat or single org structure, then adjust IAM identity
+center account access and the above config to reflect this.  The above config
+can also be generated from the devshell using:
+
+    aws configure sso
+
+When adding additional profiles the `aws configure sso` command may create
+duplicate sso-session blocks or cause other issues, so manually adding new
+profiles is preferred.  Before accessing or using `$REPO` org resources, you
+will need to start an sso session which can be done by:
+
+    just aws-sso-login
+
+While the identity center approach above gives session based access, it also
+requires periodic manual session refreshes which are more difficult to
+accomplish on a headless system or shared deployer.  For those use cases, IAM
+of the `$REPO` organization can be used to create an AWS user with your name and
+`AdministratorAccess` policy.  With this approach, create an access key set for
+your IAM user and store them in `~/.aws/credentials` under the profile name
+`$REPO`:
 
     [$REPO]
     aws_access_key_id = XXXXXXXXXXXXXXXXXXXX
     aws_secret_access_key = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
 
+No session initiation will be required and AWS resources in the org can be used
+immediately.
+
+In the case that a profile exists in both `~/.aws/config` and
+`~/.aws/credentials`, the `~/.aws/config` sso definition will take precedence.
+
 ## AGE Admin
 
 While cluster secrets shared by all machines are generally handled using AWS
@@ -114,6 +157,13 @@ With that you can then get started with:
     # Find many other operations recipes to use
     just --list
 
+Behind the scenes ssh is using AWS SSM and no open port 22 is required.  In
+fact, the default template for a cardano-parts repo does not open port 22 for
+ingress on security groups.
+
+For special use cases which still utilize port 22 ingress for ssh, ipv4 or ipv6
+ssh_config can be used by appending `.ipv4` or `.ipv6` to the target hostname.
+
 ## Colmena
 
 To deploy changes on an OS level, we use the excellent