feat: add authz support for GitHub teams (#4139)

* feat: fetch github teams for oidc groups claim

Signed-off-by: Ramkumar Chinchani <rchincha.dev@gmail.com>

* feat: enable GitHub team membership inclusion in access control groups

Signed-off-by: Ramkumar Chinchani <rchincha.dev@gmail.com>

* feat(auth): paginate org/team groups and tolerate missing read:org scope

- apply the same optional-scope strategy to org lookup: paginate org pages and
  treat 403 Forbidden as non-fatal
- keep non-403 org/team API errors as hard failures
- preserve provider-returned casing for org/team-derived group values
- add anonymized debug logging (counts/page metadata only)
- extend tests for org pagination, org 403 optional behavior, team pagination,
  team 403 optional behavior, and team 5xx hard-fail behavior

Signed-off-by: Ramkumar Chinchani <rchincha.dev@gmail.com>

* test(auth): align GitHub user info test names and org-forbidden assertion

- rename two Convey blocks so names match the mocked failing API call
- assert org-forbidden case does not include "MyOrg" (real org group) instead
  of "testOrg"

Signed-off-by: Ramkumar Chinchani <rchincha.dev@gmail.com>

* test(auth): keep org login casing consistent in paginated teams mock

Use MyOrg consistently across mocked /user/orgs and /user/teams payloads in the
same success scenario, and align expected team-derived group assertions.

Signed-off-by: Ramkumar Chinchani <rchincha.dev@gmail.com>

* test(auth): align ListOrgs-forbidden teams casing with case-sensitive group checks

Use MyOrg in the mocked /user/teams payload for the ListOrgs-forbidden
scenario and assert MyOrg/infra accordingly to keep test casing semantics
consistent.

Signed-off-by: Ramkumar Chinchani <rchincha.dev@gmail.com>

* test(auth): use consistent MyOrg casing in teams-forbidden assertion

Align negative team-group assertion with MyOrg casing used by org mocks and
other case-sensitive authz group checks.

Signed-off-by: Ramkumar Chinchani <rchincha.dev@gmail.com>

* docs(auth): align GitHub teams example casing with login-derived groups

Use consistent org casing in the README example (myorg -> myorg/infra) to
reflect that group strings follow GitHub login values and are not lowercased by
zot.

Signed-off-by: Ramkumar Chinchani <rchincha.dev@gmail.com>

* docs(auth): clarify GitHub group casing is preserved

Document that org/team group strings use GitHub login/slug casing as-is (no
normalization), so policy entries must match exact case.

Signed-off-by: Ramkumar Chinchani <rchincha.dev@gmail.com>

* fix(auth): improve GitHub ListEmails failure logging

Log the underlying error and use an operation-accurate message when
client.Users.ListEmails fails in GetGithubUserInfo.

Signed-off-by: Ramkumar Chinchani <rchincha.dev@gmail.com>

---------

Signed-off-by: Ramkumar Chinchani <rchincha.dev@gmail.com>
Co-authored-by: Kevin Andrews <kevin@nforced.uk>

examples/README.md

@@ -415,6 +415,7 @@ zot can be configured to use the above providers with:
   }
 ```
 
+
 To login with either provider use http://127.0.0.1:8080/zot/auth/login?provider=\<provider\>&callback_ui=/home
 for example to login with github use http://127.0.0.1:8080/zot/auth/login?provider=github&callback_ui=/home
 
@@ -441,6 +442,29 @@ for example github callback url would be http://127.0.0.1:8080/zot/auth/callback
 
 If network policy doesn't allow inbound connections, this callback wont work!
 
+#### GitHub Teams in Access Control
+
+When authenticating with the GitHub provider, if you include the `read:org` scope, zot will fetch both the user's Organization memberships and their Team memberships.
+Team memberships are formatted as `<organization>/<team-slug>` and added to the user's groups. You can use these in your access control policies. For example, if a user belongs to the `Infra` team in the `myorg` organization, the group name will be `myorg/infra`.
+Group strings preserve GitHub-provided `login`/`slug` casing (no lowercasing is applied), so policy group values must match that exact casing.
+
+```json
+{
+  "accessControl": {
+    "repositories": {
+      "myorg/infrastructure/**": {
+        "policies": [
+          {
+            "groups": ["myorg/infra"],
+            "actions": ["read", "create", "update", "delete"]
+          }
+        ]
+      }
+    }
+  }
+}
+```
+
 dex is an identity service that uses OpenID Connect to drive authentication for other apps https://github.com/dexidp/dex
 To setup dex service see https://dexidp.io/docs/getting-started/