oidc

README

Oh, I don't care

OIDC stands for Open ID Connect, but honestly I just don't give a shit about its internals. What's the use of a well-known address if it's not used most of the time?! Introducing: Oh, I don't care. Taking the pain out of OIDC.

How it works

It's really difficult:

// create a config
cfg := oidc.Configure("https://sso.provi.de/application/o/my-cool-app/.well-known/openid-configuration")
cfg.SetCredentials(clientID, clientSecret)
cfg.SetScopes("openid", "email") // optional: set scopes

Then you redirect the user to the application:

func (a *Authenticator) signIn(w http.ResponseWriter, r *http.Request) {
	url := a.cfg.GetAuthorizationURL()
	http.Redirect(w, r, url, http.StatusTemporaryRedirect)
}

And wait for the callback:

func (a *Authenticator) callback(w http.ResponseWriter, r *http.Request) {
	tok, err := a.cfg.Callback(r.FormValue("code"), r.FormValue("state"))
	if err != nil {
		http.Error(w, err.Error(), http.StatusUnauthorized)
		return
	}

	// set a cookie, initialize a session, do stuff
}

Licence

This project is licensed under the MPL-2.0 licence. See the licence header in each file.

Documentation

Overview

Package oidc is a simple OpenID Connect client library for Go. Its goal is to make OIDC based authentication as easy as it should be. Give it the application URL, provide credentials, done.

Why should this exist? Honestly, it shouldn't. I don't know if I missed the other 200 libraries out there that already solve this issue, or if I am really the first person to think of it.

There are also examples available, even if pkg.go.dev decides not to show them. Just check the sourcecode for simple examples on how to use the various functions.

Index

• Constants
• Variables
• type Configuration
  • func Configure(address string, callbackURL string, opts ...option) (*Configuration, error)
  • func (cfg *Configuration) Callback(code, state string) (*Token, error)
  • func (cfg *Configuration) GetAuthorizationURL() string
  • func (cfg *Configuration) LogoutURL() string
  • func (cfg *Configuration) ParseJWT(token string) (*Token, error)
  • func (cfg *Configuration) SetCredentials(clientID, clientSecret string)
  • func (cfg *Configuration) SetScopes(scopes ...string) error
  • func (cfg *Configuration) UseAppPassword(username, password string) (*Token, error)
• type Token
  • func (t *Token) Address() *openid.AddressClaim
  • func (t *Token) Audience() []string
  • func (t *Token) Birthdate() time.Time
  • func (t *Token) Email() string
  • func (t *Token) EmailVerified() bool
  • func (t *Token) Expiration() time.Time
  • func (t *Token) FamilyName() string
  • func (t *Token) Gender() string
  • func (t *Token) GetField(field string) (any, bool)
  • func (t *Token) GivenName() string
  • func (t *Token) Locale() string
  • func (t *Token) LogoutURL() string
  • func (t *Token) MiddleName() string
  • func (t *Token) Name() string
  • func (t *Token) Nickname() string
  • func (t *Token) PhoneNumber() string
  • func (t *Token) PhoneNumberVerified() bool
  • func (t *Token) Picture() string
  • func (t *Token) PreferredUsername() string
  • func (t *Token) Profile() string
  • func (t *Token) String() string
  • func (t *Token) Subject() string
  • func (t *Token) Token() (*oauth2.Token, error)
  • func (t *Token) UpdateClaims() error
  • func (t *Token) UpdatedAt() time.Time
  • func (t *Token) Valid() bool
  • func (t *Token) Website() string
  • func (t *Token) Zoneinfo() string

Constants

const (
	// OptionSkipScopeValidation disables the scope validation. This is
	// intended to only be used if a known non-standard compliant service
	// *has* to be used.
	OptionSkipScopeValidation option = 1 << iota
	// OptionDisableCSRFProtection disables CSRF protection.
	OptionDisableCSRFProtection
	// OptionForceApprovalPrompt forces the user to approve the login.
	OptionForceApprovalPrompt
	// OptionRequestOfflineToken sends a request for an offline token. This
	// is only useful if the token is used without user-interaction to
	// authenticate with another system.
	OptionRequestOfflineToken
	// OptionSkipTokenValidation skips the validation of the returned JWT.
	OptionSkipTokenValidation
)

const (
	TokenClaimAddressFormattedKey     = openid.AddressFormattedKey
	TokenClaimAddressStreetAddressKey = openid.AddressStreetAddressKey
	TokenClaimAddressLocalityKey      = openid.AddressLocalityKey
	TokenClaimAddressRegionKey        = openid.AddressRegionKey
	TokenClaimAddressPostalCodeKey    = openid.AddressPostalCodeKey
	TokenClaimAddressCountryKey       = openid.AddressCountryKey
	TokenClaimAddressKey              = openid.AddressKey
	TokenClaimBirthdateKey            = openid.BirthdateKey
	TokenClaimEmailKey                = openid.EmailKey
	TokenClaimEmailVerifiedKey        = openid.EmailVerifiedKey
	TokenClaimFamilyNameKey           = openid.FamilyNameKey
	TokenClaimGenderKey               = openid.GenderKey
	TokenClaimGivenNameKey            = openid.GivenNameKey
	TokenClaimLocaleKey               = openid.LocaleKey
	TokenClaimMiddleNameKey           = openid.MiddleNameKey
	TokenClaimNameKey                 = openid.NameKey
	TokenClaimNicknameKey             = openid.NicknameKey
	TokenClaimPhoneNumberKey          = openid.PhoneNumberKey
	TokenClaimPhoneNumberVerifiedKey  = openid.PhoneNumberVerifiedKey
	TokenClaimPictureKey              = openid.PictureKey
	TokenClaimPreferredUsernameKey    = openid.PreferredUsernameKey
	TokenClaimProfileKey              = openid.ProfileKey
	TokenClaimUpdatedAtKey            = openid.UpdatedAtKey
	TokenClaimWebsiteKey              = openid.WebsiteKey
	TokenClaimZoneinfoKey             = openid.ZoneinfoKey
)

Variables

var (
	// ErrScopeUnsupported is returned if the service does not advertise
	// support for a particular scope.
	ErrScopeUnsupported = errors.New("scope not supported")
	// ErrCSRFValidationFailed is returned if the validation of the CSRF
	// token failed.
	ErrCSRFValidationFailed = errors.New("CSRF validation failed")
)

Types

type Configuration

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

Configuration wraps an OIDC service

func Configure

func Configure(address string, callbackURL string, opts ...option) (*Configuration, error)

Configure parses the well-known config and returns a Configuration based on it. The .well-known/openid-configuration is automatically appended. In case of a non-standard endpoint, the direct response is also parsed. callbackURL is where the callback-handler is wired up to.

func (*Configuration) Callback

func (cfg *Configuration) Callback(code, state string) (*Token, error)

Callback completes the authentication of a user and returns a token for the user.

func (*Configuration) GetAuthorizationURL

func (cfg *Configuration) GetAuthorizationURL() string

GetAuthorizationURL returns the authorization URL. Redirect your user to the returned URL and be happy.

func (*Configuration) LogoutURL

func (cfg *Configuration) LogoutURL() string

LogoutURL returns the generic logout URL

func (*Configuration) ParseJWT

func (cfg *Configuration) ParseJWT(token string) (*Token, error)

ParseJWT parses and validates a provided token for example from an Authorization header.

func (*Configuration) SetCredentials

func (cfg *Configuration) SetCredentials(clientID, clientSecret string)

SetCredentials sets the clientID and clientSecret for the service.

func (*Configuration) SetScopes

func (cfg *Configuration) SetScopes(scopes ...string) error

SetScopes sets the scopes for the service. They are checked against the scopes advertised by the service, and ErrScopeUnsupported is returned if the service does not advertise support for this scope.

func (*Configuration) UseAppPassword

func (cfg *Configuration) UseAppPassword(username, password string) (*Token, error)

UseAppPassword returns a token using the app password flow. This is less secure and should be generally avoided.

type Token

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

Token returns an OIDC token returned by the service

func (*Token) Address

func (t *Token) Address() *openid.AddressClaim

func (*Token) Audience

func (t *Token) Audience() []string

func (*Token) Birthdate

func (t *Token) Birthdate() time.Time

func (*Token) Email

func (t *Token) Email() string

func (*Token) EmailVerified

func (t *Token) EmailVerified() bool

func (*Token) Expiration

func (t *Token) Expiration() time.Time

func (*Token) FamilyName

func (t *Token) FamilyName() string

func (*Token) Gender

func (t *Token) Gender() string

func (*Token) GetField

func (t *Token) GetField(field string) (any, bool)

GetField returns the specified field and whether or not it is set.

func (*Token) GivenName

func (t *Token) GivenName() string

func (*Token) Locale

func (t *Token) Locale() string

func (*Token) LogoutURL

func (t *Token) LogoutURL() string

LogoutURL returns the logout URL to invalidate the token

func (*Token) MiddleName

func (t *Token) MiddleName() string

func (*Token) Name

func (t *Token) Name() string

func (*Token) Nickname

func (t *Token) Nickname() string

func (*Token) PhoneNumber

func (t *Token) PhoneNumber() string

func (*Token) PhoneNumberVerified

func (t *Token) PhoneNumberVerified() bool

func (*Token) Picture

func (t *Token) Picture() string

func (*Token) PreferredUsername

func (t *Token) PreferredUsername() string

func (*Token) Profile

func (t *Token) Profile() string

func (*Token) String

func (t *Token) String() string

String returns the initially received ID Token

func (*Token) Subject

func (t *Token) Subject() string

func (*Token) Token

func (t *Token) Token() (*oauth2.Token, error)

Token returns the current OAuth2 token associated with the OIDC token. You probably don't want this.

func (*Token) UpdateClaims

func (t *Token) UpdateClaims() error

UpdateClaims forces an update of the information in a token. By default, the results are cached and if a user was to change any field in the identity provider, they have to login again for the token to reflect that.

func (*Token) UpdatedAt

func (t *Token) UpdatedAt() time.Time

func (*Token) Valid

func (t *Token) Valid() bool

Valid returns true if the token is still valid

func (*Token) Website

func (t *Token) Website() string

func (*Token) Zoneinfo

func (t *Token) Zoneinfo() string