feat: generic Userinfo and Introspect functions (#389)

BREAKING CHANGE: rp.Userinfo and rs.Introspect now require
a type parameter.

pkg/client/rs/introspect_example_test.go

@@ -0,0 +1,52 @@
+package rs_test
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/zitadel/oidc/v3/pkg/client/rs"
+	"github.com/zitadel/oidc/v3/pkg/oidc"
+)
+
+type IntrospectionResponse struct {
+	Active     bool                     `json:"active"`
+	Scope      oidc.SpaceDelimitedArray `json:"scope,omitempty"`
+	ClientID   string                   `json:"client_id,omitempty"`
+	TokenType  string                   `json:"token_type,omitempty"`
+	Expiration oidc.Time                `json:"exp,omitempty"`
+	IssuedAt   oidc.Time                `json:"iat,omitempty"`
+	NotBefore  oidc.Time                `json:"nbf,omitempty"`
+	Subject    string                   `json:"sub,omitempty"`
+	Audience   oidc.Audience            `json:"aud,omitempty"`
+	Issuer     string                   `json:"iss,omitempty"`
+	JWTID      string                   `json:"jti,omitempty"`
+	Username   string                   `json:"username,omitempty"`
+	oidc.UserInfoProfile
+	oidc.UserInfoEmail
+	oidc.UserInfoPhone
+	Address *oidc.UserInfoAddress `json:"address,omitempty"`
+
+	// Foo and Bar are custom claims
+	Foo string `json:"foo,omitempty"`
+	Bar struct {
+		Val1 string `json:"val_1,omitempty"`
+		Val2 string `json:"val_2,omitempty"`
+	} `json:"bar,omitempty"`
+
+	// Claims are all the combined claims, including custom.
+	Claims map[string]any `json:"-,omitempty"`
+}
+
+func ExampleIntrospect_custom() {
+	rss, err := rs.NewResourceServerClientCredentials(context.TODO(), "http://localhost:8080", "clientid", "clientsecret")
+	if err != nil {
+		panic(err)
+	}
+
+	resp, err := rs.Introspect[*IntrospectionResponse](context.TODO(), rss, "accesstokenstring")
+	if err != nil {
+		panic(err)
+	}
+
+	fmt.Println(resp)
+}

pkg/client/rs/resource_server.go

@@ -112,18 +112,24 @@ func WithStaticEndpoints(tokenURL, introspectURL string) Option {
 	}
 }
 
-func Introspect(ctx context.Context, rp ResourceServer, token string) (*oidc.IntrospectionResponse, error) {
+// Introspect calls the [RFC7662] Token Introspection
+// endpoint and returns the response in an instance of type R.
+// [*oidc.IntrospectionResponse] can be used as a good example, or use a custom type if type-safe
+// access to custom claims is needed.
+//
+// [RFC7662]: https://www.rfc-editor.org/rfc/rfc7662
+func Introspect[R any](ctx context.Context, rp ResourceServer, token string) (resp R, err error) {
 	authFn, err := rp.AuthFn()
 	if err != nil {
-		return nil, err
+		return resp, err
 	}
 	req, err := httphelper.FormRequest(ctx, rp.IntrospectionURL(), &oidc.IntrospectionRequest{Token: token}, client.Encoder, authFn)
 	if err != nil {
-		return nil, err
+		return resp, err
 	}
-	resp := new(oidc.IntrospectionResponse)
-	if err := httphelper.HttpRequest(rp.HttpClient(), req, resp); err != nil {
-		return nil, err
+
+	if err := httphelper.HttpRequest(rp.HttpClient(), req, &resp); err != nil {
+		return resp, err
 	}
 	return resp, nil
 }