Skip to content

Getting Started with Cedarling Go Bindings#

Go bindings for the Jans Cedarling authorization engine, providing policy-based access control.

Installation#

Building from Source#

If youre using pre-built binaries from the Jans releases page, you can skip this step. Otherwise, follow these instructions to build from source.

Prerequisites:

  • Go 1.20+
  • Rust toolchain

1. Build the Rust library:

Download Jans monorepo:

git clone --depth 1 https://github.com/JanssenProject/jans.git

We use --depth 1 to avoid cloning unnecessary history and minimalize the download size.

Navigate to the Cedarling Go bindings directory:

cd jans/jans-cedarling/bindings/cedarling_go

cargo build --release -p cedarling_go

2. Copy the built artifacts to your application directory:

# Windows
cp target/release/cedarling_go.dll .
cp target/release/cedarling_go.dll.lib cedarling_go.lib

# Linux
cp target/release/libcedarling_go.so .

# macOS
cp target/release/libcedarling_go.dylib .

or use scripts provided in the repository to automate this process:

sh build_and_copy_artifacts.sh

Run go test to ensure everything is working correctly:

go test .

Build your Go application with dynamic linking#

1. Download pre-built binaries:
Download the appropriate pre-built binary for your platform from the Jans releases page or build it from source as described above.

2. Add linker flags in your main.go file:
You need specify linker flags in your main.go file to link against the Cedarling library.

// #cgo LDFLAGS: -L. -lcedarling_go
import "C"

And make sure that the Cedarling library files are located in the same directory as your main package.

3. Add the Cedarling Go package to your Go application:
Use go get to fetch the Cedarling Go package:

go get github.com/JanssenProject/jans/jans-cedarling/bindings/cedarling_go

4. Add the Cedarling Go package to your Go application:
Build your Go application:

go build .

Run application to ensure it works correctly.

Runtime Notes:

  • On Windows, place the Rust artifacts (cedarling_go.dll and cedarling_go.lib) alongside the Go binary.
  • Files:
    • cedarling_go.dll
    • cedarling_go.lib

  • Windows make search in next directories:

    • The directory containing your Go executable (recommended location)
    • Windows system directories (e.g., C:\Windows\System32)
    • The PATH environment variable directories

  • On Linux, add the library directory to LD_LIBRARY_PATH:

  • Files:
    • libcedarling_go.so
export LD_LIBRARY_PATH=$(pwd):$LD_LIBRARY_PATH
  • On MacOS, add the library directory to DYLD_LIBRARY_PATH (not tested):
  • Files:
    • libcedarling_go.dylib
export DYLD_LIBRARY_PATH=$(pwd):$DYLD_LIBRARY_PATH

Documentation#

Autogenerated documentation is available on pkg.go.dev.

Usage#

Initialization#

import "github.com/JanssenProject/jans/jans-cedarling/bindings/cedarling_go"

// Example configuration (populate dynamically in production)
config := map[string]any{
    "CEDARLING_APPLICATION_NAME":   "MyApp",
    "CEDARLING_POLICY_STORE_ID":    "your-policy-store-id",
    "CEDARLING_USER_AUTHZ":         "enabled",
    "CEDARLING_WORKLOAD_AUTHZ":     "enabled",
    "CEDARLING_LOG_LEVEL":          "INFO",
    "CEDARLING_LOG_TYPE":           "std_out",
    "CEDARLING_POLICY_STORE_LOCAL_FN": "/path/to/policy-store.json",
}

instance, err := cedarling_go.NewCedarling(config)
if err != nil {
    panic(err)
}

Token-Based Authorization#

1. Define the resource:

resource := cedarling_go.EntityData{
    EntityType: "Jans::Issue",
    ID:         "random_id",
    Payload: map[string]any{
        "org_id":  "some_long_id",
        "country": "US",
    },
}

2. Define the action:

action := `Jans::Action::"Update"`

3. Build the request with tokens:

request := cedarling_go.Request{
    Tokens: map[string]string{
        "access_token":   "your.jwt.token",
        "id_token":       "your.id.token",
        "userinfo_token": "your.userinfo.token",
    },
    Action:   action,
    Resource: resource,
}

4. Authorize:

result, err := instance.Authorize(request)
if err != nil {
    // Handle error
}

if result.Decision {
    fmt.Println("Access granted")
} else {
    fmt.Println("Access denied")
}

Custom Principal Authorization (Unsigned)#

1. Define principals:

principals := []cedarling_go.EntityData{
    {
        EntityType: "Jans::User",
        ID:         "random_id",
        Payload: map[string]any{
            "role":    []string{"admin"},
            "country": "US",
            "sub":     "random_sub",
        },
    },
}

2. Build the request:

request := cedarling_go.RequestUnsigned{
    Principals: principals,
    Action:     `Jans::Action::"Update"`,
    Resource:   resource, // From previous example
}

3. Authorize:

result, err := instance.AuthorizeUnsigned(request)
if err != nil {
    // Handle error
}
if result.Decision {
   fmt.Println("Access granted")
} else {
    fmt.Println("Access denied")
}

Logging#

Retrieve logs stored in memory:

// Get all logs and clear the buffer
logs := instance.PopLogs()

// Get a specific log by ID
log := instance.GetLogById("log123")

// Get logs by tag (e.g., "info")
logs := instance.GetLogsByTag("info")

Building for Production#

Consider these settings for production deployments:

  • Set CEDARLING_LOG_LEVEL to WARN or ERROR
  • Enable JWT validation (ensure tokens are properly signed)
Last update: 2025-04-30
Created: 2025-04-30