Skip to content

fix(docs): match auth and getting-started to the platform code - #5

Merged
Alexanderamiri merged 2 commits into
mainfrom
fix/docs-match-code
Oct 31, 2026
Merged

fix(docs): match auth and getting-started to the platform code#5
Alexanderamiri merged 2 commits into
mainfrom
fix/docs-match-code

Conversation

@Alexanderamiri

@Alexanderamiri Alexanderamiri commented Oct 31, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

Merge after javaBin/platform#180. The GitHub team role default and the AWS access flow described here are what platform#180 (fix/provisioner-team-access) implements; they are not true on platform main yet.

Problem

A developer-experience audit found these docs disagree with the platform code:

  • auth.md and platform-overview.md say the internal Cognito pool signs in through Google Workspace SAML. platform#175 moved it to Google OIDC (terraform/platform/identity/main.tf, provider Google). In live AWS both internal-pool clients offer only Google.
  • auth.md, getting-started.md and platform-overview.md cite groups/heros.yaml. The registry file is groups/members.yaml. getting-started.md also said helter is implied; the registry now requires every membership to be listed.
  • auth.md lists javabin-developer as a normal permission set. SSO sessions carry no team tag, so it cannot reach team resources (platform CLAUDE.md, known issues).
  • getting-started.md says sessions last about 8 hours. Every permission set is PT4H (terraform/org/variables.tf, team_provisioner/handler.py; confirmed live for all 8 permission sets).
  • Nothing told a developer what to do when Google signs them in but AWS refuses them because their account isn't provisioned into Identity Center. That just happened to a developer.

Change

  • auth.md: Cognito internal pool is Google OIDC (Internal consent screen, @java.no only). Corrected the Identity Center section: team permission sets, registry groups and the permission sets they get, javabin-developer's limitation, 4h sessions. New sections: "How sign-in works" (Google provisions only direct members of drift@, styret@ and javabin-developer@java.no; the provisioner adds team and kodesmia members to javabin-developer@; Google SCIM creates the Identity Center user; the provisioner run every 3 hours adds them to team-<team>, giving the javabin-team-<team> role) and "When AWS sign-in fails" (not provisioned: ask a platform admin; role missing: wait for the 3-hourly run, then ask a platform admin).
  • getting-started.md says sessions last about 8 hours. Every permission set is PT4H (terraform/org/variables.tf, team_provisioner/handler.py; confirmed live for all 8 permission sets).
  • Nothing told a developer what to do when Google signs them in but AWS refuses them because their account isn't provisioned into Identity Center. That just happened to a developer.

Change

  • auth.md: Cognito internal pool is Google OIDC (Internal consent screen, @java.no only). Corrected the Identity Center section: team permission sets, registry groups and the permission sets they get, javabin-developer's limitation, 4h sessions. New sections: "How sign-in works" (Google account, then Google AWS app SCIM auto-provisioning scope, then registry provisioning into team-<team>, then portal or CLI) and "When AWS sign-in fails" (not provisioned: a Google admin has to add the account to the app's auto-provisioning scope, then someone re-runs Provision Teams/Provision Groups, because the provisioner skips users who aren't in Identity Center yet).
  • getting-started.md: GitHub team role (members without role: are maintainers, role: member restricts them; the Google Group keeps MEMBER unless role: maintainer), the AWS access flow above, members.yaml, explicit memberships, access.yaml in the tree, 4h sessions, a warning about javabin-developer, and a link to the troubleshooting section.
  • platform-overview.md: OIDC, members.yaml.

Verification

Checked every statement against platform origin/main (identity module, terraform/org, team_provisioner sync_identity_center_group/sync_group_to_identity_center skip logic, dns portal redirect), registry origin/main (groups/, workflows) and live AWS read-only: internal-pool IdPs and client IdPs, permission set session durations, aws.javabin.no 302 to https://javabin.awsapps.com/start/. Identity Center has 24 users against ~70 registry members, which fits a limited auto-provisioning scope. I could not see the Google Admin side, so the scope itself isn't confirmed. The role default and AWS access flow are checked against platform fix/provisioner-team-access (#180): GITHUB_DEFAULT_TEAM_ROLE and _google_role_for in team_provisioner/handler.py, SCIM_GROUPS/AWS_ACCESS_GROUP, sync_access_members on the rate(3 hours) schedule in terraform/platform/lambdas/main.tf, _ensure_team_permission_set, and docs/lambda-functions.md "How a member gets AWS access". Docs-only change, so there are no tests.

The CLI has the same problems (cmd/aws.go "about 8 hours", README.md "~8h", cmd/secret.go and CLAUDE.md "needs javabin-developer"). Those are reported separately for the javabin-cli repo.

🤖 Generated with Claude Code

@Alexanderamiri @claude
fix(docs): match auth and getting-started to the platform code
7fbede6 
Internal Cognito pool uses Google OIDC, the registry file is
groups/members.yaml, SSO sessions last 4 hours, and javabin-developer
cannot reach team resources. Adds how AWS sign-in works end to end and
what to do when a Google account is not provisioned into Identity Center.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@Alexanderamiri Alexanderamiri mentioned this pull request Oct 31, 2026
Merged
@Alexanderamiri

Alexanderamiri commented Oct 31, 2026

Copy link
Copy Markdown
Member Author

The review follow-up only touched the platform repo, so this PR has no changes. Details: javaBin/platform#179 (commit 1cc0885).

🤖 Generated with Claude Code

@Alexanderamiri Alexanderamiri mentioned this pull request Oct 31, 2026
Merged
@Alexanderamiri @claude
docs: describe GitHub team role default and how AWS access is provisi…
cc27d9b 
…oned

Members without role: are GitHub team maintainers; role: member restricts
them. AWS access goes through direct membership of javabin-developer@,
Google SCIM, and the 3-hourly provisioner run (platform #180).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@Alexanderamiri

Alexanderamiri commented Oct 31, 2026

Copy link
Copy Markdown
Member Author

Pushed cc27d9b: the GitHub team role now matches platform#180 (no role: means maintainer, role: member restricts), and auth.md/getting-started.md describe the actual AWS access flow (direct members of javabin-developer@, then Google SCIM, then the 3-hourly provisioner run into team-<team>; ask a platform admin if not provisioned). Merge after platform#180.

@Alexanderamiri
Alexanderamiri merged commit 323c4a9 into main Oct 31, 2026
Alexanderamiri added a commit to javaBin/platform that referenced this pull request Oct 31, 2026
@Alexanderamiri @claude
fix(docs): describe per-team ECS execution roles and the Google OIDC …
73f79c0 
…identity module (#179)

## Problem

Several comments and docs still describe the old setup:

- `terraform/modules/cognito-app-client/main.tf` says "the shared
execution role reads /<project>/apps/* at task launch". Tasks now use
per-team roles `javabin-ecs-exec-{team}`, which can read only
`/javabin/apps/{team}/*` (`terraform/platform/iam/main.tf`,
`terraform/modules/platform-data/main.tf`).
- The `terraform/platform/iam/main.tf` header still calls
`javabin-ecs-execution` "the shared execution role for all ECS tasks"
that "reads secrets". The resource comment right below it says the role
is deprecated and has no secrets access.
- `docs/platform-modules.md` and `docs/reusable-modules.md` list
`javabin-ecs-execution` as the role that reads secrets / the role
`platform-data` returns.
- The `docs/platform-modules.md` identity section says "Not yet
implemented ... blocked on Google Admin access for SAML federation". The
module is deployed and the internal pool signs in through Google OIDC
(#175).

## Change

The comments and docs now match the code. Only comments and docs change;
there is no behaviour change.

The developer-facing docs (auth, getting started, how AWS sign-in works
and what to do when a Google account isn't provisioned into Identity
Center) live in javaBin/docs: javaBin/docs#5

## Verification

- Checked the text against `iam/main.tf` (`aws_iam_role.ecs_exec_team`,
`ecs_exec_team_secrets`), `platform-data`
(`data.aws_iam_role.ecs_execution` = `javabin-ecs-exec-${var.team}`),
`identity/main.tf` and `variables.tf` (`internal_identity_providers =
["Google"]`). Read-only live check: the internal pool has `Google` and
`GoogleSAML`, and both clients offer only `Google`.
- `terraform fmt -check` on the touched dirs passes. `terraform
validate` in `cognito-app-client` passes (the only warning, about
`aws_region.name`, was already there).

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@Alexanderamiri