protocol

KexCore OpenID Connect SDK (client and server) for Go

What Is It

A full-stack OAuth 2.1 / OpenID Connect Core 1.0 SDK for Go — OP + RP — with a plugin-based server engine (StormEngine) and Chinese Commercial Cryptography (SM2/SM3/SM4/SM9).

Based on zitadel/oidc (RP client), with self-developed components:

• StormEngine (/pkg/storm) — plugin-based OP, each RFC endpoint is an independent plugin
• GM/T national cryptography (/pkg/crypto) — SM2/SM3/SM4/SM9 full suite, HSM/KMS support
• Shared protocol layer (/pkg/protocol) — zero dependency, single source of truth

The RP is certified for the oidf-basic and oidf-config profile. The OP is certified for the oidf-backchannel profile.

Basic Overview

The most important packages of the library:

/pkg
    /protocol          OAuth 2.1 / OIDC types, errors, verifiers (zero dependency)
    /storm             Plugin-based OIDC server engine
        /plugins       Individual RFC endpoint plugins (17 plugins)
    /client            RP client (based on zitadel/oidc)
        /rp            OIDC Relying Party
        /rs            OAuth Resource Server
    /crypto            SM2/SM3/SM4/SM9 + HSM/KMS provider registry

/example
    /storm-server      StormEngine-based OP (recommended)
    /client/app        RP web app (authorization code flow)
    /client/api        Resource server with token introspection

Semver

This package uses semver for releases. Major releases ship breaking changes. Starting with the v2 to v3 increment we provide an upgrade guide to ease migration to a newer version.

How To Use It

Check the /example folder where example code for different scenarios is located.

# start oidc op server (StormEngine)
# oidc discovery http://localhost:9998/.well-known/openid-configuration
go run github.com/roidmc/kexcore-oidc/example/storm-server
# start oidc web client (in a new terminal)
CLIENT_ID=web CLIENT_SECRET=secret ISSUER=http://localhost:9998/ SCOPES="openid profile" PORT=9999 go run github.com/roidmc/kexcore-oidc/example/client/app

• open http://localhost:9999/login in your browser
• you will be redirected to op server and the login UI
• login with user test-user@localhost and password verysecure
• the OP will redirect you to the client app, which displays the user info

for the dynamic issuer, just start it with:

go run github.com/roidmc/kexcore-oidc/example/server/dynamic

the oidc web client above will still work, but if you add oidc.local (pointing to 127.0.0.1) in your hosts file you can also start it with:

CLIENT_ID=web CLIENT_SECRET=secret ISSUER=http://oidc.local:9998/ SCOPES="openid profile" PORT=9999 go run github.com/roidmc/kexcore-oidc/example/client/app

Note: Usernames are suffixed with the hostname (test-user@localhost or test-user@oidc.local)

Build Tags

The library uses build tags to enable or disable features. The following build tags are available:

Server configuration

Example server allows extra configuration using environment variables and could be used for end-to-end testing of your services.

Here is json equivalent for one of the default users

{
  "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
  }
}

Features

OpenID Provider (/pkg/storm) — StormEngine

Plugin-based OIDC server framework.

FAPI Profiles (Financial-grade API)

StormEngine 实现 FAPI 1.0 Advanced 与 FAPI 2.0 Security Profile 的核心安全要求，支持通过 OIDF Conformance Test Suite 认证。

Known Conformance Suite Issues: StormEngine implements mTLS client certificate reading per RFC 8705 §2 (from tls.PeerCertificates). The OIDF Conformance Suite has a bug where env.mapKey("mutual_tls_authentication") does not prevent the HTTP client from sending certificates in the TLS handshake, causing ensure-holder-of-key-required and refresh-token tests to fail for client_auth_type=mtls + sender_constrain=dpop variants. This affects any implementation that reads certificates directly from the TLS layer. See example/testsuite/docs/issues.md for details and proposed fix.

Relying Party (/pkg/client)

Note on Chinese Commercial Cryptography (国密): This library supports SM2, SM3, SM4, and SM9 algorithms via the SGD_SM3_SM2 (SM2+SM3 signature), SGD_SM3_SM9 (SM9 identity-based signature), SGD_SM2_3 (SM2 key wrapping), SGD_SM9_3 (SM9 key wrapping), and SGD_SM4_GCM/SGD_SM4_CCM (SM4 content encryption) identifiers per GM/T 0125.1-2022 and GM/T 0125.3-2022. These are not defined in RFC 7518 and therefore are not recognized by the OpenID Foundation (OIDF) Conformance Test Suite. When running OIDF certification tests, disable national-crypto algorithms by setting the environment variable SIGNING_ALGORITHMS=RS256,RS384,RS512,PS256,PS384,PS512,ES256,ES384,ES512,EdDSA so that the JWKS endpoint only returns standard JWKs.

Contributors

Made with contrib.rocks.

Resources

For your convenience you can find the relevant guides linked below.

• OpenID Connect Core 1.0 incorporating errata set 1
• OIDC/OAuth Flow in Zitadel (using this library)

Supported Go Versions

For security reasons, we only support and recommend the use of one of the latest two Go versions (✅). Versions that also build are marked with ⚠.

Why another library

RP client based on zitadel/oidc. OP entirely self-developed with StormEngine plugin architecture.

Goals

• Certify this library as OP (incl. FAPI 2.0 Security Profile)
• Provide the most RFC-complete embeddable Go OIDC SDK
• First-class Chinese national standards (GM/T 0125) alongside international standards
• Storage-agnostic — never lock into a specific database

Other Go OpenID Connect libraries

License

The full functionality of this library is and stays open source and free to use for everyone. Visit our website and get in touch.

See the exact licensing terms here

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an " AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.