From 0b4d62c7458e31ec95c2f1bc96386b54866e33bf Mon Sep 17 00:00:00 2001 From: David Sharnoff Date: Fri, 5 Aug 2022 01:54:40 -0700 Subject: [PATCH] chore: add comments documenting Storage and AuthStorage (#193) * add comments documenting Storage and AuthStorage * JWTTokenRequest is a pointer * note that token strings are actually tokenIDs * review feedback * remove suggestion that CreateAccessToken could be called with retrun from AuthStorage.TokenRequestByRefreshToken --- pkg/op/storage.go | 31 +++++++++++++++++++++++++++---- 1 file changed, 27 insertions(+), 4 deletions(-) diff --git a/pkg/op/storage.go b/pkg/op/storage.go index 0cdffce..32905f1 100644 --- a/pkg/op/storage.go +++ b/pkg/op/storage.go @@ -16,12 +16,30 @@ type AuthStorage interface { SaveAuthCode(context.Context, string, string) error DeleteAuthRequest(context.Context, string) error - CreateAccessToken(context.Context, TokenRequest) (string, time.Time, error) - CreateAccessAndRefreshTokens(ctx context.Context, request TokenRequest, currentRefreshToken string) (accessTokenID string, newRefreshToken string, expiration time.Time, err error) - TokenRequestByRefreshToken(ctx context.Context, refreshToken string) (RefreshTokenRequest, error) + // The TokenRequest parameter of CreateAccessToken can be any of: + // + // * TokenRequest as returned by ClientCredentialsStorage.ClientCredentialsTokenRequest, + // + // * AuthRequest as returned by AuthRequestByID or AuthRequestByCode (above) + // + // * *oidc.JWTTokenRequest from a JWT that is the assertion value of a JWT Profile + // Grant: https://datatracker.ietf.org/doc/html/rfc7523#section-2.1 + CreateAccessToken(context.Context, TokenRequest) (accessTokenID string, expiration time.Time, err error) + + // The TokenRequest parameter of CreateAccessAndRefreshTokens can be any of: + // + // * TokenRequest as returned by ClientCredentialsStorage.ClientCredentialsTokenRequest + // + // * RefreshTokenRequest as returned by AuthStorage.TokenRequestByRefreshToken + // + // * AuthRequest as by returned by the AuthRequestByID or AuthRequestByCode (above). + // Used for the authorization code flow which requested offline_access scope and + // registered the refresh_token grant type in advance + CreateAccessAndRefreshTokens(ctx context.Context, request TokenRequest, currentRefreshToken string) (accessTokenID string, newRefreshTokenID string, expiration time.Time, err error) + TokenRequestByRefreshToken(ctx context.Context, refreshTokenID string) (RefreshTokenRequest, error) TerminateSession(ctx context.Context, userID string, clientID string) error - RevokeToken(ctx context.Context, token string, userID string, clientID string) *oidc.Error + RevokeToken(ctx context.Context, tokenID string, userID string, clientID string) *oidc.Error GetSigningKey(context.Context, chan<- jose.SigningKey) GetKeySet(context.Context) (*jose.JSONWebKeySet, error) @@ -42,6 +60,11 @@ type OPStorage interface { ValidateJWTProfileScopes(ctx context.Context, userID string, scopes []string) ([]string, error) } +// Storage is a required parameter for NewOpenIDProvider(). In addition to the +// embedded interfaces below, if the passed Storage implements ClientCredentialsStorage +// then the grant type "client_credentials" will be supported. In that case, the access +// token returned by CreateAccessToken should be a JWT. +// See https://datatracker.ietf.org/doc/html/rfc6749#section-1.3.4 for context. type Storage interface { AuthStorage OPStorage