Teams and access

Every org lists its teams. A team has a name, a role and its members, by GitHub login. People sign in to Infrared with GitHub, and what they can do in each org is the strongest role of the teams that list them.

The platform admin, the account the setup wizard created, keeps full access without a team and still signs in with email and password. So do API tokens.

Roles

Role	What it grants	Where it's valid
platform-admin	Every action in every org, and the actions outside any org (registering and removing clusters).	Teams of the platform org only.
org-admin	Everything a member can do, plus how the org works: create, edit and delete Products; edit, enable and reset AgentRoles and AgentWorkflows; edit the org's teams; turn scheduled runs on or off.	Any org.
member	The work in the org: start AgentWorkflowRuns, approve and reject steps, start Releases and approve promotions, open and move issues, open and resolve incidents.	Any org.
viewer	Reads everything in the org and changes nothing.	Any org.

A person on several teams gets the strongest role. A platform-admin team member has that role in every org, not only the platform org.

Some actions are for the platform admin's password session only, never for someone who signed in with GitHub, whatever their role:

• the setup wizard,
• minting API tokens,
• installing a license,
• recording the GitHub App installation.

People who signed in with GitHub see only the orgs they're on in the org list.

Manage teams

In the UI, open Settings → Teams and choose Edit teams. Add a team, pick its role, and list GitHub logins separated by commas. Saving replaces the org's whole team list. With no teams, only the platform admin can sign in.

The same list is spec.teams on the Organization:

apiVersion: infrared.darkshift.io/v1alpha1
kind: Organization
metadata:
  name: acme
spec:
  displayName: Acme
  teams:
    - name: platform
      role: org-admin
      members: [octocat]
      description: Owns the org's Products and AgentRoles
    - name: checkout
      role: member
      members: [hubot]
    - name: auditors
      role: viewer
      members: [monalisa]

Through the API:

curl https://<host>/api/v1/orgs/<org>/teams -H "Authorization: Bearer $INFRARED_TOKEN"

curl -X PUT https://<host>/api/v1/orgs/<org>/teams \
  -H "Authorization: Bearer $INFRARED_TOKEN" -H 'Content-Type: application/json' \
  -d '{"teams": [{"name": "checkout", "role": "member", "members": ["hubot"]}]}'

PUT replaces every team of the org and needs org-admin. A platform-admin team on any org other than the platform org is refused with 422.

Team names are lowercase DNS labels. GitHub logins match without regard to case.

Sign in with GitHub

Sign-in uses the platform org's GitHub App, the one the setup wizard created, as an OAuth client. People choose Sign in with GitHub on the sign-in page, GitHub asks them to authorize the App, and Infrared reads their GitHub login. Only logins on some team get a session; everyone else goes back to the sign-in page with "not on any team: ask an org admin to add you".

Set it up

1. Give Infrared a public URL. See Expose Infrared over HTTPS. GitHub redirects the browser back to it.

2. Add the callback URL to the App. In GitHub, open the organization's Settings → Developer settings → GitHub Apps, choose the App (infrared-<platform org>), and under Identifying and authorizing users add the callback URL:

   https://<host>/api/v1/auth/github/callback

   The App manifest the setup wizard uses sets no callback URL, so this step is always needed.

3. Check the App's OAuth client. The setup wizard stores the App's client ID and client secret in the Secret github-app (keys client-id and client-secret) in the platform org's namespace, ir-org-<platform org>. If you generate a new client secret on GitHub, write it to that key.

4. Add teams. Put each person's GitHub login on a team in the org they work in.

If sign-in shows "the platform org's GitHub App has no OAuth client", the Secret is missing one of those two keys. If GitHub says the redirect URI isn't associated with the App, step 2 is missing or the host differs.

What a GitHub session shows

Settings → Account shows the GitHub login and the role in each org. Sessions last 12 hours, like password sessions.

Password sign-in limits

The platform admin's email and password sign-in (POST /v1/auth/login) is rate limited:

Limit	What happens
5 failed attempts in a minute from one client	Further attempts from that client get HTTP 429 until the minute passes.
10 failed attempts from one client within 15 minutes	That client is locked out for 15 minutes.
50 failed attempts in a minute across all clients	Every client gets HTTP 429 for a minute.

A successful sign-in clears the client's failures. The 429 response says how long to wait. The counters live in the API's memory, so restarting the API clears them.

A client is its first X-Forwarded-For address, or the connection's address when there's none. Make sure the ingress in front of Infrared sets that header itself rather than passing through what a client sends.

Not yet

• SSO through OIDC (Dex) for sign-in without GitHub.
• Mapping Slack users to GitHub logins.
• Mapping teams to Kubernetes RBAC on workload clusters.

See the roadmap.