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
.
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 examples of an OpenID Provider implementations (including dynamic) with some very basic login UI
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.
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/v3/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/v3/example/client/app
test-user@localhost
and password verysecure
for the dynamic issuer, just start it with:
go run github.com/zitadel/oidc/v3/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/zitadel/oidc/v3/example/client/app
Note: Usernames are suffixed with the hostname (
test-user@localhost
ortest-user@oidc.local
)
Relying party | OpenID Provider | Specification | |
---|---|---|---|
Code Flow | yes | yes | OpenID Connect Core 1.0, Section 3.1 |
Implicit Flow | no^1 | yes | OpenID Connect Core 1.0, Section 3.2 |
Hybrid Flow | no | not yet | OpenID Connect Core 1.0, Section 3.3 |
Client Credentials | yes | yes | OpenID Connect Core 1.0, Section 9 |
Refresh Token | yes | yes | OpenID Connect Core 1.0, Section 12 |
Discovery | yes | yes | OpenID Connect Discovery 1.0 |
JWT Profile | yes | yes | RFC 7523 |
PKCE | yes | yes | RFC 7636 |
Token Exchange | yes | yes | RFC 8693 |
Device Authorization | yes | yes | RFC 8628 |
mTLS | not yet | not yet | RFC 8705 |
Made with contrib.rocks.
For your convenience you can find the relevant guides linked below.
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 :warning:.
Version | Supported |
---|---|
<1.21 | :x: |
1.21 | :white_check_mark: |
1.22 | :white_check_mark: |
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.
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
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.
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.