go-oidc

go-oidc

OpenID Connect is a specification on top of OAuth 2.0 that adds a provider-agnostic API for user attributes. End users perform the regular OAuth 2.0 flow and the response includes a JWT signed by the identity provider with standard claims for a stable identifier, email, display name, and other attributes.

{
  "sub": "12345abcd",
  "email": "janedoe@example.com",
  "email_verified": true,
  "name": "Jane Doe"
}

This package can be used to identify users (and even workload identities) across a large number of identity providers:

• Consumer
  • Google
  • Apple (Sign in with Apple)
  • Microsoft
  • Facebook Login
  • LinkedIn
• Enterprise
  • Microsoft Entra ID
  • Okta
  • Auth0
  • Amazon Cognito
  • OneLogin
• Workload
  • GitHub Actions
  • GitLab CI/CD (ID tokens)
  • Google Cloud Workload Identity Federation
  • AWS (IAM OIDC identity providers)
  • Kubernetes (service account / OIDC tokens)
  • HashiCorp HCP Terraform

go-oidc is a mature OpenID Connect client, and is imported by over 1000 open source projects.

OpenID Connect support for Go

This package enables OpenID Connect support for the golang.org/x/oauth2 package. The client can be initialized through OpenID Connect discovery with the issuer URL and a few additional scopes on the oauth2.Config.

provider, err := oidc.NewProvider(ctx, "https://accounts.google.com")
if err != nil {
    // handle error
}

// Configure an OpenID Connect aware OAuth2 client.
oauth2Config := oauth2.Config{
    ClientID:     clientID,
    ClientSecret: clientSecret,
    RedirectURL:  redirectURL,

    // Discovery returns the OAuth2 endpoints.
    Endpoint: provider.Endpoint(),

    // "openid" is a required scope for OpenID Connect flows.
    Scopes: []string{oidc.ScopeOpenID, oidc.ScopeProfile, oidc.ScopeEmail},
}

// Create an ID Token verifier.
idTokenVerifier := provider.Verifier(&oidc.Config{ClientID: clientID})

OAuth2 redirects are unchanged.

func handleRedirect(w http.ResponseWriter, r *http.Request) {
    http.Redirect(w, r, oauth2Config.AuthCodeURL(state), http.StatusFound)
}

Then, on the response, the ID Token verifier can be used to verify ID Tokens.

func handleOAuth2Callback(w http.ResponseWriter, r *http.Request) {
    // Verify state and errors.

    oauth2Token, err := oauth2Config.Exchange(ctx, r.URL.Query().Get("code"))
    if err != nil {
        // handle error
    }

    // Extract the ID Token from OAuth2 token.
    rawIDToken, ok := oauth2Token.Extra("id_token").(string)
    if !ok {
        // handle missing token
    }

    // Parse and verify ID Token payload.
    idToken, err := idTokenVerifier.Verify(ctx, rawIDToken)
    if err != nil {
        // handle error
    }

    // Extract custom claims
    var claims struct {
        Email         string `json:"email"`
        EmailVerified bool   `json:"email_verified"`
        Name          string `json:"name"`
        Picture       string `json:"picture"`
    }
    if err := idToken.Claims(&claims); err != nil {
        // handle error
    }
}