zitadel/oidc Go SDK

The zitadel/oidc project provides a complete OpenID Connect (OIDC) implementation for Go, supporting both the Relying Party (RP/Client) and the OpenID Provider (OP/Server) roles.

Core Packages

• pkg/client/rp: Implementation of an OIDC Relying Party (client).
• pkg/client/rs: Implementation of an OAuth Resource Server (API).
• pkg/op: Implementation of an OIDC OpenID Provider (server).
• pkg/oidc: Shared definitions used by both clients and servers.

The OIDC framework now uses the standard library log/slog for logging.

• Default Behavior: By default, slog.Default() is used.
• Configuration: Use the WithLogger() method on the Provider to configure a custom logger.
• Accessing Logger: The OpenIDProvider and sub-interfaces like Authorizer and Exchanger provide a Logger() method to retrieve the configured logger.
• Customizing Log Output: You can implement the LogAuthRequest interface on your AuthRequest type. If implemented, the AuthRequest is passed to the logger after an error, using its LogValue() method to control which fields are printed (useful for omitting sensitive data).

The OIDC SDK now uses the standard Go log/slog package for all logging. Instead of configuring loggers on individual OP or RP instances, you must configure the process-wide default slog handler before constructing your OIDC components.

Key changes:

• op.WithLogger and op.WithFallbackLogger are now no-ops.
• op.Provider.Logger() returns slog.Default().
• rp.WithLogger is deprecated; the RP package no longer writes through the provided logger, instead using the global slog default.
• Arguments passed to RequestError, WriteError, and TryErrorRedirect are now ignored.
• Remove dependencies on logging.ToContext and github.com/zitadel/logging middleware. Use your own middleware and slog.Handler for request logging or context enrichment.

To upgrade your project from version 2 to version 3 of the OIDC SDK, follow these steps:

1. Download the latest v3 module: go get -u github.com/zitadel/oidc/v3.
2. Replace all imports in your Go files from github.com/zitadel/oidc/v2 to github.com/zitadel/oidc/v3.
3. Run go mod tidy to clean up the module file.

Note: This migration involves significant breaking changes, including the addition of context.Context to most function signatures and changes to several interfaces becoming struct types.

go get -u github.com/zitadel/oidc/v3
find . -type f -name '*.go' | xargs sed -i \
    -e 's/github\.com\/zitadel\/oidc\/v2/github.com\/zitadel\/oidc\/v3/g'
go mod tidy

The library uses the standard Go log/slog package for logging. Because the logger is process-wide, you should configure the global slog default before constructing any OIDC provider or relying party.

To use JSON logging:

slog.SetDefault(slog.New(slog.NewJSONHandler(os.Stderr, nil)))

To disable all OIDC logs, set the default logger to a handler that discards output:

slog.SetDefault(slog.New(slog.NewTextHandler(io.Discard, nil)))

Note: Existing WithLogger, WithFallbackLogger, and Logger APIs are deprecated and should not be used in new code.

When returning data from op.Server methods, use these two types:

• op.Response: Used for JSON-based responses. Use op.NewResponse(data) to create one. The Data field is marshaled to JSON in the response body. You can also add custom headers via the Header field.
• op.Redirect: Used for endpoints that must redirect the user (e.g., Authorize, EndSession). Use op.NewRedirect(url) to create one. This initiates a http.StatusFound redirect.

The example server implementation supports the following environment variables for testing and configuration:

User Data Format

The USERS_FILE should point to a JSON object where keys are user IDs. Example structure:

{
  "id2": {
    "ID": "id2",
    "Username": "test-user2",
    "Password": "verysecure",
    "FirstName": "Test",
    "LastName": "User2",
    "Email": "test-user2@zitadel.ch",
    "EmailVerified": true,
    "Phone": "",
    "PhoneVerified": false,
    "PreferredLanguage": "DE",
    "IsAdmin": false
  }
}

The op.Server methods use two primary request wrappers to provide access to HTTP metadata and parsed data:

1. op.Request[T]: Used for endpoints that do not require client authentication (e.g., Discovery, UserInfo, Introspect). It contains:

   • Method: The HTTP method.
   • URL: The parsed URL.
   • Header: The HTTP headers.
   • Form / PostForm: URL-encoded form values.
   • Data: A pointer to the parsed body/parameters of type T.

2. op.ClientRequest[T]: A specialized version of op.Request[T] used for endpoints that require client authentication (e.g., CodeExchange, RefreshToken, Revocation). It includes the Client field, which contains the authenticated Client object.

The client/profile package introduces a TokenSource interface that extends oauth2.TokenSource with a TokenCtx method to allow explicit context passing.

Constructors now require a context as the first argument:

• NewJWTProfileTokenSource
• NewJWTProfileTokenSourceFromKeyFileData
• NewJWTProfileTokenSourceFromKeyFile