fosite/HISTORY.md
THIS DOCUMENT HAS MOVED
This file is no longer being updated and kept for historical reasons. Please check the CHANGELOG instead!
<!-- START doctoc generated TOC please keep comment here to allow auto update --> <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->fosite/handler/oauth2.AuthorizeCodeGrantStorage was removedfosite/handler/oauth2.RefreshTokenGrantStorage was removedfosite/handler/oauth2.AuthorizeCodeGrantStorage was removedThis version (re-)introduces refresh token lifespans. Per default, this feature is enabled and set to 30 days. If a refresh token has not been used within 30 days, it will expire.
To disable refresh token lifespans (previous behaviour), set
compose.Config.RefreshTokenLifespan = -1.
This PR adds the ability to specify a target audience for OAuth 2.0 Access Tokens.
From now on, scope and audience will be checked against the client's
whitelisted scope and audience on every refresh token exchange. This prevents
clients, which no longer are allowed to request a certain audience or scope, to
keep using those values with existing refresh tokens.
type fosite.Client interface {
+ // GetAudience returns the allowed audience(s) for this client.
+ GetAudience() Arguments
}
type fosite.Request struct {
- Scopes Argument
+ RequestedScope Argument
- GrantedScopes Argument
+ GrantedScope Argument
}
type fosite.Requester interface {
+ // GetRequestedAudience returns the requested audiences for this request.
+ GetRequestedAudience() (audience Arguments)
+ // SetRequestedAudience sets the requested audienc.
+ SetRequestedAudience(audience Arguments)
+ // GetGrantedAudience returns all granted scopes.
+ GetGrantedAudience() (grantedAudience Arguments)
+ // GrantAudience marks a request's audience as granted.
+ GrantAudience(audience string)
}
type fosite/token/jwt.JWTClaimsContainer interface {
- // With returns a copy of itself with expiresAt and scope set to the given values.
- With(expiry time.Time, scope, audience []string) JWTClaimsContainer
+ // With returns a copy of itself with expiresAt, scope, audience set to the given values.
+ With(expiry time.Time, scope, audience []string) JWTClaimsContainer
}
This release makes it easier to define custom JWT Containers for access tokens when using the JWT strategy. To do that, the following signatures have changed:
// github.com/ory/fosite/handler/oauth2
type JWTSessionContainer interface {
// GetJWTClaims returns the claims.
- GetJWTClaims() *jwt.JWTClaims
+ GetJWTClaims() jwt.JWTClaimsContainer
// GetJWTHeader returns the header.
GetJWTHeader() *jwt.Headers
fosite.Session
}
+ type JWTClaimsContainer interface {
+ // With returns a copy of itself with expiresAt and scope set to the given values.
+ With(expiry time.Time, scope []string) JWTClaimsContainer
+
+ // WithDefaults returns a copy of itself with issuedAt and issuer set to the given default values. If those
+ // values are already set in the claims, they will not be updated.
+ WithDefaults(iat time.Time, issuer string) JWTClaimsContainer
+
+ // ToMapClaims returns the claims as a github.com/dgrijalva/jwt-go.MapClaims type.
+ ToMapClaims() jwt.MapClaims
+ }
All default session implementations have been updated to reflect this change. If you define custom session, this patch will affect you.
This release addresses areas where the go context was missing or not propagated down the call path properly.
fosite/handler/oauth2.JWTStrategyThe
fosite/handler/oauth2.JWTStrategy
interface changed as a context parameter was added to its method signature:
type JWTStrategy interface {
- Validate(tokenType fosite.TokenType, token string) (requester fosite.Requester, err error)
+ Validate(ctx context.Context, tokenType fosite.TokenType, token string) (requester fosite.Requester, err error)
}
OpenIDConnectRequestValidator.ValidatePromptThe
OpenIDConnectRequestValidator.ValidatePrompt
method signature was updated to take a go context as its first parameter:
- func (v *OpenIDConnectRequestValidator) ValidatePrompt(req fosite.AuthorizeRequester) error {
+ func (v *OpenIDConnectRequestValidator) ValidatePrompt(ctx context.Context, req fosite.AuthorizeRequester) error {
This releases addresses inconsistencies in some of the public interfaces by passing in the go context to their signatures.
HasherThe Hasher interface
changed as a context parameter was added to its method signatures:
type Hasher interface {
- Compare(hash, data []byte) error
+ Compare(ctx context.Context, hash, data []byte) error
- Hash(data []byte) ([]byte, error)
+ Hash(ctx context.Context, data []byte) ([]byte, error)
}
This releases addresses inconsistencies in some of the public interfaces by passing in the go context to their signatures.
JWTStrategyThe JWTStrategy
interface changed as a context parameter was added to its method signatures:
type JWTStrategy interface {
- Generate(claims jwt.Claims, header Mapper) (string, string, error)
+ Generate(ctx context.Context, claims jwt.Claims, header Mapper) (string, string, error)
- Validate(token string) (string, error)
+ Validate(ctx context.Context, token string) (string, error)
- GetSignature(token string) (string, error)
+ GetSignature(ctx context.Context, token string) (string, error)
- Hash(in []byte) ([]byte, error)
+ Hash(ctx context.Context, in []byte) ([]byte, error)
- Decode(token string) (*jwt.Token, error)
+ Decode(ctx context.Context, token string) (*jwt.Token, error)
GetSigningMethodLength() int
}
This release improves compatibility with the OpenID Connect Dynamic Client Registration 1.0 specification.
response_typesPreviously, when response types such as code token id_token were requested
(OpenID Connect Hybrid Flow) it was enough for the client to have
response_types=["code", "token", "id_token"]. This is however incompatible
with the OpenID Connect Dynamic Client Registration 1.0 spec which dictates that
the response_types have to match exactly.
Assuming you are requesting &response_types=code+token+id_token, your client
should have response_types=["code token id_token"], if other response types
are required (e.g. &response_types=code, &response_types=token) they too
must be included: response_types=["code", "token", "code token id_token"].
openid.DefaultStrategy field name changedField RS256JWTStrategy was renamed to JWTStrategy and now relies on an
interface instead of a concrete struct.
oauth2.RS256JWTStrategy was renamed and field name changedThe strategy oauth2.RS256JWTStrategy was renamed to
oauth2.DefaultJWTStrategy and now accepts an interface that implements
jwt.JWTStrategy instead of directly relying on jwt.RS256JWTStrategy. For
this reason, the field RS256JWTStrategy was renamed to JWTStrategy
private_key_jwt client authentication methodThis patch adds the ability to perform the
private_key_jwt client authentication method
defined in the OpenID Connect specification. Please note that method
client_secret_jwt is not supported because of the BCrypt hashing strategy.
For this strategy to work, you must set the TokenURL field of the
compose.Config object to the authorization server's Token URL.
If you would like to support this authentication method, your Client
implementation must also implement fosite.DefaultOpenIDConnectClient and then,
for example, GetTokenEndpointAuthMethod() should return private_key_jwt.
id_token no longer required for authorize_code flowThe authorize_code
does not require
the id_token response type to be available when performing the OpenID Connect
flow:
grant_types OPTIONAL. JSON array containing a list of the OAuth 2.0 Grant Types that the Client is declaring that it will restrict itself to using. The Grant Type values used by OpenID Connect are:
authorization_code: The Authorization Code Grant Type described in OAuth 2.0 Section 4.1. implicit: The Implicit Grant Type described in OAuth 2.0 Section 4.2. refresh_token: The Refresh Token Grant Type described in OAuth 2.0 Section 6. The following table lists the correspondence between response_type values that the Client will use and grant_type values that MUST be included in the registered grant_types list: code: authorization_code id_token: implicit token id_token: implicit code id_token: authorization_code, implicit code token: authorization_code, implicit code token id_token: authorization_code, implicit If omitted, the default is that the Client will use only the authorization_code Grant Type.
Before this patch, the id_token response type was required whenever an ID
Token was requested. This patch changes that.
This release implements an OAuth 2.0 Best Practice with regards to revoking already issued access and refresh tokens if an authorization code is used more than one time.
github.com/ory/fosite/token/jwt.JWTClaims.Audience is no longer a string,
but a string slice []string.github.com/ory/fosite/handler/openid.IDTokenClaims is no longer a string,
but a string slice []string.AuthorizeCodeStorageThis improves security as, in the event of an authorization code being leaked,
all associated tokens are revoked. To implement this feature, a breaking change
had to be introduced. The
github.com/ory/fosite/handler/oauth2.AuthorizeCodeStorage interface changed as
follows:
DeleteAuthorizeCodeSession(ctx context.Context, code string) (err error) has
been removed from the interface and is no longer used by this library.InvalidateAuthorizeCodeSession(ctx context.Context, code string) (err error)
has been introduced.github.com/ory/fosite/handler/oauth2.ErrInvalidatedAuthorizeCode
has been added.The following documentation sheds light on how you should update your storage adapter:
// ErrInvalidatedAuthorizeCode is an error indicating that an authorization code has been
// used previously.
var ErrInvalidatedAuthorizeCode = errors.New("Authorization code has ben invalidated")
// AuthorizeCodeStorage handles storage requests related to authorization codes.
type AuthorizeCodeStorage interface {
// GetAuthorizeCodeSession stores the authorization request for a given authorization code.
CreateAuthorizeCodeSession(ctx context.Context, code string, request fosite.Requester) (err error)
// GetAuthorizeCodeSession hydrates the session based on the given code and returns the authorization request.
// If the authorization code has been invalidated with `InvalidateAuthorizeCodeSession`, this
// method should return the ErrInvalidatedAuthorizeCode error.
//
// Make sure to also return the fosite.Requester value when returning the ErrInvalidatedAuthorizeCode error!
GetAuthorizeCodeSession(ctx context.Context, code string, session fosite.Session) (request fosite.Requester, err error)
// InvalidateAuthorizeCodeSession is called when an authorize code is being used. The state of the authorization
// code should be set to invalid and consecutive requests to GetAuthorizeCodeSession should return the
// ErrInvalidatedAuthorizeCode error.
InvalidateAuthorizeCodeSession(ctx context.Context, code string) (err error)
}
This release improves the OpenID Connect vaildation strategy which now properly
handles prompt, max_age, and id_token_hint at the /oauth2/auth endpoint
instead of the /oauth2/token endpoint.
To achieve this, the OpenIDConnectRequestValidator has been modified and now
requires a jwt.JWTStrategy (implemented by, for example
jwt.RS256JWTStrategy).
The compose package has been updated accordingly. You should not expect any major breaking changes from this release.
This release allows the introspection handler to return the token type (e.g.
access_token, refresh_token) of the introspected token. To achieve that,
some breaking API changes have been introduced:
OAuth2.IntrospectToken(ctx context.Context, token string, tokenType TokenType, session Session, scope ...string) (AccessRequester, error)
is now
OAuth2.IntrospectToken(ctx context.Context, token string, tokenType TokenType, session Session, scope ...string) (TokenType, AccessRequester, error).TokenIntrospector.IntrospectToken(ctx context.Context, token string, tokenType TokenType, accessRequest AccessRequester, scopes []string) (error)
is now
TokenIntrospector.IntrospectToken(ctx context.Context, token string, tokenType TokenType, accessRequest AccessRequester, scopes []string) (TokenType, error).This patch also resolves a misconfigured json key in the IntrospectionResponse
struct. AccessRequester AccessRequester json:",extra" is now properly declared
as AccessRequester AccessRequester json:"extra".
This release resolves a security issue (reported by platform.sh) related to potential storage implementations. This library used to pass all of the request body from both authorize and token endpoints to the storage adapters. As some of these values are needed in consecutive requests, some storage adapters chose to drop the full body to the database.
This implied that confidential parameters, such as the client_secret which can
be passed in the request body since version 0.15.0, were stored as key/value
pairs in plaintext in the database. While most client secrets are generated
programmatically (as opposed to set by the user), it's a considerable security
issue nonetheless.
The issue has been resolved by sanitizing the request body and only including those values truly required by their respective handlers. This lead to two breaking changes in the API:
fosite.Requester interface has a new method
Sanitize(allowedParameters []string) Requester which returns a sanitized
clone of the method receiver. If you do not use your own fosite.Requester
implementation, this won't affect you.CreateAuthorizeCodeSession. A reference implementation can be found
in ./storage/memory.go. The method signatures are as
follows:type PKCERequestStorage interface {
GetPKCERequestSession(ctx context.Context, signature string, session fosite.Session) (fosite.Requester, error)
CreatePKCERequestSession(ctx context.Context, signature string, requester fosite.Requester) error
DeletePKCERequestSession(ctx context.Context, signature string) error
}
We encourage you to upgrade to this release and check your storage implementations and potentially remove old data.
We would like to thank platform.sh for sponsoring the development of a patch that resolves this issue.
This patch introduces SendDebugMessagesToClients to the Fosite struct which
enables/disables sending debug information to clients. Debug information may
contain sensitive information as it forwards error messages from, for example,
storage implementations. For this reason, RevealDebugPayloads defaults to
false. Keep in mind that the information may be very helpful when specific OAuth
2.0 requests fail and we generally recommend displaying debug information.
Additionally, error keys for JSON changed which caused a new minor version,
speicifically
statusCode was changed to status_code.
This release focuses on improving compatibility with OpenID Connect Certification and better error context.
/oauth2/token endpoint. Please
note that this method is not recommended to be used, unless the client making
the request is unable to use HTTP Basic Authorization./oauth2/token endpoint
which was previously only possible by adding an arbitrary secret.This release has no breaking changes to the external API but due to the nature of the changes, it is released as a new major version.
Improves error contexts. A breaking code changes to the public API was reverted with 0.14.1.
glide was replaced with dep.
To simplify the storage adapter logic, and also reduce the likelihoods of bugs within the storage adapter, the interface was greatly simplified. Specifically, these two methods have been removed:
PersistRefreshTokenGrantSession(ctx context.Context, requestRefreshSignature, accessSignature, refreshSignature string, request fosite.Requester) errorPersistAuthorizeCodeGrantSession(ctx context.Context, authorizeCode, accessSignature, refreshSignature string, request fosite.Requester) errorFor this change, you don't need to do anything. You can however simply delete those two methods from your store.
In the long term, fosite should remove all gomocks and instead test against the internal implementations. This will increase iterations per line during tests and reduce annoying mock updates.
fosite/handler/oauth2.AuthorizeCodeGrantStorage was removedAuthorizeCodeGrantStorage was used specifically in the composer. Refactor
references to AuthorizeCodeGrantStorage with CoreStorage.
fosite/handler/oauth2.RefreshTokenGrantStorage was removedRefreshTokenGrantStorage was used specifically in the composer. Refactor
references to RefreshTokenGrantStorage with CoreStorage.
fosite/handler/oauth2.AuthorizeCodeGrantStorage was removedAuthorizeCodeGrantStorage was used specifically in the composer. Refactor
references to AuthorizeCodeGrantStorage with CoreStorage.
A new scope strategy was introduced
called WildcardScopeStrategy. This strategy is now the default when using the
composer. To set the HierarchicScopeStrategy strategy, do:
import "github.com/ory/fosite/compose"
var config = &compose.Config{
ScopeStrategy: fosite.HierarchicScopeStrategy,
}
Using JWTs for refresh tokens and authorize codes did not make sense:
Also, one compose method changed due to this:
package compose
// ..
- func NewOAuth2JWTStrategy(key *rsa.PrivateKey) *oauth2.RS256JWTStrategy
+ func NewOAuth2JWTStrategy(key *rsa.PrivateKey, strategy *oauth2.HMACSHAStrategy) *oauth2.RS256JWTStrategy
Please delete access tokens in your store when you persist a refresh session. This increases security. Here is an example of how to do that using only existing methods:
func (s *MemoryStore) PersistRefreshTokenGrantSession(ctx context.Context, originalRefreshSignature, accessSignature, refreshSignature string, request fosite.Requester) error {
if ts, err := s.GetRefreshTokenSession(ctx, originalRefreshSignature, nil); err != nil {
return err
} else if err := s.RevokeAccessToken(ctx, ts.GetID()); err != nil {
return err
} else if err := s.RevokeRefreshToken(ctx, ts.GetID()); err != nil {
return err
} else if err := s.CreateAccessTokenSession(ctx, accessSignature, request); err != nil {
return err
} else if err := s.CreateRefreshTokenSession(ctx, refreshSignature, request); err != nil {
return err
}
return nil
}
It is no longer possible to introspect authorize codes, and passing scopes to the introspector now also checks refresh token scopes.
This patch adds the ability to pass a custom hasher to compose.Compose, which
is a breaking change. You can pass nil for the fosite default hasher:
package compose
-func Compose(config *Config, storage interface{}, strategy interface{}, factories ...Factory) fosite.OAuth2Provider {
+func Compose(config *Config, storage interface{}, strategy interface{}, hasher fosite.Hasher, factories ...Factory) fosite.OAuth2Provider {
This patch addresses some inconsistencies in the public interfaces. Also
remaining references to the old repository location at ory-am/fosite where
updated to ory/fosite.
ClientManagerThe
ClientManager
interface changed, as a context parameter was added:
type ClientManager interface {
// GetClient loads the client by its ID or returns an error
// if the client does not exist or another error occurred.
- GetClient(id string) (Client, error)
+ GetClient(ctx context.Context, id string) (Client, error)
}
OAuth2ProviderThe OAuth2Provider
interface changed, as the need for passing down *http.Request was removed.
This is justifiable because NewAuthorizeRequest and NewAccessRequest already
contain *http.Request.
The public api of those two methods changed:
- NewAuthorizeResponse(ctx context.Context, req *http.Request, requester AuthorizeRequester, session Session) (AuthorizeResponder, error)
+ NewAuthorizeResponse(ctx context.Context, requester AuthorizeRequester, session Session) (AuthorizeResponder, error)
- NewAccessResponse(ctx context.Context, req *http.Request, requester AccessRequester) (AccessResponder, error)
+ NewAccessResponse(ctx context.Context, requester AccessRequester) (AccessResponder, error)
Breaking changes:
"golang.org/x/net/context" with "context".github.com/ory-am/fosite to github.com/ory/fositeA bug related to refresh tokens was found. To mitigate it, a Clone() method
has been introduced to the fosite.Session interface. If you use a custom
session object, this will be a breaking change. Fosite's default sessions have
been upgraded and no additional work should be required. If you use your own
session struct, we encourage using package gob/encoding to deep-copy it in
Clone().
Breaking changes:
compose.OpenIDConnectExplicit is now compose.OpenIDConnectExplicitFactorycompose.OpenIDConnectImplicit is now compose.OpenIDConnectImplicitFactorycompose.OpenIDConnectHybrid is now compose.OpenIDConnectHybridFactorycompose.OAuth2*. Add compose.OAuth2TokenIntrospectionFactory to your
composer if you need token introspection.fosite.Session /
fosite.DefaultSession. All sessions must now implement this signature. The
new session interface allows for better expiration time handling.DefaultSession signature changed as well, it is now
implementing the fosite.Session interfaceBreaking changes:
./fosite-example is now a separate repository:
https://github.com/ory-am/fosite-examplegithub.com/ory-am/fosite/fosite-example/pkg.Store is now
github.com/ory-am/fosite/storage.MemoryStorefosite.Client has now a new method called IsPublic() which can be used to
identify public clients who do not own a client secretTokenValidator is now TokenIntrospector, TokenValidationHandlers is now
TokenIntrospectionHandlers.TokenValidator.ValidateToken is now TokenIntrospector.IntrospectTokenfosite.OAuth2Provider.NewIntrospectionRequest() has been addedfosite.OAuth2Provider.WriteIntrospectionError() has been addedfosite.OAuth2Provider.WriteIntrospectionResponse() has been addedBreaking changes:
ValidateRequestAuthorization is now Validate
and does not require a http request but instead a token and a token hint. A
token can be anything, including authorization codes, refresh tokens, id
tokens, ...fosite) has been removed as it
has proven impractical.scope instead of
granted_scopes when using the DefaultClient.core/client or oidc/explicit have been merged
and moved one level uphandler/oidc is now handler/openidhandler/core is now handler/oauth2Initial release