1# Okta JWT Verifier for Golang
2
3This library helps you verify tokens that have been issued by Okta. To learn more about verification cases and Okta's tokens please read [Working With OAuth 2.0 Tokens](https://developer.okta.com/authentication-guide/tokens/)
4
5## Release status
6
7This library uses semantic versioning and follows Okta's [library version policy](https://developer.okta.com/code/library-versions/).
8
9| Version | Status |
10| ------- | -------------------------------- |
11| 0.x | :warning: Beta Release (Retired) |
12| 1.x | :heavy_check_mark: Release |
13
14## Installation
15
16```sh
17go get -u github.com/okta/okta-jwt-verifier-golang
18```
19
20## Usage
21
22This library was built to keep configuration to a minimum. To get it running at its most basic form, all you need to provide is the the following information:
23
24- **Issuer** - This is the URL of the authorization server that will perform authentication. All Developer Accounts have a "default" authorization server. The issuer is a combination of your Org URL (found in the upper right of the console home page) and `/oauth2/default`. For example, `https://dev-1234.oktapreview.com/oauth2/default`.
25- **Client ID**- These can be found on the "General" tab of the Web application that you created earlier in the Okta Developer Console.
26
27#### Access Token Validation
28
29```go
30import "github.com/okta/okta-jwt-verifier-golang"
31
32toValidate := map[string]string{}
33toValidate["aud"] = "api://default"
34toValidate["cid"] = "{CLIENT_ID}"
35
36jwtVerifierSetup := jwtverifier.JwtVerifier{
37 Issuer: "{ISSUER}",
38 ClaimsToValidate: toValidate,
39}
40
41verifier := jwtVerifierSetup.New()
42
43token, err := verifier.VerifyAccessToken("{JWT}")
44```
45
46#### Id Token Validation
47
48```go
49import "github.com/okta/okta-jwt-verifier-golang"
50
51toValidate := map[string]string{}
52toValidate["nonce"] = "{NONCE}"
53toValidate["aud"] = "{CLIENT_ID}"
54
55
56jwtVerifierSetup := jwtverifier.JwtVerifier{
57 Issuer: "{ISSUER}",
58 ClaimsToValidate: toValidate,
59}
60
61verifier := jwtVerifierSetup.New()
62
63token, err := verifier.VerifyIdToken("{JWT}")
64```
65
66This will either provide you with the token which gives you access to all the claims, or an error. The token struct contains a `Claims` property that will give you a `map[string]interface{}` of all the claims in the token.
67
68```go
69// Getting the sub from the token
70sub := token.Claims["sub"]
71```
72
73#### Dealing with clock skew
74
75We default to a two minute clock skew adjustment in our validation. If you need to change this, you can use the `SetLeeway` method:
76
77```go
78jwtVerifierSetup := JwtVerifier{
79 Issuer: "{ISSUER}",
80}
81
82verifier := jwtVerifierSetup.New()
83verifier.SetLeeway("2m") //String instance of time that will be parsed by `time.ParseDuration`
84```
85
86#### Customizable Resource Cache
87
88The verifier setup has a default cache based on
89[`patrickmn/go-cache`](https://github.com/patrickmn/go-cache) with a 5 minute
90expiry and 10 minute purge setting that is used to store resources fetched over
91HTTP. It also defines a `Cacher` interface with a `Get` method allowing
92customization of that caching. If you want to establish your own caching
93strategy then provide your own `Cacher` object that implements that interface.
94Your custom cache is set in the verifier via the `Cache` attribute. See the
95example in the [cache example test](utils/cache_example_test.go) that shows a
96"forever" cache (that one would never use in production ...)
97
98```go
99jwtVerifierSetup := jwtverifier.JwtVerifier{
100 Cache: NewForeverCache,
101 // other fields here
102}
103
104verifier := jwtVerifierSetup.New()
105```
106
107#### Utilities
108
109The below utilities are available in this package that can be used for Authentication flows
110
111**Nonce Generator**
112
113```go
114import jwtUtils "github.com/okta/okta-jwt-verifier-golang/utils"
115
116nonce, err := jwtUtils.GenerateNonce()
117```
118
119**PKCE Code Verifier and Challenge Generator**
120
121```go
122import jwtUtils "github.com/okta/okta-jwt-verifier-golang/utils"
123
124codeVerifier, err := jwtUtils.GenerateCodeVerifier()
125// or
126codeVerifier, err := jwtUtils.GenerateCodeVerifierWithLength(50)
127
128// get string value for oauth2 code verifier
129codeVerifierValue := codeVerifier.String()
130
131// get plain text code challenge from verifier
132codeChallengePlain := codeVerifier.CodeChallengePlain()
133codeChallengeMethod := "plain"
134// get sha256 code challenge from verifier
135codeChallengeS256 := codeVerifier.CodeChallengeS256()
136codeChallengeMethod := "S256"
137```
138
139## Testing
140
141If you create a PR from a fork of okta/okta-jwt-verifier-golang the build for
142the PR will fail. Don't worry, we'll bring your commits into a review branch in
143okta/okta-jwt-verifier-golang and get a green build.
144
145jwtverifier_test.go expects environment variables for `ISSUER`, `CLIENT_ID`,
146`USERNAME`, and `PASSWORD` to be present. Take note if you use zshell as
147`USERSNAME` is a special environment variable and is not settable. Therefore
148tests shouldn't be run in zshell.
149
150`USERNAME` and `PASSWORD` are for a user with access to the test app associated
151with `CLIENT_ID`. The test app should not have 2FA enabled and allow password
152login. The General Settings for the test app should have Application Grant type
153with Implicit (hybrid) enabled.
154
155```
156go test -test.v
157```
View as plain text