Deprecation of GitHub connector's teams_to_logins field

[zmb3]

The GitHub SSO connector's teams_to_logins field can be used to specify how to map GitHub team membership to Teleport roles (not logins). This unfortunate name is the result of a migration from the early days when RBAC did not exist in OSS Teleport.

Here's an example connector configuration:

kind: github
version: v3
metadata:
  name: github
spec:
  client_id: aaa
  client_secret: bbb
  display: GitHub
  redirect_url: https://teleport.example.com:3080/v1/webapi/github/callback
  teams_to_logins:
  # map the 'database' team in the gravitational GitHub org
  # to the 'db-admins' Teleport role
  - organization: gravitational
    team: database
    logins: [ db-admins ]
    # optional kubernetes fields for specifying the kubernetes
    # groups/users that Teleport users in the database team can use
    kubernetes_groups: [ a, b ]
    kubernetes_users:  [ c, d ]

Starting in Teleport 10, we deprecated teams_to_logins and introduced a new teams_to_roles field that better describes this behavior. The equivalent connector configuration looks like this:

kind: github
version: v3
metadata:
  name: github
spec:
  client_id: aaa
  client_secret: bbb
  display: GitHub
  redirect_url: https://teleport.example.com:3080/v1/webapi/github/callback
  teams_to_roles:
  # map the 'database' team in the gravitational GitHub org
  # to the 'db-admins' Teleport role
  - organization: gravitational
    team: database
    roles: [ db-admins ]

To summarize the changes:

• change teams_to_logins to teams_to_roles
• change the logins field to roles

Lastly, note that the kubernetes_groups and kubernetes_users fields are no longer present in the new teams_to_roles mapping. This is another artifact of the pre-RBAC era. To ensure that the correct kubernetes groups and users are set, add these fields to the db-admins role spec instead of specifying them in the connector.

Teleport 10 will continue to accept the old teams_to_logins field, but users should prefer the newer teams_to_roles mapping instead. Starting soon, Teleport 11 will display a warning in the web UI and upon tsh login if the cluster contains a GitHub connector using the deprecated configuration. Updating your connector will clear the alert. When Teleport 12 is released in early 2023 it will not accept connectors with the deprecated teams_to_logins field, so you must update your connectors before upgrading to Teleport 12 to avoid breaking GitHub logins.