openid

Documentation

Overview

Package openid implements OpenID Connect Login protocol (client side).

Tested only with Google's implementation of the protocol.

See https://developers.google.com/identity/protocols/OpenIDConnect.

Index

• Constants
• Variables
• func AudienceMatchesHost(ctx context.Context, r *http.Request, aud string) (valid bool, err error)
• type CookieAuthMethod
  • func (m *CookieAuthMethod) Authenticate(c context.Context, r *http.Request) (*auth.User, error)
  • func (m *CookieAuthMethod) InstallHandlers(r *router.Router, base router.MiddlewareChain)
  • func (m *CookieAuthMethod) LoginURL(c context.Context, dest string) (string, error)
  • func (m *CookieAuthMethod) LogoutURL(c context.Context, dest string) (string, error)
  • func (m *CookieAuthMethod) Warmup(c context.Context) (err error)
• type GoogleIDTokenAuthMethod
  • func (m *GoogleIDTokenAuthMethod) Authenticate(ctx context.Context, r *http.Request) (*auth.User, error)
  • func (m *GoogleIDTokenAuthMethod) Warmup(ctx context.Context) error
• type IDToken
  • func VerifyIDToken(ctx context.Context, token string, keys *JSONWebKeySet, issuer string) (*IDToken, error)
• type JSONWebKeySet
  • func NewJSONWebKeySet(parsed *JSONWebKeySetStruct) (*JSONWebKeySet, error)
  • func (k *JSONWebKeySet) VerifyJWT(jwt string) (body []byte, err error)
• type JSONWebKeySetStruct
• type JSONWebKeyStruct
• type Settings

Constants

const SettingsKey = "openid_auth"

SettingsKey is key for OpenID settings (described by Settings struct) in settings store. See go.chromium.org/luci/server/settings.

Variables

var (
	// ErrNotConfigured is returned by various functions if OpenID settings are
	// not properly configured.
	ErrNotConfigured = errors.New("openid: not configured")
)

Functions

func AudienceMatchesHost

func AudienceMatchesHost(ctx context.Context, r *http.Request, aud string) (valid bool, err error)

AudienceMatchesHost can be used as a AudienceCheck callback.

It verifies token's audience matches "Host" request header. Suitable for environments where "Host" header can be trusted.

Types

type CookieAuthMethod

type CookieAuthMethod struct {
	// SessionStore keeps user sessions in some permanent storage. Must be set,
	// otherwise all methods return ErrNotConfigured.
	SessionStore auth.SessionStore

	// Insecure is true to allow http:// URLs and non-https cookies. Useful for
	// local development.
	Insecure bool

	// IncompatibleCookies is a list of cookies to remove when setting or clearing
	// session cookie. It is useful to get rid of GAE cookies when OpenID cookies
	// are being used. Having both is very confusing.
	IncompatibleCookies []string
}

CookieAuthMethod implements auth.Method and auth.UsersAPI and can be used as one of authentication method in auth.Authenticator. It is using OpenID for login flow, stores session ID in cookies, and session itself in supplied SessionStore.

It requires some routes to be added to the router. Use exact same instance of CookieAuthMethod in auth.Authenticator and when adding routes via InstallHandlers.

DEPRECATED. Do not use.

func (*CookieAuthMethod) Authenticate

func (m *CookieAuthMethod) Authenticate(c context.Context, r *http.Request) (*auth.User, error)

Authenticate extracts peer's identity from the incoming request. It is part of auth.Method interface.

func (*CookieAuthMethod) InstallHandlers

func (m *CookieAuthMethod) InstallHandlers(r *router.Router, base router.MiddlewareChain)

InstallHandlers installs HTTP handlers used in OpenID protocol. Must be installed in server HTTP router for OpenID authentication flow to work.

Implements auth.HasHandlers.

func (*CookieAuthMethod) LoginURL

func (m *CookieAuthMethod) LoginURL(c context.Context, dest string) (string, error)

LoginURL returns a URL that, when visited, prompts the user to sign in, then redirects the user to the URL specified by dest. It is part of auth.UsersAPI interface.

func (*CookieAuthMethod) LogoutURL

func (m *CookieAuthMethod) LogoutURL(c context.Context, dest string) (string, error)

LogoutURL returns a URL that, when visited, signs the user out, then redirects the user to the URL specified by dest. It is part of auth.UsersAPI interface.

func (*CookieAuthMethod) Warmup

func (m *CookieAuthMethod) Warmup(c context.Context) (err error)

Warmup prepares local caches. It's optional.

Implements auth.Warmable.

type GoogleIDTokenAuthMethod

type GoogleIDTokenAuthMethod struct {
	// Audience is a list of allowed audiences for tokens that identify Google
	// service accounts ("*.gserviceaccount.com" emails).
	Audience []string

	// AudienceCheck is an optional callback to use to check tokens audience in
	// case enumerating all expected audiences is not viable.
	//
	// Works in conjunction with Audience. Also, just like Audience, this check is
	// used only for tokens that identify service accounts.
	AudienceCheck func(ctx context.Context, r *http.Request, aud string) (valid bool, err error)
	// contains filtered or unexported fields
}

GoogleIDTokenAuthMethod implements auth.Method by checking `Authorization` header which is expected to have an OpenID Connect ID token signed by Google.

The header value should have form "Bearer <base64 JWT>".

There are two variants of tokens signed by Google:

• ID tokens identifying end users. They always have an OAuth2 Client ID as an audience (`aud` field). Their `aud` is placed into User.ClientID, so it is later checked against a whitelist of client IDs by the LUCI auth stack.
• ID tokens identifying service accounts. They generally can have anything at all as an audience, but usually have an URL of the service being called. Their `aud` is checked against Audience list below.

func (*GoogleIDTokenAuthMethod) Authenticate

func (m *GoogleIDTokenAuthMethod) Authenticate(ctx context.Context, r *http.Request) (*auth.User, error)

Authenticate extracts user information from the incoming request.

It returns:

• (*User, nil) on success.
• (nil, nil) if the method is not applicable.
• (nil, error) if the method is applicable, but credentials are invalid.

func (*GoogleIDTokenAuthMethod) Warmup

func (m *GoogleIDTokenAuthMethod) Warmup(ctx context.Context) error

Warmup prepares local caches. It's optional.

Implements auth.Warmable.

type IDToken

type IDToken struct {
	Iss           string `json:"iss"`
	AtHash        string `json:"at_hash"`
	EmailVerified bool   `json:"email_verified"`
	Sub           string `json:"sub"`
	Azp           string `json:"azp"`
	Email         string `json:"email"`
	Profile       string `json:"profile"`
	Picture       string `json:"picture"`
	Name          string `json:"name"`
	Aud           string `json:"aud"`
	Iat           int64  `json:"iat"`
	Exp           int64  `json:"exp"`
	Nonce         string `json:"nonce"`
	Hd            string `json:"hd"`
}

IDToken is verified deserialized ID token.

See https://developers.google.com/identity/protocols/OpenIDConnect.

func VerifyIDToken

func VerifyIDToken(ctx context.Context, token string, keys *JSONWebKeySet, issuer string) (*IDToken, error)

VerifyIDToken deserializes and verifies the ID token.

It checks the signature, expiration time and verifies fields `iss` and `email_verified`.

It checks `aud` and `sub` are present, but does NOT verify them any further. It is the caller's responsibility to do so.

This is a fast local operation.

type JSONWebKeySet

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

JSONWebKeySet implements subset of functionality described in RFC7517.

It currently supports only RSA keys and RS256 alg. It's intended to be used to represent keys fetched from https://www.googleapis.com/oauth2/v3/certs.

It's used to verify ID token signatures.

func NewJSONWebKeySet

func NewJSONWebKeySet(parsed *JSONWebKeySetStruct) (*JSONWebKeySet, error)

NewJSONWebKeySet makes the keyset from raw JSON Web Key set struct.

func (*JSONWebKeySet) VerifyJWT

func (k *JSONWebKeySet) VerifyJWT(jwt string) (body []byte, err error)

VerifyJWT checks JWT signature and returns the token body.

Supports only non-encrypted RS256-signed JWTs. See RFC7519.

type JSONWebKeySetStruct

type JSONWebKeySetStruct struct {
	Keys []JSONWebKeyStruct `json:"keys"`
}

JSONWebKeySetStruct defines the JSON structure of JSONWebKeySet.

Read it from the wire and pass to NewJSONWebKeySet to get a usable object.

See https://www.iana.org/assignments/jose/jose.xhtml#web-key-parameters. We care only about RSA public keys (thus use 'n' and 'e').

type JSONWebKeyStruct

type JSONWebKeyStruct struct {
	Kty string `json:"kty"`
	Alg string `json:"alg"`
	Use string `json:"use"`
	Kid string `json:"kid"`
	N   string `json:"n"` // raw URL-safe base64, NOT standard base64
	E   string `json:"e"` // same
}

JSONWebKeyStruct defines the JSON structure of a single key in the key set.

type Settings

type Settings struct {
	// DiscoveryURL is where to grab discovery document with provider's config.
	// Use `https://accounts.google.com/.well-known/openid-configuration` for
	// Google OpenID Connect provider.
	DiscoveryURL string `json:"discovery_url"`

	// ClientID identifies OAuth2 Web client representing the application. Create
	// one in Cloud Console if using Google OpenID Connect provider.
	ClientID string `json:"client_id"`

	// ClientSecret is a secret associated with ClientID.
	ClientSecret string `json:"client_secret"`

	// RedirectURI must be `https://<apphost>/auth/openid/callback`. It is stored
	// in config explicitly to remind admin that OAuth2 client in Cloud Console
	// must be configured accordingly.
	RedirectURI string `json:"redirect_uri"`
}

Settings contain parameters of OpenID protocol. They are stored in app settings store under SettingsKey key.