oidc

Documentation

Index

• Constants
• func ClientContext(ctx context.Context, client *http.Client) context.Context
• func Nonce(nonce string) oauth2.AuthCodeOption
• type AccessToken
  • func (s *AccessToken) ToClaims() []*contracts_claimsprincipal.Claim
• type CustomClaims
• type JWTAccessTokenVerifier
  • func NewJWTAccessTokenVerifier(issuerURL string, keySet go_oidc.KeySet, config *go_oidc.Config) *JWTAccessTokenVerifier
  • func (v *JWTAccessTokenVerifier) Verify(ctx context.Context, rawToken string) (*AccessToken, error)
• type Provider
  • func NewProvider(ctx context.Context, issuer string) (*Provider, error)
  • func (p *Provider) Claims(v interface{}) error
  • func (p *Provider) Endpoint() oauth2.Endpoint
  • func (p *Provider) GetRemoteKeySet() go_oidc.KeySet
  • func (p *Provider) UserInfo(ctx context.Context, tokenSource oauth2.TokenSource) (*UserInfo, error)
  • func (p *Provider) Verifier(config *go_oidc.Config) *JWTAccessTokenVerifier
• type UserInfo
  • func (u *UserInfo) Claims(v interface{}) error

Constants

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"
)

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 AccessToken

type AccessToken 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

	// Claims, all of them.
	Claims map[string]interface{}
}

AccessToken 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 (*AccessToken) ToClaims

func (s *AccessToken) ToClaims() []*contracts_claimsprincipal.Claim

ToClaims converts the AccessToken to a Claims object.

type CustomClaims

type CustomClaims struct {
	*jose_jwt.Claims
	AnyJSONObjectClaim map[string]interface{} `json:"anyJSONObjectClaim"`
}

Verify parses a raw ID Token, verifies it's been signed by the provider, performs 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 JWTAccessTokenVerifier

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

JWTAccessTokenVerifier provides verification for ID Tokens.

func NewJWTAccessTokenVerifier

func NewJWTAccessTokenVerifier(issuerURL string, keySet go_oidc.KeySet, config *go_oidc.Config) *JWTAccessTokenVerifier

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

It's easier to use provider discovery to construct an JWTAccessTokenVerifier 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 (*JWTAccessTokenVerifier) Verify

func (v *JWTAccessTokenVerifier) Verify(ctx context.Context, rawToken string) (*AccessToken, error)

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) GetRemoteKeySet

func (p *Provider) GetRemoteKeySet() go_oidc.KeySet

GetRemoteKeySet retrieves the keys used by the 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 *go_oidc.Config) *JWTAccessTokenVerifier

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

The returned JWTAccessTokenVerifier 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.