jwtverifier

README

AuthOne JWT verifier for Go

Overview

This component contains helper methods for working with authentication in ProtocolOne projects. Also, based on these methods, middleware is implemented to verify authentication in the Echo framework.

Installation

go get -u github.com/ProtocolONE/authone-jwt-verifier-golang

Usage

The complete example of usage can be found in the demo application located in the example directory. This library was built to simplify authorization process and converting opaque oauth2 access tokens to Jwt tokens and manage they lifecycle. To get it running at its most basic form, all you need to provide is the the following information:

• Client ID - The unique ID of application in the AuthOne Developer Console.
• RedirectURL - The authorization server will redirect the user back to the application with either an authorization code or access token in the URL.
• Issuer - the AuthOne authorization server to manage introspection, authorization, revoke and get user info operations.

Documentation

Index

• type AuthUrlOption
• type Config
• type IdToken
• type IntrospectToken
• type JwtVerifier
  • func NewJwtVerifier(config Config, options ...interface{}) *JwtVerifier
  • func (j *JwtVerifier) CreateAuthUrl(state string, options ...AuthUrlOption) string
  • func (j *JwtVerifier) CreateLogoutUrl(url string) string
  • func (j *JwtVerifier) Exchange(ctx context.Context, code string) (*Token, error)
  • func (j *JwtVerifier) GetUserInfo(ctx context.Context, token string) (*UserInfo, error)
  • func (j *JwtVerifier) Introspect(ctx context.Context, token string) (*IntrospectToken, error)
  • func (j *JwtVerifier) Revoke(ctx context.Context, token string) error
  • func (j *JwtVerifier) SetStorage(a storage.Adapter)
  • func (j *JwtVerifier) ValidateIdToken(ctx context.Context, token string) (*IdToken, error)
• type RetrieveError
  • func (r *RetrieveError) Error() string
• type Token
• type UserInfo

Types

type AuthUrlOption

type AuthUrlOption struct {
	// Key defines key for oauth2 url option
	Key string

	// Value defines value for oauth2 url option
	Value string
}

AuthUrlOption contains an additional option for authentication form URL.

type Config

type Config struct {
	// ClientID is the application's ID.
	ClientID string

	// ClientSecret is the application's secret.
	ClientSecret string

	// RedirectURL is the URL to redirect users going through
	// the OAuth flow, after the resource owner's URLs.
	RedirectURL string

	// Scope specifies optional requested permissions.
	Scopes []string

	// Issuer is the domain where ProtocolOne authorization server is located.
	// Without a slash at the end of the line, this is important.
	Issuer string
	// contains filtered or unexported fields
}

Config describes a typical 3-legged OpenId Connect flow, with both the client application information and the server's endpoint URLs.

type IdToken

type IdToken struct {
	AtHash   string   `json:"at_hash"`
	Aud      []string `json:"aud"`
	AuthTime int      `json:"auth_time"`
	Exp      int64    `json:"exp"`
	Iat      int      `json:"iat"`
	Iss      string   `json:"iss"`
	Jti      string   `json:"jti"`
	Nonce    string   `json:"nonce"`
	Rat      int      `json:"rat"`
	Sub      string   `json:"sub"`
}

IdToken based at JWT claims.

See more at: - https://www.iana.org/assignments/jwt/jwt.xhtml

type IntrospectToken

type IntrospectToken struct {
	// Active is a boolean indicator of whether or not the presented token is currently active.
	// The specifics of a token's \"active\" state will vary depending on the implementation of the authorization server
	// and the information it keeps about its tokens, but a \"true\" value return for the \"active\" property will
	// generally indicate that a given token has been issued by this authorization server, has not been revoked by the
	// resource owner, and is within its given time window of validity (e.g., after its issuance time and before its
	// expiration time).
	Active bool `json:"active"`

	// Audience contains a list of the token's intended audiences.
	Aud []string `json:"aud,omitempty"`

	// ClientID is aclient identifier for the OAuth 2.0 client that requested this token.
	ClientID string `json:"client_id"`

	// Expires at is an integer timestamp, measured in the number of seconds since January 1 1970 UTC,
	// indicating when this token will expire.
	Exp int64 `json:"exp,omitempty"`

	// Extra is arbitrary data set by the session.
	Ext map[string]interface{} `json:"ext,omitempty"`

	// Issued at is an integer timestamp, measured in the number of seconds since January 1 1970 UTC, indicating when
	// this token was originally issued.
	Iat int `json:"iat,omitempty"`

	// IssuerURL is a string representing the issuer of this token
	Iss string `json:"iss,omitempty"`

	// NotBefore is an integer timestamp, measured in the number of seconds since January 1 1970 UTC, indicating when
	// this token is not to be used before.
	Nbf int `json:"nbf,omitempty"`

	// Scope is a JSON string containing a space-separated list of scopes associated with this token.
	Scope string `json:"scope"`

	// Subject of the token, as defined in JWT [RFC7519]. Usually a machine-readable identifier of the resource owner
	// who authorized this token.
	Sub string `json:"sub"`

	// TokenType is the introspected token's type, for example `access_token` or `refresh_token`.
	TokenType string `json:"token_type"`

	// Username is a human-readable identifier for the resource owner who authorized this token.
	Username string `json:"username,omitempty"`
}

IntrospectToken repeats the structure of the Introspect Token object described in the Hydra documentation.

See more at: - https://www.ory.sh/docs/hydra/sdk/api#schemaoauth2tokenintrospection - https://www.iana.org/assignments/jwt/jwt.xhtml

type JwtVerifier

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

JwtVerifier used to interact with AuthOne authorization server.

func NewJwtVerifier

func NewJwtVerifier(config Config, options ...interface{}) *JwtVerifier

NewJwtVerifier create new instance of verifier with given configuration.

func (*JwtVerifier) CreateAuthUrl

func (j *JwtVerifier) CreateAuthUrl(state string, options ...AuthUrlOption) string

CreateAuthUrl create an URL to send the user to the initial authentication step.

func (*JwtVerifier) CreateLogoutUrl

func (j *JwtVerifier) CreateLogoutUrl(url string) string

CreateLogoutUrl create an URL to send the user to the logging out step with return back to the url.

func (*JwtVerifier) Exchange

func (j *JwtVerifier) Exchange(ctx context.Context, code string) (*Token, error)

Exchange converts an authorization code into a token.

It is used after a resource provider redirects the user back to the Redirect URI (the URL obtained from AuthCodeURL).

The provided context optionally controls which HTTP client is used. See the HTTPClient variable.

The code will be in the *http.Request.FormValue("code"). Before calling Exchange, be sure to validate FormValue("state").

Opts may include the PKCE verifier code if previously used in AuthCodeURL. See https://www.oauth.com/oauth2-servers/pkce/ for more info.

func (*JwtVerifier) GetUserInfo

func (j *JwtVerifier) GetUserInfo(ctx context.Context, token string) (*UserInfo, error)

GetUserInfo via UserInfo endpoint with uses AccessToken by authenticate header. The claims are packaged in a JSON object where the sub member denotes the subject (end-user) identifier.

func (*JwtVerifier) Introspect

func (j *JwtVerifier) Introspect(ctx context.Context, token string) (*IntrospectToken, error)

Introspect check the token refresh or access is active or not. An active token is neither expired nor revoked. Uses token storage for temporary storage of tokens. If the token has expired or it has been revoked, the information will be deleted from the temporary storage.

func (*JwtVerifier) Revoke

func (j *JwtVerifier) Revoke(ctx context.Context, token string) error

Revoke used to invalidate the specified token and, if applicable, other tokens based on the same authorisation grant.

func (*JwtVerifier) SetStorage

func (j *JwtVerifier) SetStorage(a storage.Adapter)

SetStorage allow to set adapter for the introspection token. See available adapters in the storage folder.

func (*JwtVerifier) ValidateIdToken

func (j *JwtVerifier) ValidateIdToken(ctx context.Context, token string) (*IdToken, error)

ValidateIdToken used to check the ID Token and returns its claims (as custom json object) in the event of its validity.

type RetrieveError

type RetrieveError struct {
	Response *http.Response
	Body     []byte
}

RetrieveError defined the structure of the error response to the oauth server

func (*RetrieveError) Error

func (r *RetrieveError) Error() string

type Token

type Token struct {
	*oauth2.Token
}

Token defined structure of oauth2.Token

type UserInfo

type UserInfo struct {
	UserID        string `json:"sub"`
	Email         string `json:"email"`
	EmailVerified bool   `json:"email_verified"`
	PhoneNumber   string `json:"phone_number"`
	PhoneVerified bool   `json:"phone_number_verified"`
	Name          string `json:"name"`
	Picture       string `json:"picture"`
}

UserInfo based at JWT claims.

See more at: - https://www.iana.org/assignments/jwt/jwt.xhtml