feat: token introspection (#83)

* introspect

* introspect and client assertion

* introspect and client assertion

* scopes

* token introspection

* introspect

* refactoring

* fixes

* clenaup

* Update example/internal/mock/storage.go

Co-authored-by: Fabi <38692350+fgerschwiler@users.noreply.github.com>

* clenaup

Co-authored-by: Fabi <38692350+fgerschwiler@users.noreply.github.com>

pkg/client/rp/cli/cli.go

@@ -0,0 +1,35 @@
+package cli
+
+import (
+	"context"
+	"net/http"
+
+	"github.com/caos/oidc/pkg/client/rp"
+	"github.com/caos/oidc/pkg/oidc"
+	"github.com/caos/oidc/pkg/utils"
+)
+
+const (
+	loginPath = "/login"
+)
+
+func CodeFlow(relyingParty rp.RelyingParty, callbackPath, port string, stateProvider func() string) *oidc.Tokens {
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	var token *oidc.Tokens
+	callback := func(w http.ResponseWriter, r *http.Request, tokens *oidc.Tokens, state string) {
+		token = tokens
+		msg := "<p><strong>Success!</strong></p>"
+		msg = msg + "<p>You are authenticated and can now return to the CLI.</p>"
+		w.Write([]byte(msg))
+	}
+	http.Handle(loginPath, rp.AuthURLHandler(stateProvider, relyingParty))
+	http.Handle(callbackPath, rp.CodeExchangeHandler(callback, relyingParty))
+
+	utils.StartServer(ctx, port)
+
+	utils.OpenBrowser("http://localhost:" + port + loginPath)
+
+	return token
+}

pkg/client/rp/delegation.go

@@ -0,0 +1,13 @@
+package rp
+
+import (
+	"github.com/caos/oidc/pkg/oidc/grants/tokenexchange"
+)
+
+//DelegationTokenRequest is an implementation of TokenExchangeRequest
+//it exchanges a "urn:ietf:params:oauth:token-type:access_token" with an optional
+//"urn:ietf:params:oauth:token-type:access_token" actor token for a
+//"urn:ietf:params:oauth:token-type:access_token" delegation token
+func DelegationTokenRequest(subjectToken string, opts ...tokenexchange.TokenExchangeOption) *tokenexchange.TokenExchangeRequest {
+	return tokenexchange.NewTokenExchangeRequest(subjectToken, tokenexchange.AccessTokenType, opts...)
+}

pkg/client/rp/jwks.go

@@ -0,0 +1,156 @@
+package rp
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"net/http"
+	"sync"
+
+	"github.com/caos/oidc/pkg/utils"
+
+	"gopkg.in/square/go-jose.v2"
+
+	"github.com/caos/oidc/pkg/oidc"
+)
+
+func NewRemoteKeySet(client *http.Client, jwksURL string) oidc.KeySet {
+	return &remoteKeySet{httpClient: client, jwksURL: jwksURL}
+}
+
+type remoteKeySet struct {
+	jwksURL    string
+	httpClient *http.Client
+
+	// guard all other fields
+	mu sync.Mutex
+
+	// inflight suppresses parallel execution of updateKeys and allows
+	// multiple goroutines to wait for its result.
+	inflight *inflight
+
+	// A set of cached keys and their expiry.
+	cachedKeys []jose.JSONWebKey
+}
+
+// inflight is used to wait on some in-flight request from multiple goroutines.
+type inflight struct {
+	doneCh chan struct{}
+
+	keys []jose.JSONWebKey
+	err  error
+}
+
+func newInflight() *inflight {
+	return &inflight{doneCh: make(chan struct{})}
+}
+
+// wait returns a channel that multiple goroutines can receive on. Once it returns
+// a value, the inflight request is done and result() can be inspected.
+func (i *inflight) wait() <-chan struct{} {
+	return i.doneCh
+}
+
+// done can only be called by a single goroutine. It records the result of the
+// inflight request and signals other goroutines that the result is safe to
+// inspect.
+func (i *inflight) done(keys []jose.JSONWebKey, err error) {
+	i.keys = keys
+	i.err = err
+	close(i.doneCh)
+}
+
+// result cannot be called until the wait() channel has returned a value.
+func (i *inflight) result() ([]jose.JSONWebKey, error) {
+	return i.keys, i.err
+}
+
+func (r *remoteKeySet) VerifySignature(ctx context.Context, jws *jose.JSONWebSignature) ([]byte, error) {
+	// We don't support JWTs signed with multiple signatures.
+	keyID := ""
+	for _, sig := range jws.Signatures {
+		keyID = sig.Header.KeyID
+		break
+	}
+
+	keys := r.keysFromCache()
+	payload, err, ok := oidc.CheckKey(keyID, jws, keys...)
+	if ok {
+		return payload, err
+	}
+
+	keys, err = r.keysFromRemote(ctx)
+	if err != nil {
+		return nil, fmt.Errorf("fetching keys %v", err)
+	}
+
+	payload, err, ok = oidc.CheckKey(keyID, jws, keys...)
+	if !ok {
+		return nil, errors.New("invalid kid")
+	}
+	return payload, err
+}
+
+func (r *remoteKeySet) keysFromCache() (keys []jose.JSONWebKey) {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	return r.cachedKeys
+}
+
+// keysFromRemote syncs the key set from the remote set, records the values in the
+// cache, and returns the key set.
+func (r *remoteKeySet) keysFromRemote(ctx context.Context) ([]jose.JSONWebKey, error) {
+	// Need to lock to inspect the inflight request field.
+	r.mu.Lock()
+	// If there's not a current inflight request, create one.
+	if r.inflight == nil {
+		r.inflight = newInflight()
+
+		// This goroutine has exclusive ownership over the current inflight
+		// request. It releases the resource by nil'ing the inflight field
+		// once the goroutine is done.
+		go r.updateKeys(ctx)
+	}
+	inflight := r.inflight
+	r.mu.Unlock()
+
+	select {
+	case <-ctx.Done():
+		return nil, ctx.Err()
+	case <-inflight.wait():
+		return inflight.result()
+	}
+}
+
+func (r *remoteKeySet) updateKeys(ctx context.Context) {
+	// Sync keys and finish inflight when that's done.
+	keys, err := r.fetchRemoteKeys(ctx)
+
+	r.inflight.done(keys, err)
+
+	// Lock to update the keys and indicate that there is no longer an
+	// inflight request.
+	r.mu.Lock()
+	defer r.mu.Unlock()
+
+	if err == nil {
+		r.cachedKeys = keys
+	}
+
+	// Free inflight so a different request can run.
+	r.inflight = nil
+}
+
+func (r *remoteKeySet) fetchRemoteKeys(ctx context.Context) ([]jose.JSONWebKey, error) {
+	req, err := http.NewRequest("GET", r.jwksURL, nil)
+	if err != nil {
+		return nil, fmt.Errorf("oidc: can't create request: %v", err)
+	}
+
+	keySet := new(jose.JSONWebKeySet)
+	if err = utils.HttpRequest(r.httpClient, req, keySet); err != nil {
+		return nil, fmt.Errorf("oidc: failed to get keys: %v", err)
+	}
+
+	return keySet.Keys, nil
+}

pkg/client/rp/mock/generate.go

@@ -0,0 +1,3 @@
+package mock
+
+//go:generate mockgen -package mock -destination ./verifier.mock.go github.com/caos/oidc/pkg/rp Verifier

pkg/client/rp/mock/verifier.mock.go

@@ -0,0 +1,67 @@
+// Code generated by MockGen. DO NOT EDIT.
+// Source: github.com/caos/oidc/pkg/rp (interfaces: Verifier)
+
+// Package mock is a generated GoMock package.
+package mock
+
+import (
+	"context"
+	"reflect"
+
+	"github.com/golang/mock/gomock"
+
+	"github.com/caos/oidc/pkg/oidc"
+)
+
+// MockVerifier is a mock of Verifier interface
+type MockVerifier struct {
+	ctrl     *gomock.Controller
+	recorder *MockVerifierMockRecorder
+}
+
+// MockVerifierMockRecorder is the mock recorder for MockVerifier
+type MockVerifierMockRecorder struct {
+	mock *MockVerifier
+}
+
+// NewMockVerifier creates a new mock instance
+func NewMockVerifier(ctrl *gomock.Controller) *MockVerifier {
+	mock := &MockVerifier{ctrl: ctrl}
+	mock.recorder = &MockVerifierMockRecorder{mock}
+	return mock
+}
+
+// EXPECT returns an object that allows the caller to indicate expected use
+func (m *MockVerifier) EXPECT() *MockVerifierMockRecorder {
+	return m.recorder
+}
+
+// Verify mocks base method
+func (m *MockVerifier) Verify(arg0 context.Context, arg1, arg2 string) (*oidc.IDTokenClaims, error) {
+	m.ctrl.T.Helper()
+	ret := m.ctrl.Call(m, "Verify", arg0, arg1, arg2)
+	ret0, _ := ret[0].(*oidc.IDTokenClaims)
+	ret1, _ := ret[1].(error)
+	return ret0, ret1
+}
+
+// Verify indicates an expected call of Verify
+func (mr *MockVerifierMockRecorder) Verify(arg0, arg1, arg2 interface{}) *gomock.Call {
+	mr.mock.ctrl.T.Helper()
+	return mr.mock.ctrl.RecordCallWithMethodType(mr.mock, "Verify", reflect.TypeOf((*MockVerifier)(nil).Verify), arg0, arg1, arg2)
+}
+
+// VerifyIDToken mocks base method
+func (m *MockVerifier) VerifyIDToken(arg0 context.Context, arg1 string) (*oidc.IDTokenClaims, error) {
+	m.ctrl.T.Helper()
+	ret := m.ctrl.Call(m, "VerifyIDToken", arg0, arg1)
+	ret0, _ := ret[0].(*oidc.IDTokenClaims)
+	ret1, _ := ret[1].(error)
+	return ret0, ret1
+}
+
+// VerifyIDToken indicates an expected call of VerifyIDToken
+func (mr *MockVerifierMockRecorder) VerifyIDToken(arg0, arg1 interface{}) *gomock.Call {
+	mr.mock.ctrl.T.Helper()
+	return mr.mock.ctrl.RecordCallWithMethodType(mr.mock, "VerifyIDToken", reflect.TypeOf((*MockVerifier)(nil).VerifyIDToken), arg0, arg1)
+}

pkg/client/rp/relaying_party.go

@@ -0,0 +1,456 @@
+package rp
+
+import (
+	"context"
+	"errors"
+	"net/http"
+	"strings"
+	"time"
+
+	"github.com/google/uuid"
+	"golang.org/x/oauth2"
+	"gopkg.in/square/go-jose.v2"
+
+	"github.com/caos/oidc/pkg/client"
+	"github.com/caos/oidc/pkg/oidc"
+	"github.com/caos/oidc/pkg/utils"
+)
+
+const (
+	idTokenKey = "id_token"
+	stateParam = "state"
+	pkceCode   = "pkce"
+)
+
+//RelyingParty declares the minimal interface for oidc clients
+type RelyingParty interface {
+	//OAuthConfig returns the oauth2 Config
+	OAuthConfig() *oauth2.Config
+
+	//Issuer returns the issuer of the oidc config
+	Issuer() string
+
+	//IsPKCE returns if authorization is done using `Authorization Code Flow with Proof Key for Code Exchange (PKCE)`
+	IsPKCE() bool
+
+	//CookieHandler returns a http cookie handler used for various state transfer cookies
+	CookieHandler() *utils.CookieHandler
+
+	//HttpClient returns a http client used for calls to the openid provider, e.g. calling token endpoint
+	HttpClient() *http.Client
+
+	//IsOAuth2Only specifies whether relaying party handles only oauth2 or oidc calls
+	IsOAuth2Only() bool
+
+	//Signer is used if the relaying party uses the JWT Profile
+	Signer() jose.Signer
+
+	//UserinfoEndpoint returns the userinfo
+	UserinfoEndpoint() string
+
+	//IDTokenVerifier returns the verifier interface used for oidc id_token verification
+	IDTokenVerifier() IDTokenVerifier
+	//ErrorHandler returns the handler used for callback errors
+
+	ErrorHandler() func(http.ResponseWriter, *http.Request, string, string, string)
+}
+
+type ErrorHandler func(w http.ResponseWriter, r *http.Request, errorType string, errorDesc string, state string)
+
+var (
+	DefaultErrorHandler ErrorHandler = func(w http.ResponseWriter, r *http.Request, errorType string, errorDesc string, state string) {
+		http.Error(w, errorType+": "+errorDesc, http.StatusInternalServerError)
+	}
+)
+
+type relyingParty struct {
+	issuer      string
+	endpoints   Endpoints
+	oauthConfig *oauth2.Config
+	oauth2Only  bool
+	pkce        bool
+
+	httpClient    *http.Client
+	cookieHandler *utils.CookieHandler
+
+	errorHandler    func(http.ResponseWriter, *http.Request, string, string, string)
+	idTokenVerifier IDTokenVerifier
+	verifierOpts    []VerifierOption
+	signer          jose.Signer
+}
+
+func (rp *relyingParty) OAuthConfig() *oauth2.Config {
+	return rp.oauthConfig
+}
+
+func (rp *relyingParty) Issuer() string {
+	return rp.issuer
+}
+
+func (rp *relyingParty) IsPKCE() bool {
+	return rp.pkce
+}
+
+func (rp *relyingParty) CookieHandler() *utils.CookieHandler {
+	return rp.cookieHandler
+}
+
+func (rp *relyingParty) HttpClient() *http.Client {
+	return rp.httpClient
+}
+
+func (rp *relyingParty) IsOAuth2Only() bool {
+	return rp.oauth2Only
+}
+
+func (rp *relyingParty) Signer() jose.Signer {
+	return rp.signer
+}
+
+func (rp *relyingParty) UserinfoEndpoint() string {
+	return rp.endpoints.UserinfoURL
+}
+
+func (rp *relyingParty) IDTokenVerifier() IDTokenVerifier {
+	if rp.idTokenVerifier == nil {
+		rp.idTokenVerifier = NewIDTokenVerifier(rp.issuer, rp.oauthConfig.ClientID, NewRemoteKeySet(rp.httpClient, rp.endpoints.JKWsURL), rp.verifierOpts...)
+	}
+	return rp.idTokenVerifier
+}
+
+func (rp *relyingParty) ErrorHandler() func(http.ResponseWriter, *http.Request, string, string, string) {
+	if rp.errorHandler == nil {
+		rp.errorHandler = DefaultErrorHandler
+	}
+	return rp.errorHandler
+}
+
+//NewRelyingPartyOAuth creates an (OAuth2) RelyingParty with the given
+//OAuth2 Config and possible configOptions
+//it will use the AuthURL and TokenURL set in config
+func NewRelyingPartyOAuth(config *oauth2.Config, options ...Option) (RelyingParty, error) {
+	rp := &relyingParty{
+		oauthConfig: config,
+		httpClient:  utils.DefaultHTTPClient,
+		oauth2Only:  true,
+	}
+
+	for _, optFunc := range options {
+		if err := optFunc(rp); err != nil {
+			return nil, err
+		}
+	}
+
+	return rp, nil
+}
+
+//NewRelyingPartyOIDC creates an (OIDC) RelyingParty with the given
+//issuer, clientID, clientSecret, redirectURI, scopes and possible configOptions
+//it will run discovery on the provided issuer and use the found endpoints
+func NewRelyingPartyOIDC(issuer, clientID, clientSecret, redirectURI string, scopes []string, options ...Option) (RelyingParty, error) {
+	rp := &relyingParty{
+		issuer: issuer,
+		oauthConfig: &oauth2.Config{
+			ClientID:     clientID,
+			ClientSecret: clientSecret,
+			RedirectURL:  redirectURI,
+			Scopes:       scopes,
+		},
+		httpClient: utils.DefaultHTTPClient,
+		oauth2Only: false,
+	}
+
+	for _, optFunc := range options {
+		if err := optFunc(rp); err != nil {
+			return nil, err
+		}
+	}
+
+	endpoints, err := Discover(rp.issuer, rp.httpClient)
+	if err != nil {
+		return nil, err
+	}
+	rp.oauthConfig.Endpoint = endpoints.Endpoint
+	rp.endpoints = endpoints
+
+	return rp, nil
+}
+
+//DefaultRPOpts is the type for providing dynamic options to the DefaultRP
+type Option func(*relyingParty) error
+
+//WithCookieHandler set a `CookieHandler` for securing the various redirects
+func WithCookieHandler(cookieHandler *utils.CookieHandler) Option {
+	return func(rp *relyingParty) error {
+		rp.cookieHandler = cookieHandler
+		return nil
+	}
+}
+
+//WithPKCE sets the RP to use PKCE (oauth2 code challenge)
+//it also sets a `CookieHandler` for securing the various redirects
+//and exchanging the code challenge
+func WithPKCE(cookieHandler *utils.CookieHandler) Option {
+	return func(rp *relyingParty) error {
+		rp.pkce = true
+		rp.cookieHandler = cookieHandler
+		return nil
+	}
+}
+
+//WithHTTPClient provides the ability to set an http client to be used for the relaying party and verifier
+func WithHTTPClient(client *http.Client) Option {
+	return func(rp *relyingParty) error {
+		rp.httpClient = client
+		return nil
+	}
+}
+
+func WithErrorHandler(errorHandler ErrorHandler) Option {
+	return func(rp *relyingParty) error {
+		rp.errorHandler = errorHandler
+		return nil
+	}
+}
+
+func WithVerifierOpts(opts ...VerifierOption) Option {
+	return func(rp *relyingParty) error {
+		rp.verifierOpts = opts
+		return nil
+	}
+}
+
+func WithClientKey(path string) Option {
+	return func(rp *relyingParty) error {
+		config, err := client.ConfigFromKeyFile(path)
+		if err != nil {
+			return err
+		}
+		rp.signer, err = client.NewSignerFromPrivateKeyByte([]byte(config.Key), config.KeyID)
+		return err
+	}
+}
+
+//Discover calls the discovery endpoint of the provided issuer and returns the found endpoints
+//
+//deprecated: use client.Discover
+func Discover(issuer string, httpClient *http.Client) (Endpoints, error) {
+	wellKnown := strings.TrimSuffix(issuer, "/") + oidc.DiscoveryEndpoint
+	req, err := http.NewRequest("GET", wellKnown, nil)
+	if err != nil {
+		return Endpoints{}, err
+	}
+	discoveryConfig := new(oidc.DiscoveryConfiguration)
+	err = utils.HttpRequest(httpClient, req, &discoveryConfig)
+	if err != nil {
+		return Endpoints{}, err
+	}
+	return GetEndpoints(discoveryConfig), nil
+}
+
+//AuthURL returns the auth request url
+//(wrapping the oauth2 `AuthCodeURL`)
+func AuthURL(state string, rp RelyingParty, opts ...AuthURLOpt) string {
+	authOpts := make([]oauth2.AuthCodeOption, 0)
+	for _, opt := range opts {
+		authOpts = append(authOpts, opt()...)
+	}
+	return rp.OAuthConfig().AuthCodeURL(state, authOpts...)
+}
+
+//AuthURLHandler extends the `AuthURL` method with a http redirect handler
+//including handling setting cookie for secure `state` transfer
+func AuthURLHandler(stateFn func() string, rp RelyingParty) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		opts := make([]AuthURLOpt, 0)
+		state := stateFn()
+		if err := trySetStateCookie(w, state, rp); err != nil {
+			http.Error(w, "failed to create state cookie: "+err.Error(), http.StatusUnauthorized)
+			return
+		}
+		if rp.IsPKCE() {
+			codeChallenge, err := GenerateAndStoreCodeChallenge(w, rp)
+			if err != nil {
+				http.Error(w, "failed to create code challenge: "+err.Error(), http.StatusUnauthorized)
+				return
+			}
+			opts = append(opts, WithCodeChallenge(codeChallenge))
+		}
+		http.Redirect(w, r, AuthURL(state, rp, opts...), http.StatusFound)
+	}
+}
+
+//GenerateAndStoreCodeChallenge generates a PKCE code challenge and stores its verifier into a secure cookie
+func GenerateAndStoreCodeChallenge(w http.ResponseWriter, rp RelyingParty) (string, error) {
+	codeVerifier := uuid.New().String()
+	if err := rp.CookieHandler().SetCookie(w, pkceCode, codeVerifier); err != nil {
+		return "", err
+	}
+	return oidc.NewSHACodeChallenge(codeVerifier), nil
+}
+
+//CodeExchange handles the oauth2 code exchange, extracting and validating the id_token
+//returning it parsed together with the oauth2 tokens (access, refresh)
+func CodeExchange(ctx context.Context, code string, rp RelyingParty, opts ...CodeExchangeOpt) (tokens *oidc.Tokens, err error) {
+	ctx = context.WithValue(ctx, oauth2.HTTPClient, rp.HttpClient())
+	codeOpts := make([]oauth2.AuthCodeOption, 0)
+	for _, opt := range opts {
+		codeOpts = append(codeOpts, opt()...)
+	}
+
+	token, err := rp.OAuthConfig().Exchange(ctx, code, codeOpts...)
+	if err != nil {
+		return nil, err
+	}
+
+	if rp.IsOAuth2Only() {
+		return &oidc.Tokens{Token: token}, nil
+	}
+
+	idTokenString, ok := token.Extra(idTokenKey).(string)
+	if !ok {
+		return nil, errors.New("id_token missing")
+	}
+
+	idToken, err := VerifyTokens(ctx, token.AccessToken, idTokenString, rp.IDTokenVerifier())
+	if err != nil {
+		return nil, err
+	}
+
+	return &oidc.Tokens{Token: token, IDTokenClaims: idToken, IDToken: idTokenString}, nil
+}
+
+//CodeExchangeHandler extends the `CodeExchange` method with a http handler
+//including cookie handling for secure `state` transfer
+//and optional PKCE code verifier checking
+func CodeExchangeHandler(callback func(http.ResponseWriter, *http.Request, *oidc.Tokens, string), rp RelyingParty) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		state, err := tryReadStateCookie(w, r, rp)
+		if err != nil {
+			http.Error(w, "failed to get state: "+err.Error(), http.StatusUnauthorized)
+			return
+		}
+		params := r.URL.Query()
+		if params.Get("error") != "" {
+			rp.ErrorHandler()(w, r, params.Get("error"), params.Get("error_description"), state)
+			return
+		}
+		codeOpts := make([]CodeExchangeOpt, 0)
+		if rp.IsPKCE() {
+			codeVerifier, err := rp.CookieHandler().CheckCookie(r, pkceCode)
+			if err != nil {
+				http.Error(w, "failed to get code verifier: "+err.Error(), http.StatusUnauthorized)
+				return
+			}
+			codeOpts = append(codeOpts, WithCodeVerifier(codeVerifier))
+		}
+		if rp.Signer() != nil {
+			assertion, err := client.SignedJWTProfileAssertion(rp.OAuthConfig().ClientID, []string{rp.Issuer()}, time.Hour, rp.Signer())
+			if err != nil {
+				http.Error(w, "failed to build assertion: "+err.Error(), http.StatusUnauthorized)
+				return
+			}
+			codeOpts = append(codeOpts, WithClientAssertionJWT(assertion))
+		}
+		tokens, err := CodeExchange(r.Context(), params.Get("code"), rp, codeOpts...)
+		if err != nil {
+			http.Error(w, "failed to exchange token: "+err.Error(), http.StatusUnauthorized)
+			return
+		}
+		callback(w, r, tokens, state)
+	}
+}
+
+//Userinfo will call the OIDC Userinfo Endpoint with the provided token
+func Userinfo(token string, rp RelyingParty) (oidc.UserInfo, error) {
+	req, err := http.NewRequest("GET", rp.UserinfoEndpoint(), nil)
+	if err != nil {
+		return nil, err
+	}
+	req.Header.Set("authorization", token)
+	userinfo := oidc.NewUserInfo()
+	if err := utils.HttpRequest(rp.HttpClient(), req, &userinfo); err != nil {
+		return nil, err
+	}
+	return userinfo, nil
+}
+
+func trySetStateCookie(w http.ResponseWriter, state string, rp RelyingParty) error {
+	if rp.CookieHandler() != nil {
+		if err := rp.CookieHandler().SetCookie(w, stateParam, state); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+func tryReadStateCookie(w http.ResponseWriter, r *http.Request, rp RelyingParty) (state string, err error) {
+	if rp.CookieHandler() == nil {
+		return r.FormValue(stateParam), nil
+	}
+	state, err = rp.CookieHandler().CheckQueryCookie(r, stateParam)
+	if err != nil {
+		return "", err
+	}
+	rp.CookieHandler().DeleteCookie(w, stateParam)
+	return state, nil
+}
+
+type OptionFunc func(RelyingParty)
+
+type Endpoints struct {
+	oauth2.Endpoint
+	IntrospectURL string
+	UserinfoURL   string
+	JKWsURL       string
+}
+
+func GetEndpoints(discoveryConfig *oidc.DiscoveryConfiguration) Endpoints {
+	return Endpoints{
+		Endpoint: oauth2.Endpoint{
+			AuthURL:   discoveryConfig.AuthorizationEndpoint,
+			AuthStyle: oauth2.AuthStyleAutoDetect,
+			TokenURL:  discoveryConfig.TokenEndpoint,
+		},
+		IntrospectURL: discoveryConfig.IntrospectionEndpoint,
+		UserinfoURL:   discoveryConfig.UserinfoEndpoint,
+		JKWsURL:       discoveryConfig.JwksURI,
+	}
+}
+
+type AuthURLOpt func() []oauth2.AuthCodeOption
+
+//WithCodeChallenge sets the `code_challenge` params in the auth request
+func WithCodeChallenge(codeChallenge string) AuthURLOpt {
+	return func() []oauth2.AuthCodeOption {
+		return []oauth2.AuthCodeOption{
+			oauth2.SetAuthURLParam("code_challenge", codeChallenge),
+			oauth2.SetAuthURLParam("code_challenge_method", "S256"),
+		}
+	}
+}
+
+//WithPrompt sets the `prompt` params in the auth request
+func WithPrompt(prompt oidc.Prompt) AuthURLOpt {
+	return func() []oauth2.AuthCodeOption {
+		return []oauth2.AuthCodeOption{
+			oauth2.SetAuthURLParam("prompt", string(prompt)),
+		}
+	}
+}
+
+type CodeExchangeOpt func() []oauth2.AuthCodeOption
+
+//WithCodeVerifier sets the `code_verifier` param in the token request
+func WithCodeVerifier(codeVerifier string) CodeExchangeOpt {
+	return func() []oauth2.AuthCodeOption {
+		return []oauth2.AuthCodeOption{oauth2.SetAuthURLParam("code_verifier", codeVerifier)}
+	}
+}
+
+//WithClientAssertionJWT sets the `client_assertion` param in the token request
+func WithClientAssertionJWT(clientAssertion string) CodeExchangeOpt {
+	return func() []oauth2.AuthCodeOption {
+		return client.ClientAssertionCodeOptions(clientAssertion)
+	}
+}

pkg/client/rp/tockenexchange.go

@@ -0,0 +1,27 @@
+package rp
+
+import (
+	"context"
+
+	"golang.org/x/oauth2"
+
+	"github.com/caos/oidc/pkg/oidc/grants/tokenexchange"
+)
+
+//TokenExchangeRP extends the `RelyingParty` interface for the *draft* oauth2 `Token Exchange`
+type TokenExchangeRP interface {
+	RelyingParty
+
+	//TokenExchange implement the `Token Exchange Grant` exchanging some token for an other
+	TokenExchange(context.Context, *tokenexchange.TokenExchangeRequest) (*oauth2.Token, error)
+}
+
+//DelegationTokenExchangeRP extends the `TokenExchangeRP` interface
+//for the specific `delegation token` request
+type DelegationTokenExchangeRP interface {
+	TokenExchangeRP
+
+	//DelegationTokenExchange implement the `Token Exchange Grant`
+	//providing an access token in request for a `delegation` token for a given resource / audience
+	DelegationTokenExchange(context.Context, string, ...tokenexchange.TokenExchangeOption) (*oauth2.Token, error)
+}

pkg/client/rp/verifier.go

@@ -0,0 +1,216 @@
+package rp
+
+import (
+	"context"
+	"time"
+
+	"gopkg.in/square/go-jose.v2"
+
+	"github.com/caos/oidc/pkg/oidc"
+)
+
+type IDTokenVerifier interface {
+	oidc.Verifier
+	ClientID() string
+	SupportedSignAlgs() []string
+	KeySet() oidc.KeySet
+	Nonce(context.Context) string
+	ACR() oidc.ACRVerifier
+	MaxAge() time.Duration
+}
+
+//VerifyTokens implement the Token Response Validation as defined in OIDC specification
+//https://openid.net/specs/openid-connect-core-1_0.html#TokenResponseValidation
+func VerifyTokens(ctx context.Context, accessToken, idTokenString string, v IDTokenVerifier) (oidc.IDTokenClaims, error) {
+	idToken, err := VerifyIDToken(ctx, idTokenString, v)
+	if err != nil {
+		return nil, err
+	}
+	if err := VerifyAccessToken(accessToken, idToken.GetAccessTokenHash(), idToken.GetSignatureAlgorithm()); err != nil {
+		return nil, err
+	}
+	return idToken, nil
+}
+
+//VerifyIDToken validates the id token according to
+//https://openid.net/specs/openid-connect-core-1_0.html#IDTokenValidation
+func VerifyIDToken(ctx context.Context, token string, v IDTokenVerifier) (oidc.IDTokenClaims, error) {
+	claims := oidc.EmptyIDTokenClaims()
+
+	decrypted, err := oidc.DecryptToken(token)
+	if err != nil {
+		return nil, err
+	}
+	payload, err := oidc.ParseToken(decrypted, claims)
+	if err != nil {
+		return nil, err
+	}
+
+	if err := oidc.CheckIssuer(claims, v.Issuer()); err != nil {
+		return nil, err
+	}
+
+	if err = oidc.CheckAudience(claims, v.ClientID()); err != nil {
+		return nil, err
+	}
+
+	if err = oidc.CheckAuthorizedParty(claims, v.ClientID()); err != nil {
+		return nil, err
+	}
+
+	if err = oidc.CheckSignature(ctx, decrypted, payload, claims, v.SupportedSignAlgs(), v.KeySet()); err != nil {
+		return nil, err
+	}
+
+	if err = oidc.CheckExpiration(claims, v.Offset()); err != nil {
+		return nil, err
+	}
+
+	if err = oidc.CheckIssuedAt(claims, v.MaxAgeIAT(), v.Offset()); err != nil {
+		return nil, err
+	}
+
+	if err = oidc.CheckNonce(claims, v.Nonce(ctx)); err != nil {
+		return nil, err
+	}
+
+	if err = oidc.CheckAuthorizationContextClassReference(claims, v.ACR()); err != nil {
+		return nil, err
+	}
+
+	if err = oidc.CheckAuthTime(claims, v.MaxAge()); err != nil {
+		return nil, err
+	}
+	return claims, nil
+}
+
+//VerifyAccessToken validates the access token according to
+//https://openid.net/specs/openid-connect-core-1_0.html#CodeFlowTokenValidation
+func VerifyAccessToken(accessToken, atHash string, sigAlgorithm jose.SignatureAlgorithm) error {
+	if atHash == "" {
+		return nil
+	}
+
+	actual, err := oidc.ClaimHash(accessToken, sigAlgorithm)
+	if err != nil {
+		return err
+	}
+	if actual != atHash {
+		return oidc.ErrAtHash
+	}
+	return nil
+}
+
+//NewIDTokenVerifier returns an implementation of `IDTokenVerifier`
+//for `VerifyTokens` and `VerifyIDToken`
+func NewIDTokenVerifier(issuer, clientID string, keySet oidc.KeySet, options ...VerifierOption) IDTokenVerifier {
+	v := &idTokenVerifier{
+		issuer:   issuer,
+		clientID: clientID,
+		keySet:   keySet,
+		offset:   1 * time.Second,
+		nonce: func(_ context.Context) string {
+			return ""
+		},
+	}
+
+	for _, opts := range options {
+		opts(v)
+	}
+
+	return v
+}
+
+//VerifierOption is the type for providing dynamic options to the IDTokenVerifier
+type VerifierOption func(*idTokenVerifier)
+
+//WithIssuedAtOffset mitigates the risk of iat to be in the future
+//because of clock skews with the ability to add an offset to the current time
+func WithIssuedAtOffset(offset time.Duration) func(*idTokenVerifier) {
+	return func(v *idTokenVerifier) {
+		v.offset = offset
+	}
+}
+
+//WithIssuedAtMaxAge provides the ability to define the maximum duration between iat and now
+func WithIssuedAtMaxAge(maxAge time.Duration) func(*idTokenVerifier) {
+	return func(v *idTokenVerifier) {
+		v.maxAge = maxAge
+	}
+}
+
+//WithNonce sets the function to check the nonce
+func WithNonce(nonce func(context.Context) string) VerifierOption {
+	return func(v *idTokenVerifier) {
+		v.nonce = nonce
+	}
+}
+
+//WithACRVerifier sets the verifier for the acr claim
+func WithACRVerifier(verifier oidc.ACRVerifier) VerifierOption {
+	return func(v *idTokenVerifier) {
+		v.acr = verifier
+	}
+}
+
+//WithAuthTimeMaxAge provides the ability to define the maximum duration between auth_time and now
+func WithAuthTimeMaxAge(maxAge time.Duration) VerifierOption {
+	return func(v *idTokenVerifier) {
+		v.maxAge = maxAge
+	}
+}
+
+//WithSupportedSigningAlgorithms overwrites the default RS256 signing algorithm
+func WithSupportedSigningAlgorithms(algs ...string) VerifierOption {
+	return func(v *idTokenVerifier) {
+		v.supportedSignAlgs = algs
+	}
+}
+
+type idTokenVerifier struct {
+	issuer            string
+	maxAgeIAT         time.Duration
+	offset            time.Duration
+	clientID          string
+	supportedSignAlgs []string
+	keySet            oidc.KeySet
+	acr               oidc.ACRVerifier
+	maxAge            time.Duration
+	nonce             func(ctx context.Context) string
+}
+
+func (i *idTokenVerifier) Issuer() string {
+	return i.issuer
+}
+
+func (i *idTokenVerifier) MaxAgeIAT() time.Duration {
+	return i.maxAgeIAT
+}
+
+func (i *idTokenVerifier) Offset() time.Duration {
+	return i.offset
+}
+
+func (i *idTokenVerifier) ClientID() string {
+	return i.clientID
+}
+
+func (i *idTokenVerifier) SupportedSignAlgs() []string {
+	return i.supportedSignAlgs
+}
+
+func (i *idTokenVerifier) KeySet() oidc.KeySet {
+	return i.keySet
+}
+
+func (i *idTokenVerifier) Nonce(ctx context.Context) string {
+	return i.nonce(ctx)
+}
+
+func (i *idTokenVerifier) ACR() oidc.ACRVerifier {
+	return i.acr
+}
+
+func (i *idTokenVerifier) MaxAge() time.Duration {
+	return i.maxAge
+}