README.md
1# go-oidc
2
3[![GoDoc](https://godoc.org/github.com/coreos/go-oidc?status.svg)](https://godoc.org/github.com/coreos/go-oidc)
4[![Build Status](https://travis-ci.org/coreos/go-oidc.png?branch=master)](https://travis-ci.org/coreos/go-oidc)
5
6## OpenID Connect support for Go
7
8This package enables OpenID Connect support for the [golang.org/x/oauth2](https://godoc.org/golang.org/x/oauth2) package.
9
10```go
11provider, err := oidc.NewProvider(ctx, "https://accounts.google.com")
12if err != nil {
13 // handle error
14}
15
16// Configure an OpenID Connect aware OAuth2 client.
17oauth2Config := oauth2.Config{
18 ClientID: clientID,
19 ClientSecret: clientSecret,
20 RedirectURL: redirectURL,
21
22 // Discovery returns the OAuth2 endpoints.
23 Endpoint: provider.Endpoint(),
24
25 // "openid" is a required scope for OpenID Connect flows.
26 Scopes: []string{oidc.ScopeOpenID, "profile", "email"},
27}
28```
29
30OAuth2 redirects are unchanged.
31
32```go
33func handleRedirect(w http.ResponseWriter, r *http.Request) {
34 http.Redirect(w, r, oauth2Config.AuthCodeURL(state), http.StatusFound)
35}
36```
37
38The on responses, the provider can be used to verify ID Tokens.
39
40```go
41var verifier = provider.Verifier(&oidc.Config{ClientID: clientID})
42
43func handleOAuth2Callback(w http.ResponseWriter, r *http.Request) {
44 // Verify state and errors.
45
46 oauth2Token, err := oauth2Config.Exchange(ctx, r.URL.Query().Get("code"))
47 if err != nil {
48 // handle error
49 }
50
51 // Extract the ID Token from OAuth2 token.
52 rawIDToken, ok := oauth2Token.Extra("id_token").(string)
53 if !ok {
54 // handle missing token
55 }
56
57 // Parse and verify ID Token payload.
58 idToken, err := verifier.Verify(ctx, rawIDToken)
59 if err != nil {
60 // handle error
61 }
62
63 // Extract custom claims
64 var claims struct {
65 Email string `json:"email"`
66 Verified bool `json:"email_verified"`
67 }
68 if err := idToken.Claims(&claims); err != nil {
69 // handle error
70 }
71}
72```
73