Skip to content

cargomail-org/cargomail-zitadel-oidc

 
 

Repository files navigation

OpenID Connect SDK (client and server) for Go

semantic-release Release GoDoc license release Go Report Card codecov

openid_certified

What Is It

This project is an easy-to-use client (RP) and server (OP) implementation for the OIDC (OpenID Connect) standard written for Go.

The RP is certified for the basic and config profile.

Whenever possible we tried to reuse / extend existing packages like OAuth2 for Go.

Basic Overview

The most important packages of the library:

/pkg
    /client            clients using the OP for retrieving, exchanging and verifying tokens       
        /rp            definition and implementation of an OIDC Relying Party (client)
        /rs            definition and implementation of an OAuth Resource Server (API)
    /op                definition and implementation of an OIDC OpenID Provider (server)
    /oidc              definitions shared by clients and server

/example
    /client/api        example of an api / resource server implementation using token introspection
    /client/app        web app / RP demonstrating authorization code flow using various authentication methods (code, PKCE, JWT profile)
    /client/github     example of the extended OAuth2 library, providing an HTTP client with a reuse token source
    /client/service    demonstration of JWT Profile Authorization Grant
    /server            example of an OpenID Provider implementation including some very basic login UI

How To Use It

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

# start oidc op server
# oidc discovery http://localhost:9998/.well-known/openid-configuration
go run github.com/zitadel/oidc/example/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/zitadel/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 and password verysecure
  • the OP will redirect you to the client app, which displays the user info

Features

Code Flow Implicit Flow Hybrid Flow Discovery PKCE Token Exchange mTLS JWT Profile Refresh Token Client Credentials
Relying Party yes no1 no yes yes partial not yet yes yes not yet
OpenID Provider yes yes not yet yes yes not yet not yet yes yes yes

Contributors

Screen with contributors' avatars from contrib.rocks

Made with contrib.rocks.

Resources

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

Supported Go Versions

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

Version Supported
<1.15
1.15 ⚠️
1.16 ⚠️
1.17 ⚠️
1.18
1.19

Why another library

As of 2020 there are not a lot of OIDC library's in Go which can handle server and client implementations. ZITADEL is strongly committed to the general field of IAM (Identity and Access Management) and as such, we need solid frameworks to implement services.

Goals

Other Go OpenID Connect libraries

https://github.com/coreos/go-oidc

The go-oidc does only support RP and is not feasible to use as OP that's why we could not rely on go-oidc

https://github.com/ory/fosite

We did not choose fosite because it implements OAuth 2.0 on its own and does not rely on the golang provided package. Nonetheless this is a great project.

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.

Footnotes

  1. https://github.com/zitadel/oidc/issues/135#issuecomment-950563892