Authorization Superissue, v5.0.0 proposal

Recently we've had a lot of papercuts with the provider's authentication mechanism. I've performed a bunch of testing (see results below) and I've come up with a list of behavior that I think is broken in the current release that I think we can fix in the next major version.

Terraform Version

Terraform v1.0.11
on linux_amd64

Affected Resource(s)

Multiple resources: this issue concerns our authorization policies for the terraform provider

Terraform Configuration Files

Here's an example that creates a repository, used in attempting to reproduce #876.

terraform {
  required_providers {
    github = {
      source = "integrations/github"
      version = "4.18.0"
    }
  }
}

provider "github" {
  owner = "kfcampbell-terraform-provider"
  token = "ghp_personal_token_redacted"
}


resource "github_repository" "app_repo" {
  name        = "876-repro"
  description = "App repository"

  visibility = "private"
  delete_branch_on_merge = "true"
}

Behavior

See these issues for a non-comprehensive list of current authorization issues.

I have responded to a few of these threads (#876, #878, #655) with reproduction cases.

I've performed a pretty comprehensive test of authentication results

Release v5.0.0 proposed authorization changes:

• Deprecate GITHUB_ORGANIZATION environment variable (and organization provider block configuration) in favor of GITHUB_OWNER
• If no token is present, still process owner variables so that unauthenticated requests may be made against public org-owned repos
• Improve error handling and messaging around missing tokens/owner configuration (currently it's pretty difficult to figure out this is a problem and act accordingly)
• Tweaks to avoid pointless requests (for example, when no token or owner is configured, we try a pointless request to e.g. api.github.com//example-repo, which obviously won't succeed)
• Docs overhaul:
  • Clarify how provider authentication works in the case where both the integrations and hashicorp providers are used (I keep returning to @tibbes's excellent comment here about it)
  • Specify in our docs exactly how the decision tree works for each form of authentication (app, provider PAT config, environment variable PAT config) and when/how they can be combined
• Return an error in some cases where our requests fail but the provider doesn't return an error code (see scenarios described below)

What's next

I'm going to leave this issue open for a couple weeks and hope it inspires some community discussion! Barring major changes to the plan, I'll start work on an implementation in December, and updates will be published to this issue and repo, of course.

References

Related auth issues:

• integration/terraform-provider-github auth doesn't work: "resource can only be used in the context of an organization" #878
• Unable to create a repository in an organisation #876
• Data source github_team returns 404 #655
• Need instructions for migrating from hashicorp/github to integrations/github #652
• terraform-import failure: Cannot import non-existent remote object #647
• Misleading error message when GITHUB_TOKEN not set #598

Authorization tests performed

• no auth, readonly request
  • does not find an owner when an owner is set, and it should
    • the plan/apply succeed, and i don't think they should
  • does not find an owner when an organization is set, and it should
    • the plan/apply succeed, and i don't think they should
    • did get the deprecation notice, which is good
• env var token set, no env var owner or org set
  • readonly request
    • infers owner of token as owner of repo (not correct in my case)
• env var token set, env var owner set
  • readonly request
    • correct retrieves repository information
• env var token set, env var org set to org
  • readonly request
    • correct retrieves repository information and displays deprecation notice
• env var token set, env var org set to individual
  • readonly request
    • request fails since it does an org lookup first
    • however, terraform succeeds and i don't think it should
• provider block owner set, no other config
  • readonly request fails and terraform succeeds with the usual 404
• provider block owner and token set
  • readonly request
    • correctly returns repository information
• provider block organization and token set
  • readonly request
    • correctly returns repository info and displays deprecation notice
• provider block organization and owner, env var owner set
  • readonly request
    • env var config supersedes provider block config
• provider block owner set, env var token set
  • readonly request
    • correctly returns repository info
• provider block config is interchangeable (and interoperable) with env var config, and env var config is always dominant from what i can tell
• app auth, no owner in any form set
  • readonly request
    • 404s on GET /user
• app auth, env var owner set
  • both readonly and write requests work correctly
• app auth, env var organization set
  • readonly request
    • correctly returns repository info and displays deprecation notice
• app auth, env var token set
  • conflicts
• app auth, provider token set
  • conflicts