# golang/oauth2 architecture

> Architecture diagram of the GitHub repository golang/oauth2, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/golang/oauth2
- Repository: https://github.com/golang/oauth2

## Overview

##### Project type and purpose
- This is a Go client library implementing the OAuth 2.0 specification.
- It provides a core `oauth2` package, an `endpoints` registry for generic OAuth2 providers, plus numerous provider-specific subpackages (e.g. `google`, `facebook`, `amazon`, etc.), and support for advanced flows (device auth, client credentials, external account, downscoping, STS).

##### File structure
- Top-level:
- `.travis.yml`, `go.mod`/`go.sum`, CI, contribution, and license files.
- `oauth2` root files: `oauth2.go`, `token.go`, `transport.go`, `deviceauth.go`, `clientcredentials/`, `authhandler/`.
- `endpoints/` package listing standardized endpoint sets.
- A directory per provider (e.g. `google/`, `facebook/`, `github/`, …), each defining provider-specific endpoints or credential helpers.
- `internal/` contains shared low-level code (transport wrappers, token parsing).
- Within `google/`, subpackages for external account support, impersonation, STS exchange, JWT, SDK helpers, downscope broker, etc.

##### README
- Confirms it is an OAuth2 client library for Go, describes how to run tests, points to documentation, and outlines policy on provider endpoints.

##### Components & Relationships
1. Core oauth2 Package
- Config (client ID/secret, scopes, endpoints)
- TokenSource interface & implementations (e.g. reuse token, refresh token)
- Transport (an `http.RoundTripper` that injects tokens)
2. Endpoints Registry
- Standardized endpoint definitions (AuthURL, TokenURL)
3. Provider Subpackages
- Each provider either:
– Defines a single `Endpoint` (in which case it should live in `endpoints/`), or
– Provides extra helpers (e.g. `google` has JWT, external account credential sources, STS, impersonation, downscoping, SDK wrappers)
4. Advanced Flow Modules
- `deviceauth` – Device code flow
- `clientcredentials` – Client credentials flow
- `authhandler` – Custom HTTP auth handling
5. Internal Helpers
- `internal/transport` – HTTP wrappers
- `internal/token` – Token parsing & storage
6. Test Suites (optional to show coverage)

1. Client code → uses → oauth2.Config
2. Config → references → Endpoints (from `endpoints/` or provider packages)
3. Config → produces → TokenSource
4. TokenSource → interacts → Provider Token Endpoint (HTTP)
5. TokenSource → returns → Token
6. HTTP Client with Transport → injects → Token into requests to target APIs
7. Provider packages (e.g. `google`) → may wrap TokenSource for specific flows (STS, downscope)
8. Advanced Flow modules (device, clientcredentials) → implement → TokenSource interface

c. Architectural Patterns & Principles
- Modular package design—each provider is isolated, core logic is common.
- Interface-driven (`TokenSource`, `http.RoundTripper` wrappers).
- Clear separation of concerns: configuration → token acquisition → request transport.
- Dependency injection: HTTP transport accepts a wrapped RoundTripper.

d. Key Technologies & Frameworks
- Go modules (`go.mod`)
- net/http for REST calls
- JSON for token payloads
- Gerrit-based workflow, Travis CI tests

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Core Package
    subgraph "Core oauth2 Package" 
        direction TB
        Config["oauth2.Config\n(ClientID, Secret, Scopes, Endpoints)"]:::core
        TokenSrcInterface["TokenSource Interface\n(NewToken, Token)"]:::core
        TransportWrapper["Transport (http.RoundTripper)\n(Token injection)"]:::core
    end

    %% Endpoints Registry
    EndpointsRegistry["endpoints/endpoints.go\n(Endpoint constants)"]:::endpoints

    %% Provider Subpackages (single-endpoint definitions)
    subgraph "Provider Subpackages" 
        direction TB
        amazon["amazon.go"]:::provider
        bitbucket["bitbucket.go"]:::provider
        cern["cern.go"]:::provider
        facebook["facebook.go"]:::provider
        fitbit["fitbit.go"]:::provider
        foursquare["foursquare.go"]:::provider
        github["github.go"]:::provider
        gitlab["gitlab.go"]:::provider
        heroku["heroku.go"]:::provider
        hipchat["hipchat.go"]:::provider
        instagram["instagram.go"]:::provider
        jira["jira.go"]:::provider
        kakao["kakao.go"]:::provider
        linkedin["linkedin.go"]:::provider
        mailchimp["mailchimp.go"]:::provider
        mailru["mailru.go"]:::provider
        mediamath["mediamath.go"]:::provider
        microsoft["microsoft.go"]:::provider
        nokiahealth["nokiahealth.go"]:::provider
        odnoklassniki["odnoklassniki.go"]:::provider
        paypal["paypal.go"]:::provider
        slack["slack.go"]:::provider
        spotify["spotify.go"]:::provider
        stackoverflow["stackoverflow.go"]:::provider
        twitch["twitch.go"]:::provider
        uber["uber.go"]:::provider
        vk["vk.go"]:::provider
        yahoo["yahoo.go"]:::provider
        yandex["yandex.go"]:::provider
    end

    %% Google Rich Provider
    subgraph "Google Rich Provider" 
        direction TB
        gcore["google.go"]:::rich
        gjwt["jwt.go"]:::rich
        gsdk["sdk.go"]:::rich
        gappengine["appengine.go"]:::rich
        gdefault["default.go"]:::rich
        gerror["error.go"]:::rich
        gdownscope["downscoping.go"]:::rich
        gext_aws["aws.go"]:::rich
        gext_base["basecredentials.go"]:::rich
        gext_exec["executablecredsource.go"]:::rich
        gext_file["filecredsource.go"]:::rich
        gext_header["header.go"]:::rich
        gext_prog["programmaticrefreshcredsource.go"]:::rich
        gext_url["urlcredsource.go"]:::rich
        gimpersonate["impersonate.go"]:::rich
        gstsex["sts_exchange.go"]:::rich
        gstscauth["clientauth.go"]:::rich
    end

    %% Advanced Flow Modules
    subgraph "Advanced Flow Modules" 
        direction TB
        DeviceAuth["deviceauth.go"]:::advanced
        ClientCreds["clientcredentials.go"]:::advanced
        AuthHandler["authhandler.go"]:::advanced
    end

    %% Internal Helpers
    subgraph "Internal Helpers" 
        direction TB
        InternalOAuth2["internal/oauth2.go"]:::internal
        InternalToken["internal/token.go"]:::internal
        InternalTransport["internal/transport.go"]:::internal
    end

    %% Flow
    ClientApp["Client Application"]:::external
    ClientApp -->|"uses"| Config
    Config -->|"references"| EndpointsRegistry
    Config -->|"builds"| TokenSrcInterface
    TokenSrcInterface -->|"fetch token"| EndpointsRegistry
    TokenSrcInterface -->|"fetch token"| amazon
    TokenSrcInterface -->|"fetch token"| gcore
    DeviceAuth -->|"implements"| TokenSrcInterface
    ClientCreds -->|"implements"| TokenSrcInterface
    AuthHandler -->|"customizes"| TransportWrapper
    TokenSrcInterface -->|"returns Token"| TransportWrapper
    TransportWrapper -->|"injects token"| ClientAPI["Target API Calls"]:::external

    %% Click Events - Core
    click Config "https://github.com/golang/oauth2/blob/master/oauth2.go"
    click TokenSrcInterface "https://github.com/golang/oauth2/blob/master/token.go"
    click TransportWrapper "https://github.com/golang/oauth2/blob/master/transport.go"

    %% Click Events - Endpoints
    click EndpointsRegistry "https://github.com/golang/oauth2/blob/master/endpoints/endpoints.go"

    %% Click Events - Providers
    click amazon "https://github.com/golang/oauth2/blob/master/amazon/amazon.go"
    click bitbucket "https://github.com/golang/oauth2/blob/master/bitbucket/bitbucket.go"
    click cern "https://github.com/golang/oauth2/blob/master/cern/cern.go"
    click facebook "https://github.com/golang/oauth2/blob/master/facebook/facebook.go"
    click fitbit "https://github.com/golang/oauth2/blob/master/fitbit/fitbit.go"
    click foursquare "https://github.com/golang/oauth2/blob/master/foursquare/foursquare.go"
    click github "https://github.com/golang/oauth2/blob/master/github/github.go"
    click gitlab "https://github.com/golang/oauth2/blob/master/gitlab/gitlab.go"
    click heroku "https://github.com/golang/oauth2/blob/master/heroku/heroku.go"
    click hipchat "https://github.com/golang/oauth2/blob/master/hipchat/hipchat.go"
    click instagram "https://github.com/golang/oauth2/blob/master/instagram/instagram.go"
    click jira "https://github.com/golang/oauth2/blob/master/jira/jira.go"
    click kakao "https://github.com/golang/oauth2/blob/master/kakao/kakao.go"
    click linkedin "https://github.com/golang/oauth2/blob/master/linkedin/linkedin.go"
    click mailchimp "https://github.com/golang/oauth2/blob/master/mailchimp/mailchimp.go"
    click mailru "https://github.com/golang/oauth2/blob/master/mailru/mailru.go"
    click mediamath "https://github.com/golang/oauth2/blob/master/mediamath/mediamath.go"
    click microsoft "https://github.com/golang/oauth2/blob/master/microsoft/microsoft.go"
    click nokiahealth "https://github.com/golang/oauth2/blob/master/nokiahealth/nokiahealth.go"
    click odnoklassniki "https://github.com/golang/oauth2/blob/master/odnoklassniki/odnoklassniki.go"
    click paypal "https://github.com/golang/oauth2/blob/master/paypal/paypal.go"
    click slack "https://github.com/golang/oauth2/blob/master/slack/slack.go"
    click spotify "https://github.com/golang/oauth2/blob/master/spotify/spotify.go"
    click stackoverflow "https://github.com/golang/oauth2/blob/master/stackoverflow/stackoverflow.go"
    click twitch "https://github.com/golang/oauth2/blob/master/twitch/twitch.go"
    click uber "https://github.com/golang/oauth2/blob/master/uber/uber.go"
    click vk "https://github.com/golang/oauth2/blob/master/vk/vk.go"
    click yahoo "https://github.com/golang/oauth2/blob/master/yahoo/yahoo.go"
    click yandex "https://github.com/golang/oauth2/blob/master/yandex/yandex.go"

    %% Click Events - Google
    click gcore "https://github.com/golang/oauth2/blob/master/google/google.go"
    click gjwt "https://github.com/golang/oauth2/blob/master/google/jwt.go"
    click gsdk "https://github.com/golang/oauth2/blob/master/google/sdk.go"
    click gappengine "https://github.com/golang/oauth2/blob/master/google/appengine.go"
    click gdefault "https://github.com/golang/oauth2/blob/master/google/default.go"
    click gerror "https://github.com/golang/oauth2/blob/master/google/error.go"
    click gdownscope "https://github.com/golang/oauth2/blob/master/google/downscope/downscoping.go"
    click gext_aws "https://github.com/golang/oauth2/blob/master/google/externalaccount/aws.go"
    click gext_base "https://github.com/golang/oauth2/blob/master/google/externalaccount/basecredentials.go"
    click gext_exec "https://github.com/golang/oauth2/blob/master/google/externalaccount/executablecredsource.go"
    click gext_file "https://github.com/golang/oauth2/blob/master/google/externalaccount/filecredsource.go"
    click gext_header "https://github.com/golang/oauth2/blob/master/google/externalaccount/header.go"
    click gext_prog "https://github.com/golang/oauth2/blob/master/google/externalaccount/programmaticrefreshcredsource.go"
    click gext_url "https://github.com/golang/oauth2/blob/master/google/externalaccount/urlcredsource.go"
    click gimpersonate "https://github.com/golang/oauth2/blob/master/google/internal/impersonate/impersonate.go"
    click gstsex "https://github.com/golang/oauth2/blob/master/google/internal/stsexchange/sts_exchange.go"
    click gstscauth "https://github.com/golang/oauth2/blob/master/google/internal/stsexchange/clientauth.go"

    %% Click Events - Advanced Flows
    click DeviceAuth "https://github.com/golang/oauth2/blob/master/deviceauth.go"
    click ClientCreds "https://github.com/golang/oauth2/blob/master/clientcredentials/clientcredentials.go"
    click AuthHandler "https://github.com/golang/oauth2/blob/master/authhandler/authhandler.go"

    %% Click Events - Internal
    click InternalOAuth2 "https://github.com/golang/oauth2/blob/master/internal/oauth2.go"
    click InternalToken "https://github.com/golang/oauth2/blob/master/internal/token.go"
    click InternalTransport "https://github.com/golang/oauth2/blob/master/internal/transport.go"

    %% Styles
    classDef core fill:#D0E8FF,stroke:#0366D6,color:#0366D6;
    classDef endpoints fill:#DFFFE0,stroke:#28A745,color:#28A745;
    classDef provider fill:#E8FFEF,stroke:#1F8E3E,color:#1F8E3E;
    classDef rich fill:#E0FFFD,stroke:#006B75,color:#006B75;
    classDef advanced fill:#FFEFD5,stroke:#FF8C00,color:#FF8C00;
    classDef internal fill:#F0F0F0,stroke:#6A737D,color:#6A737D;
    classDef external fill:#FFFFFF,stroke:#444444,color:#444444,stroke-dasharray: 2 2;
```
