CLOUDP-279930: Admin SDK helper with examples (#461)

Co-authored-by: Lovisa Berggren <[email protected]>

Author: wtrocki

admin/atlas_client.go

@@ -6,6 +6,7 @@ import (
 	"strings"
 
 	"github.com/mongodb-forks/digest"
+	"go.mongodb.org/atlas-sdk/v20241023001/auth/credentials"
 	"go.mongodb.org/atlas-sdk/v20241023001/internal/core"
 )
 
@@ -52,6 +53,34 @@ func UseDigestAuth(apiKey, apiSecret string) ClientModifier {
 	}
 }
 
+// UseOAuthAuth provides OAuthAuth authentication for Go SDK.
+// Method is provided as helper to create a default HTTP client that supports OAuth (Service Accounts) authentication.
+// credentials.LocalTokenCache can be supplied to reuse OAuth Token across application restarts.
+// Warning: for advanced use cases please use credentials.NewTokenSource directly in your code pass it to UseHTTPClient method.
+// Warning: any previously set httpClient will be overwritten. To fully customize HttpClient use UseHTTPClient method.
+func UseOAuthAuth(clientID, clientSecret string, tokenCache credentials.LocalTokenCache) ClientModifier {
+	return func(c *Configuration) error {
+		var tokenSource credentials.TokenSource
+		if tokenCache != nil {
+			tokenSource = credentials.NewTokenSourceWithOptions(credentials.AtlasTokenSourceOptions{
+				ClientID:     clientID,
+				ClientSecret: clientSecret,
+				TokenCache:   tokenCache,
+				BaseURL:      &c.Servers[0].URL,
+			})
+		} else {
+			tokenSource = credentials.NewTokenSourceWithOptions(credentials.AtlasTokenSourceOptions{
+				ClientID:     clientID,
+				ClientSecret: clientSecret,
+				BaseURL:      &c.Servers[0].URL,
+			})
+		}
+		httpClient := credentials.NewHTTPClientWithOAuthToken(tokenSource)
+		c.HTTPClient = httpClient
+		return nil
+	}
+}
+
 // Advanced modifiers.
 
 // UseHTTPClient set custom http client implementation.

auth/credentials/api.go

@@ -63,6 +63,10 @@ func NewTokenSourceWithOptions(opts AtlasTokenSourceOptions) TokenSource {
 		ctx = *opts.Context
 	}
 
+	if opts.TokenCache == nil {
+		opts.TokenCache = &InMemoryTokenCache{}
+	}
+
 	return &OAuthTokenSource{
 		clientID:     opts.ClientID,
 		clientSecret: opts.ClientSecret,

auth/credentials/oauth.go

@@ -50,8 +50,8 @@ func (c *OAuthTokenSource) RevokeToken() error {
 	if err != nil {
 		return err
 	}
-	if tokenString != nil && *tokenString != "" {
-		err := c.revokeTokenInRemoteServer(*tokenString)
+	if tokenString != "" {
+		err := c.revokeTokenInRemoteServer(tokenString)
 		if err != nil {
 			return err
 		}
@@ -70,12 +70,12 @@ func (c *OAuthTokenSource) RevokeToken() error {
 func (c *OAuthTokenSource) GetValidToken() (*Token, error) {
 	// Try to retrieve the Token string from the Token source
 	tokenString, err := c.tokenCache.RetrieveToken(c.ctx)
-	if err != nil || tokenString == nil {
+	if err != nil || tokenString == "" {
 		return c.refreshToken()
 	}
 
 	// Parse the Token string into the Token structure (mock parse operation)
-	c.token, err = parseToken(*tokenString)
+	c.token, err = parseToken(tokenString)
 	if err != nil || c.token.expired() {
 		// Token is invalid or expired, refresh it
 		return c.refreshToken()
@@ -169,17 +169,17 @@ func (c *OAuthTokenSource) fetchTokenFromRemoteServer() (*Token, error) {
 	defer resp.Body.Close()
 
 	if resp.StatusCode != http.StatusOK {
+		msg, _ := io.ReadAll(resp.Body)
 		if resp.StatusCode == http.StatusTooManyRequests {
-			msg, _ := io.ReadAll(resp.Body)
 			formattedMessage := fmt.Sprintf("%v %v: HTTP %v Detail: %v Reason: %v",
 				"POST", c.tokenURL, resp.StatusCode,
 				"Token request was rate limited", string(msg))
 			return nil, errors.New(formattedMessage)
 		}
 		formattedMessage := fmt.Sprintf("%v %v: HTTP %v Detail: %v Reason: %v",
 			"POST", c.tokenURL, resp.StatusCode,
-			"Failed to obtain Access Token when fetching new OAuth Token from remote server",
-			resp.Header.Get("www-authenticate"))
+			"Failed to obtain Access Token when fetching new OAuth Token from remote server for client "+c.clientID,
+			string(msg))
 		return nil, errors.New(formattedMessage)
 	}
 	// tokenRemoteResponse represents successful response from token endpoint

auth/credentials/oauth_test.go

@@ -66,8 +66,8 @@ type MockTokenCache struct {
 }
 
 // Retrieve returns the stored Token
-func (m *MockTokenCache) RetrieveToken(_ context.Context) (*string, error) {
-	return &m.token, nil
+func (m *MockTokenCache) RetrieveToken(_ context.Context) (string, error) {
+	return m.token, nil
 }
 
 // Save saves the Token

auth/credentials/token_cache.go

@@ -10,34 +10,34 @@ import (
 // Interface allows integrators to fully control how access Token is catched on their side.
 type LocalTokenCache interface {
 	// RetrieveToken should return the access Token string.
-	RetrieveToken(ctx context.Context) (*string, error)
+	RetrieveToken(ctx context.Context) (string, error)
 
 	// SaveToken should save the access Token string.
 	SaveToken(ctx context.Context, token string) error
 }
 
-// InMemoryTokenCache is an default implementation of LocalTokenCache that stores the Token in memory.
+// InMemoryTokenCache is a default implementation of LocalTokenCache that stores the Token in memory.
 // Implementation provides locking mechanism in order to prevent overriding access tokens
 type InMemoryTokenCache struct {
-	token *string
+	token string
 	mu    sync.Mutex
 }
 
-func (s *InMemoryTokenCache) RetrieveToken(_ context.Context) (*string, error) {
+func (s *InMemoryTokenCache) RetrieveToken(_ context.Context) (string, error) {
 	// Locking will avoid Token overrides when sharing TokenCache in multiple threads
 	s.mu.Lock()
 	defer s.mu.Unlock()
 
-	if s.token != nil {
+	if s.token != "" {
 		return s.token, nil
 	}
-	return nil, errors.New("InMemoryTokenCache: Token not found. Token needs to be refreshed in backend")
+	return "", errors.New("InMemoryTokenCache: Token not found. Token needs to be refreshed in backend")
 }
 
 func (s *InMemoryTokenCache) SaveToken(_ context.Context, token string) error {
 	// Locking will avoid Token overrides when sharing TokenCache in multiple threads
 	s.mu.Lock()
 	defer s.mu.Unlock()
-	s.token = &token
+	s.token = token
 	return nil
 }

examples/auth/basic_client.go

@@ -0,0 +1,54 @@
+package main
+
+import (
+	"context"
+	"fmt"
+	"go.mongodb.org/atlas-sdk/v20241023001/admin"
+	"log"
+	"os"
+)
+
+// Basic example for Service Account OAuth Authentication
+// Covers creation of the HTTP client with Service Account OAuth authentication
+// Required env variables to run example:
+// export MONGODB_ATLAS_CLIENT_ID="your_client_id"
+// export MONGODB_ATLAS_CLIENT_SECRET="your_client_secret"
+func main() {
+	// Fetch clientID and clientSecret from environment variables
+	clientID := os.Getenv("MONGODB_ATLAS_CLIENT_ID")
+	clientSecret := os.Getenv("MONGODB_ATLAS_CLIENT_SECRET")
+
+	if clientID == "" || clientSecret == "" {
+		log.Fatal("Missing CLIENT_ID or CLIENT_SECRET environment variables")
+	}
+
+	ctx := context.Background()
+	// Create Admin API Client with OAuth credentials.
+	// Skips optional tokenCache parameter
+	sdk, err := admin.NewClient(
+		admin.UseOAuthAuth(clientID, clientSecret, nil),
+	)
+
+	if err != nil {
+		log.Fatalf("Error: %v", err)
+	}
+
+	request := sdk.ProjectsApi.ListProjectsWithParams(ctx,
+		&admin.ListProjectsApiParams{
+			ItemsPerPage: admin.PtrInt(1),
+			IncludeCount: admin.PtrBool(true),
+			PageNum:      admin.PtrInt(1),
+		})
+
+	if err != nil {
+		log.Fatalf("Error making request: %v", err)
+	}
+	projects, _, err := request.IncludeCount(true).PageNum(1).Execute()
+	if err != nil {
+		log.Fatalf("Error: %v", err)
+	}
+
+	if projects.Results == nil {
+		fmt.Printf("projects should not be empty:  %v", projects)
+	}
+}

examples/auth/credentials.go renamed to examples/auth_advanced/advanced_client.go

@@ -12,8 +12,13 @@ import (
 	"go.mongodb.org/atlas-sdk/v20241023001/auth/credentials"
 )
 
-// Example for Service Account Authentication
-// Required env variables
+// Advanced Example for Service Account OAuth Authentication
+// Provides:
+// 1. Custom Token Cache in order to store OAuth Token for further reuse across application restarts
+// 2. Usage of logout (Token Revocation) method.
+// 3. Using custom Context and HttpTransports
+//
+// Required env variables to run example:
 // export MONGODB_ATLAS_CLIENT_ID="your_client_id"
 // export MONGODB_ATLAS_CLIENT_SECRET="your_client_secret"
 // export MONGODB_ATLAS_URL=https://cloud.mongodb.com
@@ -77,6 +82,7 @@ func main() {
 		fmt.Printf("projects should not be empty:  %v", projects)
 	}
 
+	// Revoke Token in the client (logout)
 	err = tokenSource.RevokeToken()
 	if err != nil {
 		log.Fatalf("Error: %v", err)
@@ -89,7 +95,7 @@ type MyTokenCache struct {
 	mu          sync.Mutex
 }
 
-func (s *MyTokenCache) RetrieveToken(ctx context.Context) (*string, error) {
+func (s *MyTokenCache) RetrieveToken(_ context.Context) (string, error) {
 	// Locking added to ensure no race condition happens with SaveToken
 	s.mu.Lock()
 	defer s.mu.Unlock()
@@ -99,13 +105,13 @@ func (s *MyTokenCache) RetrieveToken(ctx context.Context) (*string, error) {
 	var tkn string
 	err := json.Unmarshal(s.fileContent, &tkn)
 	if err != nil {
-		return nil, err
+		return "", err
 	}
 
-	return &tkn, nil
+	return tkn, nil
 }
 
-func (s *MyTokenCache) SaveToken(ctx context.Context, tkn string) error {
+func (s *MyTokenCache) SaveToken(_ context.Context, tkn string) error {
 	// Locking added to ensure no race condition happens with RetrieveToken
 	s.mu.Lock()
 	defer s.mu.Unlock()

tools/config/go-templates/atlas_client.mustache

@@ -53,8 +53,35 @@ func UseDigestAuth(apiKey, apiSecret string) ClientModifier {
 	}
 }
 
-// Advanced modifiers.
+// UseOAuthAuth provides OAuthAuth authentication for Go SDK.
+// Method is provided as helper to create a default HTTP client that supports OAuth (Service Accounts) authentication.
+// credentials.LocalTokenCache can be supplied to reuse OAuth Token across application restarts.
+// Warning: for advanced use cases please use credentials.NewTokenSource directly in your code pass it to UseHTTPClient method.
+// Warning: any previously set httpClient will be overwritten. To fully customize HttpClient use UseHTTPClient method.
+func UseOAuthAuth(clientID, clientSecret string, tokenCache credentials.LocalTokenCache) ClientModifier {
+	return func(c *Configuration) error {
+		var tokenSource credentials.TokenSource
+		if tokenCache != nil {
+			tokenSource = credentials.NewTokenSourceWithOptions(credentials.AtlasTokenSourceOptions{
+				ClientID:     clientID,
+				ClientSecret: clientSecret,
+				TokenCache:   tokenCache,
+				BaseURL:      &c.Servers[0].URL,
+			})
+		} else {
+			tokenSource = credentials.NewTokenSourceWithOptions(credentials.AtlasTokenSourceOptions{
+				ClientID:     clientID,
+				ClientSecret: clientSecret,
+				BaseURL:      &c.Servers[0].URL,
+			})
+		}
+		httpClient := credentials.NewHTTPClientWithOAuthToken(tokenSource)
+		c.HTTPClient = httpClient
+		return nil
+	}
+}
 
+// Advanced modifiers.
 
 //  UseHTTPClient set custom http client implementation.
 //