oidc: add API for determining when issuer URLs mismatch

Fixes #471
Fixes #481

Author: ericchiang

oidc/oidc.go

@@ -244,10 +244,34 @@ func (p *ProviderConfig) NewProvider(ctx context.Context) *Provider {
 	}
 }
 
+// IssuerMismatchError is returned by [NewProvider] when the "iss" value
+// reported by the upstream is different than the expected value.
+//
+// Issuer mismatches can occur due to trailing slashes ("https://example.com"
+// vs. "https://example.com/") or represent significant misconfiguration for
+// multi-tenant issuers.
+//
+// Issuers must match exactly as they are also used to validate ID Tokens.
+//
+// https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata
+type IssuerMismatchError struct {
+	// The value provided to this package. The expected value.
+	Provided string
+	// The value advertised by the discovery document.
+	Discovered string
+}
+
+func (e *IssuerMismatchError) Error() string {
+	return fmt.Sprintf("oidc: issuer URL provided to client (%q) did not match the issuer URL returned by provider (%q)", e.Provided, e.Discovered)
+}
+
 // 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".
 //
+// If the "iss" value returned in the discovery document doesn't match the value
+// provided here, [IssuerMismatchError] is returned.
+//
 // OpenID Connect providers that don't implement discovery or host the discovery
 // document at a non-spec compliant path (such as requiring a URL parameter),
 // should use [ProviderConfig] instead.
@@ -285,7 +309,10 @@ func NewProvider(ctx context.Context, issuer string) (*Provider, error) {
 		issuerURL = issuer
 	}
 	if p.Issuer != issuerURL && !skipIssuerValidation {
-		return nil, fmt.Errorf("oidc: issuer URL provided to client (%q) did not match the issuer URL returned by provider (%q)", issuer, p.Issuer)
+		return nil, &IssuerMismatchError{
+			Provided:   issuerURL,
+			Discovered: p.Issuer,
+		}
 	}
 	var algs []string
 	for _, a := range p.Algorithms {

oidc/oidc_test.go

@@ -6,6 +6,7 @@ import (
 	"crypto/elliptic"
 	"crypto/rand"
 	"encoding/json"
+	"errors"
 	"fmt"
 	"io"
 	"net/http"
@@ -343,6 +344,49 @@ func TestNewProvider(t *testing.T) {
 	}
 }
 
+func TestIssuerMismatchError(t *testing.T) {
+	ctx := t.Context()
+
+	var issuer string
+	hf := func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/.well-known/openid-configuration" {
+			http.NotFound(w, r)
+			return
+		}
+		w.Header().Set("Content-Type", "application/json")
+		// The discovery document advertises an issuer that differs from the
+		// one requested (note the trailing slash), which must be rejected.
+		io.WriteString(w, `{
+			"issuer": "`+issuer+`/",
+			"authorization_endpoint": "https://example.com/auth",
+			"token_endpoint": "https://example.com/token",
+			"jwks_uri": "https://example.com/keys",
+			"id_token_signing_alg_values_supported": ["RS256"]
+		}`)
+	}
+	s := httptest.NewServer(http.HandlerFunc(hf))
+	defer s.Close()
+	issuer = s.URL
+
+	_, err := NewProvider(ctx, issuer)
+	if err == nil {
+		t.Fatal("NewProvider(): expected error, got nil")
+	}
+
+	var mismatchErr *IssuerMismatchError
+	if !errors.As(err, &mismatchErr) {
+		t.Fatalf("NewProvider() returned %T, want *IssuerMismatchError: %v", err, err)
+	}
+
+	want := &IssuerMismatchError{
+		Provided:   issuer,
+		Discovered: issuer + "/",
+	}
+	if !reflect.DeepEqual(mismatchErr, want) {
+		t.Errorf("NewProvider() returned unexpected error, got=%+v, want=%+v", mismatchErr, want)
+	}
+}
+
 func TestProviderConfigJSON(t *testing.T) {
 	// https://accounts.google.com/.well-known/openid-configuration
 	testCase := `