README

go-oidc

GoDoc Build Status

OpenID Connect support for Go

This package enables OpenID Connect support for the golang.org/x/oauth2 package.

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, "profile", "email"},
}

OAuth2 redirects are unchanged.

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

The on responses, the provider can be used to verify ID Tokens.

var verifier = provider.Verifier(&oidc.Config{ClientID: clientID})

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 := verifier.Verify(ctx, rawIDToken)
    if err != nil {
        // handle error
    }

    // Extract custom claims
    var claims struct {
        Email    string `json:"email"`
        Verified bool   `json:"email_verified"`
    }
    if err := idToken.Claims(&claims); err != nil {
        // handle error
    }
}
Expand ▾ Collapse ▴

Documentation

Overview

    Package oidc implements OpenID Connect client logic for the golang.org/x/oauth2 package.

    Index

    Constants

    View Source
    const (
    	// JOSE asymmetric signing algorithm values as defined by RFC 7518
    	//
    	// see: https://tools.ietf.org/html/rfc7518#section-3.1
    	RS256 = "RS256" // RSASSA-PKCS-v1.5 using SHA-256
    	RS384 = "RS384" // RSASSA-PKCS-v1.5 using SHA-384
    	RS512 = "RS512" // RSASSA-PKCS-v1.5 using SHA-512
    	ES256 = "ES256" // ECDSA using P-256 and SHA-256
    	ES384 = "ES384" // ECDSA using P-384 and SHA-384
    	ES512 = "ES512" // ECDSA using P-521 and SHA-512
    	PS256 = "PS256" // RSASSA-PSS using SHA256 and MGF1-SHA256
    	PS384 = "PS384" // RSASSA-PSS using SHA384 and MGF1-SHA384
    	PS512 = "PS512" // RSASSA-PSS using SHA512 and MGF1-SHA512
    )
    View Source
    const (
    	// ScopeOpenID is the mandatory scope for all OpenID Connect OAuth2 requests.
    	ScopeOpenID = "openid"
    
    	// ScopeOfflineAccess is an optional scope defined by OpenID Connect for requesting
    	// OAuth2 refresh tokens.
    	//
    	// Support for this scope differs between OpenID Connect providers. For instance
    	// Google rejects it, favoring appending "access_type=offline" as part of the
    	// authorization request instead.
    	//
    	// See: https://openid.net/specs/openid-connect-core-1_0.html#OfflineAccess
    	ScopeOfflineAccess = "offline_access"
    )

    Variables

    This section is empty.

    Functions

    func ClientContext

    func ClientContext(ctx context.Context, client *http.Client) context.Context

      ClientContext returns a new Context that carries the provided HTTP client.

      This method sets the same context key used by the golang.org/x/oauth2 package, so the returned context works for that package too.

      myClient := &http.Client{}
      ctx := oidc.ClientContext(parentContext, myClient)
      
      // This will use the custom client
      provider, err := oidc.NewProvider(ctx, "https://accounts.example.com")
      

      func Nonce

      func Nonce(nonce string) oauth2.AuthCodeOption

        Nonce returns an auth code option which requires the ID Token created by the OpenID Connect provider to contain the specified nonce.

        Types

        type Config

        type Config struct {
        	// Expected audience of the token. For a majority of the cases this is expected to be
        	// the ID of the client that initialized the login flow. It may occasionally differ if
        	// the provider supports the authorizing party (azp) claim.
        	//
        	// If not provided, users must explicitly set SkipClientIDCheck.
        	ClientID string
        	// If specified, only this set of algorithms may be used to sign the JWT.
        	//
        	// If the IDTokenVerifier is created from a provider with (*Provider).Verifier, this
        	// defaults to the set of algorithms the provider supports. Otherwise this values
        	// defaults to RS256.
        	SupportedSigningAlgs []string
        
        	// If true, no ClientID check performed. Must be true if ClientID field is empty.
        	SkipClientIDCheck bool
        	// If true, token expiry is not checked.
        	SkipExpiryCheck bool
        
        	// SkipIssuerCheck is intended for specialized cases where the the caller wishes to
        	// defer issuer validation. When enabled, callers MUST independently verify the Token's
        	// Issuer is a known good value.
        	//
        	// Mismatched issuers often indicate client mis-configuration. If mismatches are
        	// unexpected, evaluate if the provided issuer URL is incorrect instead of enabling
        	// this option.
        	SkipIssuerCheck bool
        
        	// Time function to check Token expiry. Defaults to time.Now
        	Now func() time.Time
        }

          Config is the configuration for an IDTokenVerifier.

          type IDToken

          type IDToken struct {
          	// The URL of the server which issued this token. OpenID Connect
          	// requires this value always be identical to the URL used for
          	// initial discovery.
          	//
          	// Note: Because of a known issue with Google Accounts' implementation
          	// this value may differ when using Google.
          	//
          	// See: https://developers.google.com/identity/protocols/OpenIDConnect#obtainuserinfo
          	Issuer string
          
          	// The client ID, or set of client IDs, that this token is issued for. For
          	// common uses, this is the client that initialized the auth flow.
          	//
          	// This package ensures the audience contains an expected value.
          	Audience []string
          
          	// A unique string which identifies the end user.
          	Subject string
          
          	// Expiry of the token. Ths package will not process tokens that have
          	// expired unless that validation is explicitly turned off.
          	Expiry time.Time
          	// When the token was issued by the provider.
          	IssuedAt time.Time
          
          	// Initial nonce provided during the authentication redirect.
          	//
          	// This package does NOT provided verification on the value of this field
          	// and it's the user's responsibility to ensure it contains a valid value.
          	Nonce string
          
          	// at_hash claim, if set in the ID token. Callers can verify an access token
          	// that corresponds to the ID token using the VerifyAccessToken method.
          	AccessTokenHash string
          	// contains filtered or unexported fields
          }

            IDToken is an OpenID Connect extension that provides a predictable representation of an authorization event.

            The ID Token only holds fields OpenID Connect requires. To access additional claims returned by the server, use the Claims method.

            func (*IDToken) Claims

            func (i *IDToken) Claims(v interface{}) error

              Claims unmarshals the raw JSON payload of the ID Token into a provided struct.

              idToken, err := idTokenVerifier.Verify(rawIDToken)
              if err != nil {
              	// handle error
              }
              var claims struct {
              	Email         string `json:"email"`
              	EmailVerified bool   `json:"email_verified"`
              }
              if err := idToken.Claims(&claims); err != nil {
              	// handle error
              }
              

              func (*IDToken) VerifyAccessToken

              func (i *IDToken) VerifyAccessToken(accessToken string) error

                VerifyAccessToken verifies that the hash of the access token that corresponds to the iD token matches the hash in the id token. It returns an error if the hashes don't match. It is the caller's responsibility to ensure that the optional access token hash is present for the ID token before calling this method. See https://openid.net/specs/openid-connect-core-1_0.html#CodeIDToken

                type IDTokenVerifier

                type IDTokenVerifier struct {
                	// contains filtered or unexported fields
                }

                  IDTokenVerifier provides verification for ID Tokens.

                  func NewVerifier

                  func NewVerifier(issuerURL string, keySet KeySet, config *Config) *IDTokenVerifier

                    NewVerifier returns a verifier manually constructed from a key set and issuer URL.

                    It's easier to use provider discovery to construct an IDTokenVerifier than creating one directly. This method is intended to be used with provider that don't support metadata discovery, or avoiding round trips when the key set URL is already known.

                    This constructor can be used to create a verifier directly using the issuer URL and JSON Web Key Set URL without using discovery:

                    keySet := oidc.NewRemoteKeySet(ctx, "https://www.googleapis.com/oauth2/v3/certs")
                    verifier := oidc.NewVerifier("https://accounts.google.com", keySet, config)
                    

                    Since KeySet is an interface, this constructor can also be used to supply custom public key sources. For example, if a user wanted to supply public keys out-of-band and hold them statically in-memory:

                    // Custom KeySet implementation.
                    keySet := newStatisKeySet(publicKeys...)
                    
                    // Verifier uses the custom KeySet implementation.
                    verifier := oidc.NewVerifier("https://auth.example.com", keySet, config)
                    

                    func (*IDTokenVerifier) Verify

                    func (v *IDTokenVerifier) Verify(ctx context.Context, rawIDToken string) (*IDToken, error)

                      Verify parses a raw ID Token, verifies it's been signed by the provider, preforms any additional checks depending on the Config, and returns the payload.

                      Verify does NOT do nonce validation, which is the callers responsibility.

                      See: https://openid.net/specs/openid-connect-core-1_0.html#IDTokenValidation

                      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 error
                      }
                      
                      token, err := verifier.Verify(ctx, rawIDToken)
                      

                      type KeySet

                      type KeySet interface {
                      	// VerifySignature parses the JSON web token, verifies the signature, and returns
                      	// the raw payload. Header and claim fields are validated by other parts of the
                      	// package. For example, the KeySet does not need to check values such as signature
                      	// algorithm, issuer, and audience since the IDTokenVerifier validates these values
                      	// independently.
                      	//
                      	// If VerifySignature makes HTTP requests to verify the token, it's expected to
                      	// use any HTTP client associated with the context through ClientContext.
                      	VerifySignature(ctx context.Context, jwt string) (payload []byte, err error)
                      }

                        KeySet is a set of publc JSON Web Keys that can be used to validate the signature of JSON web tokens. This is expected to be backed by a remote key set through provider metadata discovery or an in-memory set of keys delivered out-of-band.

                        func NewRemoteKeySet

                        func NewRemoteKeySet(ctx context.Context, jwksURL string) KeySet

                          NewRemoteKeySet returns a KeySet that can validate JSON web tokens by using HTTP GETs to fetch JSON web token sets hosted at a remote URL. This is automatically used by NewProvider using the URLs returned by OpenID Connect discovery, but is exposed for providers that don't support discovery or to prevent round trips to the discovery URL.

                          The returned KeySet is a long lived verifier that caches keys based on cache-control headers. Reuse a common remote key set instead of creating new ones as needed.

                          The behavior of the returned KeySet is undefined once the context is canceled.

                          type Provider

                          type Provider struct {
                          	// contains filtered or unexported fields
                          }

                            Provider represents an OpenID Connect server's configuration.

                            func NewProvider

                            func NewProvider(ctx context.Context, issuer string) (*Provider, error)

                              NewProvider uses the OpenID Connect discovery mechanism to construct a Provider.

                              The issuer is the URL identifier for the service. For example: "https://accounts.google.com" or "https://login.salesforce.com".

                              func (*Provider) Claims

                              func (p *Provider) Claims(v interface{}) error

                                Claims unmarshals raw fields returned by the server during discovery.

                                var claims struct {
                                    ScopesSupported []string `json:"scopes_supported"`
                                    ClaimsSupported []string `json:"claims_supported"`
                                }
                                
                                if err := provider.Claims(&claims); err != nil {
                                    // handle unmarshaling error
                                }
                                

                                For a list of fields defined by the OpenID Connect spec see: https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata

                                func (*Provider) Endpoint

                                func (p *Provider) Endpoint() oauth2.Endpoint

                                  Endpoint returns the OAuth2 auth and token endpoints for the given provider.

                                  func (*Provider) UserInfo

                                  func (p *Provider) UserInfo(ctx context.Context, tokenSource oauth2.TokenSource) (*UserInfo, error)

                                    UserInfo uses the token source to query the provider's user info endpoint.

                                    func (*Provider) Verifier

                                    func (p *Provider) Verifier(config *Config) *IDTokenVerifier

                                      Verifier returns an IDTokenVerifier that uses the provider's key set to verify JWTs.

                                      The returned IDTokenVerifier is tied to the Provider's context and its behavior is undefined once the Provider's context is canceled.

                                      type UserInfo

                                      type UserInfo struct {
                                      	Subject       string `json:"sub"`
                                      	Profile       string `json:"profile"`
                                      	Email         string `json:"email"`
                                      	EmailVerified bool   `json:"email_verified"`
                                      	// contains filtered or unexported fields
                                      }

                                        UserInfo represents the OpenID Connect userinfo claims.

                                        func (*UserInfo) Claims

                                        func (u *UserInfo) Claims(v interface{}) error

                                          Claims unmarshals the raw JSON object claims into the provided object.

                                          Directories

                                          Path Synopsis
                                          example
                                          idtoken
                                          This is an example application to demonstrate parsing an ID Token.
                                          This is an example application to demonstrate parsing an ID Token.
                                          nonce
                                          This is an example application to demonstrate verifying an ID Token with a nonce.
                                          This is an example application to demonstrate verifying an ID Token with a nonce.
                                          userinfo
                                          This is an example application to demonstrate querying the user info endpoint.
                                          This is an example application to demonstrate querying the user info endpoint.