jwtverifier

README

Okta JWT Verifier for Golang

This 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

⚠ 🚧 Beta Preview 🚧 ⚠

This library is under development and is currently in 0.x version series. Breaking changes may be introduced at minor versions in the 0.x range. Please lock your dependency to a specific version until this library reaches 1.x.

Need help? Okta Developer Forum.

Installation

go get -u github.com/okta/okta-jwt-verifier-golang

Usage

This 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:

• 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.
• Client ID- These can be found on the "General" tab of the Web application that you created earlier in the Okta Developer Console.

Access Token Validation

import github.com/okta/okta-jwt-verifier-golang

toValidate := map[string]string{}
toValidate["aud"] = "api://default"
toValidate["cid"] = "{CLIENT_ID}"

jwtVerifierSetup := jwtverifier.JwtVerifier{
        Issuer: "{ISSUER}",
        ClaimsToValidate: toValidate
}

verifier := jwtVerifierSetup.New()

token, err := verifier.VerifyAccessToken("{JWT}")

Id Token Validation

import github.com/okta/okta-jwt-verifier-golang

toValidate := map[string]string{}
toValidate["nonce"] = "{NONCE}"
toValidate["aud"] = "{CLIENT_ID}"


jwtVerifierSetup := jwtverifier.JwtVerifier{
        Issuer: "{ISSUER}",
        ClaimsToValidate: toValidate
}

verifier := jwtVerifierSetup.New()

token, err := verifier.VerifyIdToken("{JWT}")

This 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.

// Getting the sub from the token
sub := token.Claims["sub"]

Dealing with clock skew

We default to a PT2M clock skew adjustment in our validation. If you need to change this, you can use the SetLeeway method:

jwtVerifierSetup := JwtVerifier{
        Issuer: "{ISSUER}",
}

verifier := jwtVerifierSetup.New()
verifier.SetLeeway(60) // seconds

Documentation

Index

• Variables
• func GenerateNonce() (string, error)
• func ParseEnvironment()
• type Adaptor
  • func NewJWXAdaptor(metaDataUrl string) (Adaptor, error)
• type ConfigFunc
  • func WithAdaptor(adaptor Adaptor) ConfigFunc
  • func WithDefaultLeeway(leeway int64) ConfigFunc
  • func WithDiscovery(discovery Discovery) ConfigFunc
• type Discovery
  • func NewOIDCDiscovery() Discovery
• type JWXAdaptor
  • func (a *JWXAdaptor) Decode(jwt string) (map[string]interface{}, error)
• type Jwt
• type JwtVerifier
  • func New(issuer string, configs ...ConfigFunc) (*JwtVerifier, error)
  • func (j *JwtVerifier) VerifyAccessToken(jwt string) (*Jwt, error)
  • func (j *JwtVerifier) VerifyAccessTokenWithOpts(jwt string, opts VerificationOpts) (*Jwt, error)
  • func (j *JwtVerifier) VerifyIdToken(jwt string) (*Jwt, error)
  • func (j *JwtVerifier) VerifyIdTokenWithOpts(jwt string, opts VerificationOpts) (*Jwt, error)
• type OIDC
  • func (d *OIDC) GetWellKnownUrl() string
• type VerificationOpts

Variables

var (
	ErrJWTEmptyString = errors.New("you must provide a jwt to verify")
	ErrJWKNotFound    = errors.New("jwk not found for kid")
)

Functions

func GenerateNonce

func GenerateNonce() (string, error)

func ParseEnvironment

func ParseEnvironment()

Types

type Adaptor

type Adaptor interface {
	Decode(jwt string) (map[string]interface{}, error)
}

func NewJWXAdaptor

func NewJWXAdaptor(metaDataUrl string) (Adaptor, error)

type ConfigFunc

type ConfigFunc = func(v *JwtVerifier)

func WithAdaptor

func WithAdaptor(adaptor Adaptor) ConfigFunc

func WithDefaultLeeway

func WithDefaultLeeway(leeway int64) ConfigFunc

func WithDiscovery

func WithDiscovery(discovery Discovery) ConfigFunc

type Discovery

type Discovery interface {
	GetWellKnownUrl() string
}

func NewOIDCDiscovery

func NewOIDCDiscovery() Discovery

type JWXAdaptor

type JWXAdaptor struct {
	// contains filtered or unexported fields
}

func (*JWXAdaptor) Decode

func (a *JWXAdaptor) Decode(jwt string) (map[string]interface{}, error)

type Jwt

type Jwt struct {
	Claims map[string]interface{}
}

type JwtVerifier

type JwtVerifier struct {
	// contains filtered or unexported fields
}

JwtVerifier verifies jwt tokens. It is thread safe and therefore you should always have one instance of the verifier per application. It is important to pass around a single instance to utilize RS256 key caching and the http thread pool for its client.

func New

func New(issuer string, configs ...ConfigFunc) (*JwtVerifier, error)

func (*JwtVerifier) VerifyAccessToken

func (j *JwtVerifier) VerifyAccessToken(jwt string) (*Jwt, error)

func (*JwtVerifier) VerifyAccessTokenWithOpts

func (j *JwtVerifier) VerifyAccessTokenWithOpts(jwt string, opts VerificationOpts) (*Jwt, error)

func (*JwtVerifier) VerifyIdToken

func (j *JwtVerifier) VerifyIdToken(jwt string) (*Jwt, error)

func (*JwtVerifier) VerifyIdTokenWithOpts

func (j *JwtVerifier) VerifyIdTokenWithOpts(jwt string, opts VerificationOpts) (*Jwt, error)

type OIDC

type OIDC struct {
	// contains filtered or unexported fields
}

func (*OIDC) GetWellKnownUrl

func (d *OIDC) GetWellKnownUrl() string

type VerificationOpts

type VerificationOpts struct {
	// Leeway is the leeway in seconds.
	Leeway *int64
	// Claims are the claims you want to validate on an individual token.
	Claims map[string]string
}