Skip to content

Commit a87b063

Browse files
DiogoFerraojgero
DiogoFerrao
and
jgero
committed
Initial commit
Co-authored-by: Johannes Gerold <[email protected]>
0 parents  commit a87b063

27 files changed

+1145
-0
lines changed

‎.gitignore‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
# Binaries and build artifacts
2+
**/bin/
3+
dist/
4+
build/
5+
6+
# Dependencies
7+
vendor/
8+
node_modules/
9+
10+
# IDE specific files
11+
.idea/
12+
.vscode/
13+
*.swp
14+
*.swo
15+
*~
16+
17+
# Environment files
18+
.env
19+
.env.local
20+
.env.*.local
21+
22+
# Debug files
23+
*.log
24+
debug/
25+
26+
# Operating System
27+
.DS_Store
28+
Thumbs.db
29+
30+
# Test coverage
31+
coverage/
32+
*.out
33+
34+
# Temporary files
35+
tmp/
36+
temp/
37+
38+
# Binary files
39+
*.exe
40+
*.dll
41+
*.so
42+
43+
# Project specific
44+
config/*.json
45+
!config/example.json

‎README.md‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
<div align="center">
2+
<br>
3+
<img src="img/stackit-logo.png" alt="STACKIT logo" width="50%"/>
4+
<br>
5+
<br>
6+
</div>
7+
8+
# STACKIT Marketplace Reference Code
9+
10+
This repository contains reference implementations for **vendors** looking to integrate with the **STACKIT Marketplace**, demonstrating the subscription approval flow and token validation process.
11+
12+
## What is the STACKIT Marketplace?
13+
14+
The [STACKIT Marketplace](https://docs.stackit.cloud/Marketplace) is a digital platform connecting STACKIT customers with third-party digital products, serving as the technological foundation for rapidly expanding the STACKIT portfolio and building industry-specific cloud offerings. It provides access to a diverse range of products, from IaaS and SaaS to licenses, professional services, and datasets.
15+
16+
## Supported Languages
17+
18+
The integration examples are available in multiple languages:
19+
20+
- [Go](/go) - Go implementation
21+
- [Python](/python) - Python implementation
22+
23+
Each language implementation demonstrates the same core functionality while following language-specific best practices.
24+
25+
## Getting Started
26+
27+
1. Choose your preferred language implementation from the folders above
28+
2. Follow the language-specific README for setup instructions
29+
3. Review the implementation details in the code
30+
4. Adapt the examples to your specific use case
31+
32+
### Integration Flow
33+
34+
1. **Marketplace token validation**: Validates the marketplace token by:
35+
1. Fetching the public key from STACKIT
36+
2. Validating the token format
37+
3. Verifying the token signature
38+
2. **Customer Resolution**: Uses the validated token to resolve customer information
39+
3. **Subscription Approval**: Approves the marketplace subscription
40+
41+
### Key concepts
42+
43+
- **Redirect Token**: The Redirect Token, or simply token, is the JWT Token sent to the vendors when the STACKIT Marketplace redirects consumers to the vendor's `Sign Up/Login` page, which happens in the process of creating a subscription (see [SaaS Frontend Integration](https://docs.stackit.cloud/stackit/en/saas-frontend-integration-290718118.html) for more details).
44+
45+
## Additional Resources
46+
47+
- [STACKIT Marketplace Documentation](https://docs.stackit.cloud/Marketplace)
48+
- [API Reference](https://docs.api.stackit.cloud/documentation/stackit-marketplace/version/v1)
49+
50+
## Contributing
51+
52+
Contributions are welcome! Please feel free to submit a Pull Request.

‎go/Makefile‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
# Variables
2+
BINARY_NAME=marketplace-reference
3+
GO=go
4+
GOFLAGS=-v
5+
MAIN_PACKAGE=./cmd
6+
7+
# Colors for terminal output
8+
CYAN=\033[0;36m
9+
NC=\033[0m # No Color
10+
11+
.PHONY: all build clean test lint fmt vet run help
12+
13+
# Default target
14+
all: clean build
15+
16+
# Build the application
17+
build:
18+
@printf "$(CYAN)Building $(BINARY_NAME)...$(NC)\n"
19+
$(GO) build $(GOFLAGS) -o bin/$(BINARY_NAME) $(MAIN_PACKAGE)
20+
21+
# Clean build artifacts
22+
clean:
23+
@printf "$(CYAN)Cleaning...$(NC)\n"
24+
rm -rf bin/
25+
$(GO) clean
26+
27+
# Run tests
28+
test:
29+
@printf "$(CYAN)Running tests...$(NC)\n"
30+
$(GO) test ./internal/... ./utils/... -v
31+
32+
# Run linter
33+
lint:
34+
@printf "$(CYAN)Running linter...$(NC)\n"
35+
golangci-lint run ./...
36+
37+
# Format code
38+
fmt:
39+
@printf "$(CYAN)Formatting code...$(NC)\n"
40+
$(GO) fmt ./...
41+
42+
# Run go vet
43+
vet:
44+
@printf "$(CYAN)Running go vet...$(NC)\n"
45+
$(GO) vet ./cmd/... ./internal/... ./utils/...
46+
47+
# Run the application
48+
run:
49+
@printf "$(CYAN)Running $(BINARY_NAME)...$(NC)\n"
50+
$(GO) run $(MAIN_PACKAGE)
51+
52+
# Download dependencies
53+
deps:
54+
@printf "$(CYAN)Downloading dependencies...$(NC)\n"
55+
$(GO) mod download
56+
$(GO) mod tidy
57+
58+
# Show help
59+
help:
60+
@echo "Available targets:"
61+
@echo " all - Clean and build the project"
62+
@echo " build - Build the application"
63+
@echo " clean - Remove build artifacts"
64+
@echo " test - Run tests"
65+
@echo " lint - Run linter"
66+
@echo " fmt - Format code"
67+
@echo " vet - Run go vet"
68+
@echo " run - Run the application"
69+
@echo " deps - Download dependencies"
70+
@echo " help - Show this help message"

‎go/README.md‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
# STACKIT Marketplace Reference Code in Golang
2+
3+
This Golang reference code exemplifies how to integrate with the STACKIT Marketplace API as a vendor, showing the essential flow of authenticating and handling marketplace subscriptions.
4+
5+
## Overview
6+
7+
This example application demonstrates three key marketplace integration steps:
8+
9+
1. **Token Validation**: Validates marketplace tokens using public key cryptography
10+
2. **Customer Resolution**: Retrieves customer information from subscription tokens
11+
3. **Subscription Approval**: Processes and approves marketplace subscriptions
12+
13+
## Prerequisites
14+
15+
- Go 1.18 or higher
16+
- A STACKIT Service Account Key
17+
- A marketplace token (`x-stackit-marketplace`) received via the vendor's redirect URL
18+
19+
## Getting Started
20+
21+
1. Clone this repository
22+
2. Set up authentication with the STACKIT Go SDK (see [Using the STACKIT Go SDK](#using-the-stackit-go-sdk) below)
23+
3. Set the following environment variables:
24+
25+
- `MP_REF_CODE_REDIRECT_TOKEN`: The `x-stackit-marketplace` token received during redirect
26+
- `MP_REF_CODE_VENDOR_PROJECT_ID`: Your vendor STACKIT project ID associated with the product
27+
28+
4. Run the application using either:
29+
30+
```bash
31+
make run
32+
```
33+
34+
or
35+
36+
```bash
37+
go run cmd/main.go
38+
```
39+
40+
## Flow Explanation
41+
42+
The application demonstrates the following flow:
43+
44+
1. **Marketplace token validation**: Validates the marketplace token by:
45+
- Fetching the public key from STACKIT
46+
- Validating the token format
47+
- Verifying the token signature
48+
2. **Customer Resolution**: Uses the validated token to resolve customer information
49+
3. **Subscription Approval**: Approves the marketplace subscription
50+
51+
## Project Structure
52+
53+
```bash
54+
.
55+
├── cmd/
56+
│ └── main.go # Application entry point
57+
├── internal/
58+
│ ├── step_1_validate_token.go # Token validation logic
59+
│ ├── step_2_resolve_customer.go # Customer resolution logic
60+
│ └── step_3_approve_subscription.go # Subscription approval logic
61+
├── utils/ # Utility functions
62+
│ └── utils.go
63+
```
64+
65+
## Development
66+
67+
The project includes several make targets for development:
68+
69+
```bash
70+
make build # Build the application
71+
make test # Run tests
72+
make lint # Run linter
73+
make fmt # Format code
74+
make clean # Clean build artifacts
75+
```
76+
77+
## Using the STACKIT Go SDK
78+
79+
The examples in this repository use the official [STACKIT Go SDK](https://github.com/stackitcloud/stackit-sdk-go) to interact with the Marketplace API.
80+
81+
Authentication is handled automatically by the SDK using its default configuration. For details, see the SDK's [Authentication documentation](https://github.com/stackitcloud/stackit-sdk-go?tab=readme-ov-file#authentication).
82+
83+
A **potential** way to authenticate is by setting one of these environment variables:
84+
85+
- `STACKIT_SERVICE_ACCOUNT_KEY`: Your service account key
86+
- `STACKIT_SERVICE_ACCOUNT_KEY_PATH`: Path to a file containing your service account key
87+
- `STACKIT_SERVICE_ACCOUNT_TOKEN`: Your service account access token
88+
89+
## Contributing
90+
91+
Feel free to submit issues and enhancement requests!

‎go/cmd/main.go‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
package main
2+
3+
import (
4+
"context"
5+
"log"
6+
"os"
7+
8+
"github.com/stackitcloud/marketplace-reference-code/internal"
9+
"github.com/stackitcloud/marketplace-reference-code/utils"
10+
"github.com/stackitcloud/stackit-sdk-go/services/stackitmarketplace"
11+
)
12+
13+
const (
14+
VendorProjectIdEnvVar = "MP_REF_CODE_VENDOR_PROJECT_ID"
15+
MarketplaceTokenEnvVar = "MP_REF_CODE_REDIRECT_TOKEN"
16+
)
17+
18+
func main() {
19+
ctx := context.Background()
20+
21+
log.Println("🔐 Setting up SDK client...")
22+
client, err := stackitmarketplace.NewAPIClient()
23+
if err != nil {
24+
log.Fatalf("❌ Failed to setup SDK client: %v", err)
25+
}
26+
log.Println("✅ SDK client setup successfully")
27+
28+
// read the token and the vendor project ID from the environment variables
29+
tokenString, ok := os.LookupEnv(MarketplaceTokenEnvVar)
30+
if !ok {
31+
log.Fatalf("❌ The required environment variable %s is not set", MarketplaceTokenEnvVar)
32+
}
33+
vendorProjectID, ok := os.LookupEnv(VendorProjectIdEnvVar)
34+
if !ok {
35+
log.Fatalf("❌ The required environment variable %s is not set", VendorProjectIdEnvVar)
36+
}
37+
38+
// x-stackit-marketplace-token authentication
39+
log.Println("🔐 Authenticating token...")
40+
err = internal.ValidateToken(tokenString)
41+
if err != nil {
42+
log.Fatalf("❌ Token authentication failed: %v", err)
43+
}
44+
log.Println("✅ Token authenticated successfully")
45+
46+
// resolve customer
47+
log.Println("🔐 Resolving customer...")
48+
subscription, err := internal.ResolveCustomer(ctx, client, vendorProjectID, tokenString)
49+
if err != nil {
50+
log.Fatalf("❌ Failed to resolve customer: %v", err)
51+
}
52+
log.Printf("✅ Customer resolved successfully \n%+v", utils.VendorSubscriptionToString(subscription))
53+
54+
// approve subscription
55+
log.Println("🔐 Approving subscription...")
56+
err = internal.ApproveSubscription(ctx, client, vendorProjectID, *subscription.SubscriptionId)
57+
if err != nil {
58+
log.Fatalf("❌ Failed to approve subscription: %v", err)
59+
}
60+
log.Println("✅ Subscription approved successfully")
61+
}

‎go/go.mod‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
module github.com/stackitcloud/marketplace-reference-code
2+
3+
go 1.18.0
4+
5+
require (
6+
github.com/golang-jwt/jwt v3.2.2+incompatible
7+
github.com/stackitcloud/stackit-sdk-go/core v0.15.1
8+
github.com/stackitcloud/stackit-sdk-go/services/stackitmarketplace v0.1.0
9+
)
10+
11+
require (
12+
github.com/golang-jwt/jwt/v5 v5.2.1 // indirect
13+
github.com/google/uuid v1.6.0 // indirect
14+
)

‎go/go.sum‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
github.com/golang-jwt/jwt v3.2.2+incompatible h1:IfV12K8xAKAnZqdXVzCZ+TOjboZ2keLg81eXfW3O+oY=
2+
github.com/golang-jwt/jwt v3.2.2+incompatible/go.mod h1:8pz2t5EyA70fFQQSrl6XZXzqecmYZeUEB8OUGHkxJ+I=
3+
github.com/golang-jwt/jwt/v5 v5.2.1 h1:OuVbFODueb089Lh128TAcimifWaLhJwVflnrgM17wHk=
4+
github.com/golang-jwt/jwt/v5 v5.2.1/go.mod h1:pqrtFR0X4osieyHYxtmOUWsAWrfe1Q5UVIyoH402zdk=
5+
github.com/google/go-cmp v0.6.0 h1:ofyhxvXcZhMsU5ulbFiLKl/XBFqE1GSq7atu8tAmTRI=
6+
github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
7+
github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
8+
github.com/stackitcloud/stackit-sdk-go/core v0.15.1 h1:hIj/k/JXEuYmud3VWo3lr7Cfj2hfl4gG9nUIzcaZ9pM=
9+
github.com/stackitcloud/stackit-sdk-go/core v0.15.1/go.mod h1:mDX1mSTsB3mP+tNBGcFNx6gH1mGBN4T+dVt+lcw7nlw=
10+
github.com/stackitcloud/stackit-sdk-go/services/stackitmarketplace v0.1.0 h1:yBirkvwFnPisxFWV12N8xP164v9Vt3KBoqZ3Jp1S9iQ=
11+
github.com/stackitcloud/stackit-sdk-go/services/stackitmarketplace v0.1.0/go.mod h1:8fizt9sQTii3wR38gMZuVlhqhlmhbFb+JlbJOhWFFnU=

0 commit comments

Comments
 (0)