deploymenttheory / go-api-sdk-jamfpro

A jamf pro api sdk written in go that can perform CRUD operations against both the classic and jamf pro api. Includes an examples and recipes library demonstrating usage
Mozilla Public License 2.0
14 stars 8 forks source link

Getting Started with go-api-sdk-jamfpro

This guide will help you get started with go-api-sdk-jamfpro, a Go SDK for interfacing with Jamf Pro.

Go Prerequisites

Ensure you have Go installed and set up on your system. If not, follow the instructions on the official Go website.

Installation

Install the go-api-sdk-jamfpro package using go get:

go get github.com/deploymenttheory/go-api-sdk-jamfpro

Usage

It's highly recommended to use the examples library to get started with the SDK. Here you will find examples of how to use the SDK to perform various operations on your Jamf Pro instance.

Authentication Pre-requisites: Obtaining Client ID and Client Secret

To securely interact with the Jamf Pro API, it's essential to obtain a unique client ID and client secret. These credentials are used to authenticate API requests and ensure that only authorized users and applications can access your Jamf Pro environment.

API Roles and Clients in Jamf Pro

The API Roles and Clients functionality in Jamf Pro provides a dedicated interface for controlling access to both the Jamf Pro API and the Classic API. This feature allows you to create custom privilege sets, known as API roles, and assign them as needed to ensure that API clients possess only the necessary capabilities for their tasks. Roles can be shared between clients or assigned more than one to a client, offering a flexible way to manage and reuse privilege sets for various purposes with granular control.

Creating API Clients

To create an API client and generate a client ID and secret:

  1. Navigate to the Settings in your Jamf Pro dashboard.
  2. Select System Settings.
  3. Choose API Roles and Clients under the System Settings options.
  4. Click on New Client to create a new API client.
  5. Assign a name and description for your client, and select the API roles that define the permissions this client will have.
  6. Once the client is created, Jamf Pro will generate a unique client ID and client secret. Make sure to securely store these credentials as they are required for authenticating your API requests.

For a detailed guide and best practices on creating and managing API clients and roles, refer to the official Jamf Pro documentation: API Roles and Clients in Jamf Pro.

Remember to keep your client ID and secret confidential and secure, as these credentials provide access to your Jamf Pro environment's API.

Configuring the Jamf Pro Client with the Go SDK

The go-api-sdk-jamfpro provides two convenient ways to build and configure your Jamf Pro client: using environment variables or a JSON configuration file. This flexibility allows for easy integration into different environments and deployment pipelines.

Option 1: Building Client with Environment Variables

For scenarios where you prefer not to use configuration files (e.g., in containerized environments or CI/CD pipelines), you can configure the Jamf Pro client using environment variables.

  1. Set Environment Variables: Define the necessary environment variables in your environment. This includes credentials (for OAuth or classic auth), instance details, and client options.

    export CLIENT_ID="your_client_id"
    export CLIENT_SECRET="your_client_secret"
    export INSTANCE_DOMAIN="https://your_instance.jamfcloud.com" # use the fqdn
    export AUTH_METHOD="oauth2" # or "basic"
    export BASIC_AUTH_USERNAME="your_basic_auth_username" # Required if using basic auth
    export BASIC_AUTH_PASSWORD="your_basic_auth_password" # Required if using basic auth
    export CLIENT_ID="your_client_id" # Required if using oauth2
    export CLIENT_SECRET="your_client_secret" # Required if using oauth2
    export LOG_LEVEL="info" # or "debug" / "info" / "warn" / "dpanic" / "error"
    export LOG_OUTPUT_FORMAT="pretty" # or "json" 
    export LOG_CONSOLE_SEPARATOR=" " # or any other separator
    export LOG_EXPORT_PATH="/your/log/path/" # optional, ensure permissions to file path
    export EXPORT_LOGS="true" # or "false"
    export HIDE_SENSITIVE_DATA="true" # or "false"
    export MAX_RETRY_ATTEMPTS="3" # optional  
    export MAX_CONCURRENT_REQUESTS="5" # optional
    export ENABLE_DYNAMIC_RATE_LIMITING="true" # or "false"
    export TOKEN_REFRESH_BUFFER_PERIOD_SECONDS="300" # optional, in seconds
    export TOTAL_RETRY_DURATION_SECONDS="300" # optional, in seconds
    export CUSTOM_TIMEOUT_SECONDS="60" # optional, in seconds
    export FOLLOW_REDIRECTS="true" # or "false"
    export MAX_REDIRECTS="5" # Sets the maximum number of redirects
    export ENABLE_CONCURRENCY_MANAGEMENT="true" # or "false"
    export JAMF_LOAD_BALANCER_LOCK="true" # or "false"
    export CUSTOM_COOKIES='[{"name": "jpro-ingress", "value": "your_cookie_value"}, {"name": "sessionToken", "value": "abc123"}, {"name": "userPref", "value": "lightMode"}]' # optional, JSON array of cookies
  2. Build the Client: Use the BuildClientWithEnv function to build the Jamf Pro client using the environment variables.

    client, err := jamfpro.BuildClientWithEnv()
    if err != nil {
        log.Fatalf("Failed to build Jamf Pro client with environment variables: %v", err)
    }

    This method will automatically read the configuration from the environment variables and initialize the Jamf Pro client.

Option 2: Building Client with a Configuration File

For those who prefer using configuration files for setting up the client, the SDK supports loading configuration from a JSON file.

  1. Prepare the Configuration File: Create a JSON file with the necessary configuration. This includes authentication credentials, environment settings, and client options.

    {
      "log_level": "info", // or "debug" / "info" / "warn" / "dpanic" / "error"
      "log_output_format": "pretty", // or "json"
      "log_console_separator": "  ",
      "log_export_path": "/your/log/path/", // optional, ensure permissions to file path
      "export_logs": true, // or false
      "hide_sensitive_data": false, // redact sensitive data from logs
      "instance_domain": "https://lbgsandbox.jamfcloud.com",
      "auth_method": "oauth2", // or "basic"
      "client_id": "your_client_id", // Required if using oauth2
      "client_secret": "your_client_secret", // Required if using oauth2
      "basic_auth_username": "your_basic_auth_username", // Required if using basic auth
      "basic_auth_password": "your_basic_auth_password", // Required if using basic auth
      "jamf_load_balancer_lock": false, // or true
      "max_retry_attempts": 3,
      "enable_dynamic_rate_limiting": true,
      "max_concurrent_requests": 5, // optional
      "token_refresh_buffer_period_seconds": 300, // optional in seconds
      "total_retry_duration_seconds": 300, // optional in seconds
      "custom_timeout_seconds": 300, // optional in seconds
      "follow_redirects": true,
      "max_redirects": 5,
      "enable_concurrency_management": true,
      "custom_cookies": [
        {
          "name": "cookie1",
          "value": "value1"
        },
        {
          "name": "cookie2",
          "value": "value2"
        }
      ]
    }

    Replace placeholders with actual values as needed.

  2. Load Configuration and Build the Client: Use the BuildClientWithConfigFile function to read the configuration from the file and initialize the Jamf Pro client.

    configFilePath := "path_to_your/client_config.json"
    client, err := jamfpro.BuildClientWithConfigFile(configFilePath)
    if err != nil {
        log.Fatalf("Failed to build Jamf Pro client with configuration file: %v", err)
    }

    This method will load the configuration from the specified file and use it to set up the Jamf Pro client.

Summary

Both methods provide a flexible way to configure and initialize the Jamf Pro client, allowing you to choose the approach that best fits your deployment strategy and environment. Remember to handle credentials securely and avoid exposing sensitive information in your code or public repositories.

Calling SDK Functions

Once the Jamf Pro client is configured and initialized, you can start making API calls to perform various operations on your Jamf Pro instance. This section provides examples of common SDK functions you might want to use.

Fetching Device Details

To fetch details about a specific device, you can use the GetComputerByID function. You will need the device's unique identifier (such as a serial number) to retrieve its details.

// Assuming 'client' is your initialized Jamf Pro client
deviceID := "your_jamf_computer_id"
deviceDetails, err := client.GetComputerByID(deviceID)
if err != nil {
    log.Fatalf("Failed to get device details: %v", err)
}

// Use 'deviceDetails' as needed
fmt.Printf("Device Name: %s\n", deviceDetails.General.DeviceName)

Go SDK for Jamf Pro API Progress Tracker

API Coverage Progress

Date: Feb-2024 Maintainer: [ShocOne]

Overview

This document tracks the progress of API endpoint coverage tests. As endpoints are tested, they will be marked as covered.

Coverage Legend

Endpoints

Accounts - /JSSResource/accounts

This documentation outlines the operations available for Jamf Pro Accounts and Account Groups.

Operations

Summary

Activation Code - /JSSResource/activationcode

This documentation outlines the operations available for Activation Code in Jamf Pro.

Operations

Summary

Jamf Pro API Integrations - /api/v1/api-integrations

This documentation outlines the operations available for Jamf API Integrations.

Operations

Summary

Jamf Pro API Role Privileges - /api/v1/api-role-privileges

This documentation outlines the operations available for Jamf API Role Privileges.

Operations

Summary

Jamf Pro API Roles - /api/v1/api-roles

This documentation outlines the operations available for Jamf API Roles.

Operations

Summary

Jamf Pro Classic API - Advanced Computer Searches

This documentation outlines the operations available for Advanced Computer Searches.

Operations

Summary

Jamf Pro Classic API - Advanced Mobile Device Searches

This documentation outlines the operations available for Advanced Mobile Device Searches.

Operations

Summary

Jamf Pro Classic API - Advanced User Searches

This documentation outlines the operations available for Advanced User Searches.

Operations

Summary

Allowed File Extensions - /JSSResource/allowedfileextensions

This documentation outlines the operations available for Allowed File Extensions.

Operations

Summary

BYO Profiles - /JSSResource/byoprofiles

This documentation outlines the operations available for BYO profiles.

Operations

Summary

Jamf Pro API - Categories

This documentation outlines the operations available for categories using the API.

Operations

Summary

Jamf Pro Classic API - Computer Groups

This documentation outlines the operations available for computer groups using the Classic API.

Operations

Summary

macOS Configuration Profiles - /JSSResource/osxconfigurationprofiles

This documentation outlines the operations available for macOS configuration profiles using the API.

Operations

Summary

Departments - /JSSResource/departments

This documentation outlines the operations available for departments using the API.

Operations

Summary

Policies - /JSSResource/policies

This documentation outlines the operations available for policies using the API.

Operations

Summary

Jamf Pro API - Self Service Branding macOS

This documentation outlines the operations available for self-service branding configurations for macOS using the API.

Operations

Summary

Jamf Pro Classic API - Scripts

This documentation outlines the operations available for scripts using the API.

Operations

Summary

Jamf Pro Classic API - Sites

This documentation outlines the operations available for sites using the API.

Operations

Summary

Jamf Pro API - SSO Failover

This documentation outlines the operations available for SSO Failover using the API.

Operations

Summary

Jamf Pro API - Volume Purchasing Subscriptions

This documentation provides details on the API endpoints available for managing Volume Purchasing Subscriptions within Jamf Pro.

Operations

Summary

Jamf Pro API - Computer Inventory Collection Settings

This documentation outlines the API endpoints available for managing Computer Inventory Collection Settings in Jamf Pro.

Operations

Summary

Jamf Pro API - Jamf Pro Information

This documentation covers the API endpoints available for retrieving information about the Jamf Pro server.

Operations

Summary

Jamf Pro Classic API - Classes

This documentation provides details on the API endpoints available for managing classes within Jamf Pro using the Classic API which requires XML data structure support.

Operations

Summary

Jamf Pro Classic API - Computer Invitations

This documentation outlines the API endpoints available for managing computer invitations within Jamf Pro using the Classic API, which relies on XML data structures.

Operations

Summary

Jamf Pro Classic API - Disk Encryption Configurations

This documentation provides details on the API endpoints available for managing disk encryption configurations within Jamf Pro using the Classic API which requires XML data structure support.

Endpoints

Summary

Jamf Pro Classic API - Distribution Points

This documentation outlines the operations available for managing Distribution Points within Jamf Pro using the Classic API, which supports XML data structures.

Operations

Summary

Jamf Pro Classic API - Directory Bindings

This documentation outlines the operations available for managing Directory Bindings within Jamf Pro using the Classic API, which supports XML data structures.

Operations

Summary

Jamf Pro Classic API - Computers

This documentation outlines the operations available for managing Computers within Jamf Pro using the Classic API, which supports XML data structures.

Operations

Summary

Jamf Pro Classic API - Dock Items

This documentation outlines the operations available for managing Dock Items within Jamf Pro using the Classic API, which supports XML data structures.

Operations

Summary

Jamf Pro Classic API - eBooks

This documentation outlines the operations available for managing eBooks within Jamf Pro using the Classic API, which supports XML data structures.

Operations

Summary

Jamf Pro Classic API - VPP Mac Applications

This documentation outlines the operations available for managing VPP Mac applications within Jamf Pro using the Classic API, which supports XML data structures.

Operations

Summary

Jamf Pro Classic API - iBeacons

This documentation outlines the operations available for managing iBeacons within Jamf Pro using the Classic API, which supports XML data structures.

Operations

Summary

Jamf Pro Classic API - LDAP Servers

This documentation outlines the operations available for managing LDAP servers within Jamf Pro using the Classic API, which supports XML data structures.

Operations

Summary

Jamf Pro Classic API - Licensed Software

This documentation outlines the operations available for managing Licensed Software within Jamf Pro using the Classic API, which supports XML data structures.

Operations

Summary

Jamf Pro Classic API - Mobile Device Applications

This documentation outlines the operations available for managing Mobile Device Applications within Jamf Pro using the Classic API, which supports XML data structures.

Operations

Summary

Jamf Pro Classic API - Mobile Device Configuration Profiles

This documentation outlines the operations available for managing Mobile Device Configuration Profiles within Jamf Pro using the Classic API, which supports XML data structures.

Operations

Summary

Jamf Pro Classic API - Mobile Extension Attributes

This documentation outlines the operations available for managing Mobile Extension Attributes within Jamf Pro using the Classic API, which supports XML data structures.

Operations

Summary

Jamf Pro Classic API - Mobile Device Enrollment Profiles

This documentation outlines the operations available for managing Mobile Device Enrollment Profiles within Jamf Pro using the Classic API, which supports XML data structures.

Operations

Summary

Jamf Pro Classic API - Printers

This documentation outlines the API endpoints available for managing printers within Jamf Pro using the Classic API, which supports XML data structures.

Endpoints

Jamf Pro Classic API - Network Segments

This documentation outlines the operations available for managing Network Segments within Jamf Pro using the Classic API, which supports XML data structures.

Operations

Summary

Jamf Pro Classic API - Mobile Device Groups

This documentation outlines the operations available for managing Mobile Device Groups within Jamf Pro using the Classic API, which supports XML data structures.

Operations

Summary

Jamf Pro Classic API - Mobile Device Provisioning Profiles

This documentation outlines the operations available for managing Mobile Device Provisioning Profiles within Jamf Pro using the Classic API, which supports XML data structures.

Operations

Summary

Jamf Pro API - Buildings

This documentation outlines the operations available for managing Buildings within Jamf Pro using the API, which supports JSON data structures.

Operations

Summary

Jamf Pro Classic API - Users

This documentation outlines the operations available for managing Users within Jamf Pro using the Classic API, which supports XML data structures.

Operations

Summary

Jamf Pro Classic API - User Groups

This documentation outlines the operations available for managing User Groups within Jamf Pro using the Classic API, which supports XML data structures.

Operations

Summary

Jamf Pro Classic API - User Extension Attributes

This documentation outlines the operations available for managing User Extension Attributes within Jamf Pro using the Classic API, which supports XML data structures.

Operations

Summary

Jamf Pro Classic API - Mobile Devices

This documentation details the operations available for managing Mobile Devices within Jamf Pro using the Classic API, which supports XML data structures.

Operations

Summary

Jamf Pro Classic API - Patch Policies

This documentation outlines the operations available for managing Patch Policies within Jamf Pro using the Classic API, which supports XML data structures.

Operations

Summary

Jamf Pro API - Computer Inventory

This documentation details the operations available for managing Computer Inventory within Jamf Pro using the API, which supports JSON data structures.

Operations

Summary

Jamf Pro Classic API - Removable Mac Addresses

This documentation outlines the operations available for managing Removable Mac Addresses within Jamf Pro using the Classic API, which supports XML data structures.

Operations

Summary

Jamf Pro Classic API - Restricted Software

This documentation outlines the operations available for managing Restricted Software within Jamf Pro using the Classic API, which supports XML data structures.

Operations

Summary

Jamf Pro Classic API - Software Update Servers

This documentation outlines the operations available for managing Software Update Servers within Jamf Pro using the Classic API, which supports XML data structures.

Operations

Summary

Jamf Pro Classic API - VPP Accounts

This documentation outlines the operations available for managing VPP (Volume Purchase Program) Accounts within Jamf Pro using the Classic API, which supports XML data structures.

Operations

Summary

Jamf Pro Classic API - Webhooks

This documentation outlines the operations available for managing Webhooks within Jamf Pro using the Classic API, which supports XML data structures.

Operations

Summary

Jamf Pro Classic API - Computer Checkin

This documentation outlines the operations available for managing Computer Checkin settings within Jamf Pro using the Classic API, which supports XML data structures.

Operations

Summary

Jamf Pro Classic API - GSX Connection

This documentation outlines the operations available for managing the GSX Connection settings within Jamf Pro using the Classic API, which supports XML data structures.

Operations

Summary

Jamf Pro Classic API - SMTP Server

This documentation outlines the operations available for managing SMTP Server settings within Jamf Pro using the Classic API, which supports XML data structures.

Operations

Summary

Jamf Pro Classic API - VPP Assignments

This documentation outlines the operations available for managing VPP Assignments within Jamf Pro using the Classic API, which supports XML data structures.

Operations

Summary

Progress Summary

Notes