Skip to content

Commit eec5daf

Browse files
ericchiangericchiang
committed
readme: update README and docs
This change rewrites the readme and go docs to try to do a better job of examplining what OpenID Connect is, and how to get started with the package.
1 parent f9049c9 commit eec5daf

2 files changed

Lines changed: 121 additions & 21 deletions

File tree

‎README.md‎

Lines changed: 58 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -1,27 +1,61 @@
11
# go-oidc
22

33
[![Go Reference](https://pkg.go.dev/badge/github.com/coreos/go-oidc/v3/oidc.svg)](https://pkg.go.dev/github.com/coreos/go-oidc/v3/oidc)
4-
![github.com/coreos/go-oidc/v3](https://github.com/coreos/go-oidc/workflows/test/badge.svg?branch=v3)
54

6-
## Updates from v2 to v3
7-
8-
There were two breaking changes made to the v3 branch. The import path has changed from:
9-
10-
```
11-
github.com/coreos/go-oidc
12-
```
13-
14-
to:
15-
16-
```
17-
github.com/coreos/go-oidc/v3/oidc
5+
OpenID Connect is a specification on top of OAuth 2.0 that adds a
6+
provider-agnostic API for user attributes. End users perform the regular OAuth 2.0 flow
7+
and the response includes a JWT signed by the identity provider with [standard
8+
claims][oidc-claims] for a stable identifier, email, display name, and other
9+
attributes.
10+
11+
```json
12+
{
13+
"sub": "12345abcd",
14+
"email": "janedoe@example.com",
15+
"email_verified": true,
16+
"name": "Jane Doe"
17+
}
1818
```
1919

20-
And the return type of `NewRemoteKeySet()` is now `*RemoteKeySet` instead of an interface ([#262](https://github.com/coreos/go-oidc/pull/262)).
20+
[oidc-claims]: https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims
21+
22+
This package can be used to identify users (and even [workload identities][github-workload])
23+
across a large number of identity providers:
24+
25+
- Consumer
26+
- [Google](https://developers.google.com/identity/openid-connect/openid-connect)
27+
- [Apple (Sign in with Apple)](https://developer.apple.com/sign-in-with-apple/)
28+
- [Microsoft](https://learn.microsoft.com/en-us/entra/identity-platform/v2-protocols-oidc)
29+
- [Facebook Login](https://developers.facebook.com/docs/facebook-login/)
30+
- [LinkedIn](https://learn.microsoft.com/en-us/linkedin/consumer/integrations/self-serve/sign-in-with-linkedin-v2)
31+
- Enterprise
32+
- [Microsoft Entra ID](https://learn.microsoft.com/en-us/entra/identity-platform/v2-protocols-oidc)
33+
- [Okta](https://developer.okta.com/docs/concepts/oauth-openid/)
34+
- [Auth0](https://auth0.com/docs/authenticate/protocols/openid-connect-protocol)
35+
- [Amazon Cognito](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-oidc-idp.html)
36+
- [OneLogin](https://developers.onelogin.com/openid-connect)
37+
- Workload
38+
- [GitHub Actions](https://docs.github.com/en/actions/concepts/security/openid-connect)
39+
- [GitLab CI/CD (ID tokens)](https://docs.gitlab.com/ci/cloud_services/)
40+
- [Google Cloud Workload Identity Federation](https://cloud.google.com/iam/docs/workload-identity-federation)
41+
- [AWS (IAM OIDC identity providers)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc.html)
42+
- [Kubernetes (service account / OIDC tokens)](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#openid-connect-tokens)
43+
- [HashiCorp HCP Terraform](https://developer.hashicorp.com/terraform/cloud-docs/workspaces/dynamic-provider-credentials/workload-identity-tokens)
44+
45+
[github-workload]: https://oblique.security/blog/github-actions-identity/
46+
47+
go-oidc is a mature OpenID Connect client, and is imported by [over 1000][go-oidc-imports]
48+
open source projects.
49+
50+
[go-oidc-imports]: https://pkg.go.dev/github.com/coreos/go-oidc/v3/oidc?tab=importedby
2151

2252
## OpenID Connect support for Go
2353

24-
This package enables OpenID Connect support for the [golang.org/x/oauth2](https://godoc.org/golang.org/x/oauth2) package.
54+
This package enables OpenID Connect support for the [golang.org/x/oauth2][go-oauth2-doc] package.
55+
The client can be initialized through OpenID Connect discovery with the issuer
56+
URL and a few additional scopes on the `oauth2.Config`.
57+
58+
[go-oauth2-doc]: https://pkg.go.dev/golang.org/x/oauth2
2559

2660
```go
2761
provider, err := oidc.NewProvider(ctx, "https://accounts.google.com")
@@ -41,6 +75,9 @@ oauth2Config := oauth2.Config{
4175
// "openid" is a required scope for OpenID Connect flows.
4276
Scopes: []string{oidc.ScopeOpenID, "profile", "email"},
4377
}
78+
79+
// Create an ID Token verifier.
80+
idTokenVerifier := provider.Verifier(&oidc.Config{ClientID: clientID})
4481
```
4582

4683
OAuth2 redirects are unchanged.
@@ -51,11 +88,9 @@ func handleRedirect(w http.ResponseWriter, r *http.Request) {
5188
}
5289
```
5390

54-
The on responses, the provider can be used to verify ID Tokens.
91+
Then, on the response, the ID Token verifier can be used to verify ID Tokens.
5592

5693
```go
57-
var verifier = provider.Verifier(&oidc.Config{ClientID: clientID})
58-
5994
func handleOAuth2Callback(w http.ResponseWriter, r *http.Request) {
6095
// Verify state and errors.
6196

@@ -71,15 +106,17 @@ func handleOAuth2Callback(w http.ResponseWriter, r *http.Request) {
71106
}
72107

73108
// Parse and verify ID Token payload.
74-
idToken, err := verifier.Verify(ctx, rawIDToken)
109+
idToken, err := idTokenVerifier.Verify(ctx, rawIDToken)
75110
if err != nil {
76111
// handle error
77112
}
78113

79114
// Extract custom claims
80115
var claims struct {
81-
Email string `json:"email"`
82-
Verified bool `json:"email_verified"`
116+
Email string `json:"email"`
117+
EmailVerified bool `json:"email_verified"`
118+
Name string `json:"name"`
119+
Picture string `json:"picture"`
83120
}
84121
if err := idToken.Claims(&claims); err != nil {
85122
// handle error

‎oidc/doc.go‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,65 @@
11
// Package oidc implements OpenID Connect client logic for the golang.org/x/oauth2 package.
2+
//
3+
// Construct a [Provider] and [oauth2.Config] through the identity provider's
4+
// discovery document with [NewProvider], and construct an ID Token verifier
5+
// with [Provider.Verifier]:
6+
//
7+
// provider, err := oidc.NewProvider(ctx, "https://accounts.google.com")
8+
// if err != nil {
9+
// // handle error
10+
// }
11+
//
12+
// // Configure an OpenID Connect aware OAuth2 client.
13+
// oauth2Config := oauth2.Config{
14+
// ClientID: clientID,
15+
// ClientSecret: clientSecret,
16+
// RedirectURL: redirectURL,
17+
// // Discovery returns the OAuth2 endpoints.
18+
// Endpoint: provider.Endpoint(),
19+
// // "openid" is a required scope for OpenID Connect flows.
20+
// Scopes: []string{oidc.ScopeOpenID, "profile", "email"},
21+
// }
22+
//
23+
// idTokenVerifier := provider.Verifier(&oidc.Config{ClientID: clientID})
24+
//
25+
// OAuth 2.0 redirects then opt into the OpenID Connect flow with [ScopeOpenID]:
26+
//
27+
// func handleRedirect(w http.ResponseWriter, r *http.Request) {
28+
// http.Redirect(w, r, oauth2Config.AuthCodeURL(state), http.StatusFound)
29+
// }
30+
//
31+
// When handling an OAuth 2.0 response, an [IDTokenVerifier] can be used to
32+
// validate the "id_token" payload, containing well-known fields such as the
33+
// user's email, name, and picture URL:
34+
//
35+
// func handleOAuth2Callback(w http.ResponseWriter, r *http.Request) {
36+
// // Verify state and other OAuth 2.0 responses.
37+
//
38+
// // Perform standard token exchange.
39+
// oauth2Token, err := oauth2Config.Exchange(r.Context(), r.URL.Query().Get("code"))
40+
// if err != nil {
41+
// // ...
42+
// }
43+
// // Extract the ID Token from OAuth2 token.
44+
// rawIDToken, ok := oauth2Token.Extra("id_token").(string)
45+
// if !ok {
46+
// // ...
47+
// }
48+
// // Parse and verify ID Token payload.
49+
// idToken, err := idTokenVerifier.Verify(r.Context(), rawIDToken)
50+
// if err != nil {
51+
// // ...
52+
// }
53+
// // Parse well-known claims from the token.
54+
// // https://openid.net/specs/openid-connect-core-1_0.html#Claims
55+
// var claims struct {
56+
// Email string `json:"email"`
57+
// EmailVerified bool `json:"email_verified"`
58+
// Name string `json:"name"`
59+
// Picture string `json:"picture"`
60+
// }
61+
// if err := idToken.Claims(&claims); err != nil {
62+
// // ...
63+
// }
64+
// }
265
package oidc

0 commit comments

Comments
 (0)