DEV Community: Bryson Tyrrell

macOS Apps With Embedded Daemons

Bryson Tyrrell — Mon, 28 Apr 2025 19:02:45 +0000

I recently worked on a prototype for an assistive tool that requires root permissions for some of the tasks it would perform. Instead of writing something that would require being launched using sudo from a script or the command line, I wanted to explore what I consider to be the "most Apple" approach using modern APIs.

To me, the modern and Apple way involves:

A single app bundle - no actual need for an installer package or anything more complex to uninstall than dragging into the trash.
Using the SMAppService framework to handle registering and managing the daemon. This replaces older, more complicated methods like SMJobBless you can still find references to when searching.
Calling the daemon from the main app using secure, native interprocess communications over XPC services.

When you need a Daemon over a Agent

There are a lot of examples out there, and great ones from Apple's own developer docs, on doing what I set out to do with launch agents. Agents (and login items) run as the logged in user. Launch daemons are system level processes that run as the root user.

My entire use case is niche as my tool needs to interact with subprocesses that require root. I believe that the majority of the time we should all be fine using agents for this kind of background or async processing in our apps. Embedded agents are also much simpler to get up and running than embedded daemons.

To put it succinctly: ask if you truly need elevated permissions for what you want to accomplish. If you don't, don't use a daemon.

It's important to call out that agents and daemons cannot just register themselves. It is expected that users will be prompted to approve the background process or login item, and in the case of a daemon they need to authenticate as an admin.

The tool I was working on would have been distributed by our MDM solution and I would have automatically allowed the daemon to run via an MDM configuration profile. Know that if you don't have these mechanisms available you will have to manage user approval and navigate scenarios where you don't have it.

Create the Project in Xcode

As with all things, the only way to begin is by beginning. You don't need an Apple Developer Account for this barebones example, but it is recommended.

Open Xcode.
Create a new macOS "App" project.
1. Product Name: DaemonExample
2. Team: Select your team, or leave as None
3. Organization Identifier: Use com.example or set your own
4. Interface: SwiftUI
5. Language: Swift
6. Testing System: None
7. Storage: None
Create a new "Target" that is a macOS "Command Line Tool" (binary)
1. Product Name: Helper
2. Team: Select your team, or leave as None
3. Organization Identifier: Update to match the parent app's
  1. Bundle Identifier will display as: com.example.DaemonExample.Helper
4. Language: Swift
5. Project: DaemonExample

Create the Helper

The code used in this sample app is directly taken from the XPC project template using High Level - NSXPCConnection API. You can create one in a separate project as a reference to copy from, but don't add an XPC target in this project. Embedded XPC services like this are configured as and meant to be run as agents, not daemons.

LaunchDaemon Plist

Create a new empty file under the Helper directory called com.example.DaemonExample.Helper.
Edit using the plist form view or the raw file.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>BundleProgram</key>
    <string>Contents/Resources/Helper</string>
    <key>Label</key>
    <string>com.example.DaemonExample.Helper</string>
    <key>MachServices</key>
    <dict>
        <key>com.example.DaemonExample.Helper</key>
        <true/>
    </dict>
    <key>RunAtLoad</key>
    <true/>
</dict>
</plist>

BundleProgram points to the relative location in our app bundle for the helper's binary. MachServices is an older API we have to drop down to in order to register our helper with XPC. RunAtLoad will ensure this daemon loads during boot time (for agents this runs it at user login).

Now ensure this plist is included with the build.

Go to the Project > DaemonExample target > Build Phases.
Click the + button and select New Copy Files Phase.
In the new Copy Files section set the following on the new blank item:
1. Destination: Wrapper
2. Subpath: Contents/Library/LaunchDaemons
3. Click the + button and add the plist file
4. Check Code Sign On Copy for the file

Helper Protocol

The protocol is the contract (or rather, the API) for client-service communications. When the app connects to make a request it will use this protocol to perform the desired task. The HelperProtocol file needs to be added to the app's target so it is included during the build.

Create a new Swift file in the Helper called HelperProtocol.

import Foundation

/// The protocol that this service will vend as its API. This protocol will also need to be visible to the process hosting the service.
protocol HelperProtocol {

    /// Replace the API of this protocol with an API appropriate to the service you are vending.
    @objc func performCalculation(firstNumber: Int, secondNumber: Int, with reply: @escaping (Int) -> Void)
}

If you want, you can move this protocol file out of the Helper directory and into another directory that clearly shows it is shared code. The only requirement is that it is included in both targets

Create a new Swift file in the Helper called Helper (not confusing, I know).

import Foundation

/// This object implements the protocol which we have defined. It provides the actual behavior for the service. It is 'exported' by the service to make it available to the process hosting the service over an NSXPCConnection.
class Helper: NSObject, HelperProtocol {

    /// This implements the example protocol. Replace the body of this class with the implementation of this service's protocol.
    @objc func performCalculation(firstNumber: Int, secondNumber: Int, with reply: @escaping (Int) -> Void) {
        let response = firstNumber + secondNumber
        reply(response)
    }
}

This is the code that performs the actual work. It is only included with the Helper target. When we want to add new functionality to the Helper we add it to this class and add a corresponding entry to the protocol.

main

Update the main file with the code below. Again, this is take directly from Apple's template code for an XPC service but with logging added.

import Foundation
import os

let logger = Logger(subsystem: "com.example.DaemonExample.Helper", category: "Default")

class ServiceDelegate: NSObject, NSXPCListenerDelegate {

    /// This method is where the NSXPCListener configures, accepts, and resumes a new incoming NSXPCConnection.
    func listener(_ listener: NSXPCListener, shouldAcceptNewConnection newConnection: NSXPCConnection) -> Bool {
        logger.info("Received new connection request")

        newConnection.interruptionHandler = {
            // Handle interrupted connections here
            logger.error("Connection interrupted")
        }

        newConnection.invalidationHandler = {
            // Handle invalidated connections here
            logger.error("Connection invalidated")
        }

        // Configure the connection.
        // First, set the interface that the exported object implements.
        newConnection.exportedInterface = NSXPCInterface(with: HelperProtocol.self)

        // Next, set the object that the connection exports. All messages sent on the connection to this service will be sent to the exported object to handle. The connection retains the exported object.
        let exportedObject = Helper()
        newConnection.exportedObject = exportedObject

        // Resuming the connection allows the system to deliver more incoming messages.
        newConnection.resume()

        // Returning true from this method tells the system that you have accepted this connection. If you want to reject the connection for some reason, call invalidate() on the connection and return false.
        logger.info("Connection configured and resumed")
        return true
    }
}

// Create the delegate for the service.
let delegate = ServiceDelegate()
logger.info("Delegate created")

// Create and start the listener
let listener = NSXPCListener(machServiceName: "com.example.DaemonExample.Helper")
logger.info("Listener created")
listener.delegate = delegate

// Resuming the serviceListener starts this service. This method does not return.
listener.resume()
logger.info("Listener resumed")

// Keep the main run loop running
RunLoop.current.run()

Info.plist and Signing

Go to the Project > Helper binary target > Signing & Capabilities.
In the top section set Bundle Identifier to com.example.DaemonExample.Helper

The macOS section will change removing its Bundle Identifier field.

Go to Build Settings
Scroll to the Packaging section.
Update the following values.
1. Create Info.plist Section in Binary: Yes
2. Generate Info.plist File: Yes
3. Info.plist Output Encoding: binary

Embedding the Helper

Go to the Project > DaemonExample app target > Build Phases.

First add the Helper as a dependency in the build.

In the Target Dependencies section click the + button.
Select DaemonExample/Helper and click Add.

Now include the resulting build of the Helper in the app's bundle resources.

In the Copy Bundle Resources section click the + button.
Select Products/Helper and click Add.

The App

Most of the code below is defining the user interface of the app - which runs as the user. There are a couple lines to show the status of the Helper and some controls to manage it and check the state (which outputs into the log stream).

Once the Helper is registered and loaded additional inputs will be revealed for the addition operation it performs. The result will be output at the bottom of the window.

Remember this will require the user granting permission for it to run in the background.

Replace the contents of the ContentView file with the following.

import ServiceManagement
import SwiftUI

struct ContentView: View {
    let helperServiceName = "com.example.DaemonExample.Helper"
    var helperServicePlist: String {
        helperServiceName + ".plist"
    }

    @State private var helperRegistered: Bool = false
    @State private var helperApproved: Bool = false

    @State private var testResult: Int?

    var body: some View {
        VStack {
            HStack {
                Text("Helper Is Registered:")
                Image(systemName: helperRegistered ? "checkmark.square.fill" : "x.square.fill")
                    .foregroundColor(helperRegistered ? Color.green : Color.red)
            }

            HStack {
                Text("Helper Is Approved:")
                Image(systemName: helperApproved ? "checkmark.square.fill" : "x.square.fill")
                    .foregroundColor(helperApproved ? Color.green : Color.red)
            }

            Button("Register Helper Daemon Service") {
                print("Registering \(helperServicePlist)")
                let service = SMAppService.daemon(plistName: helperServicePlist)

                do {
                    try service.register()
                    print("Successfully registered \(service)")
                    checkHelperStatus()
                } catch {
                    print("Unable to register \(error)")
                }
            }

            Button("Unregister Helper Daemon Service") {
                print("Unregistering \(helperServicePlist)")
                let service = SMAppService.daemon(plistName: helperServicePlist)

                do {
                    try service.unregister()
                    print("Successfully unregistered \(service)")
                    helperRegistered = false
                    helperApproved = false
                    testResult = nil
                } catch {
                    print("Unable to unregister \(error)")
                }
            }

            Button("Check Helper Status") {
                checkHelperStatus()
            }

            if helperRegistered && helperApproved {
                Button("Test Helper") {
                    print("TEST: Sending Helper Request")

                    let connection = NSXPCConnection(machServiceName: helperServiceName)
                    print("TEST: Connection: \(connection)")

                    connection.remoteObjectInterface = NSXPCInterface(with: HelperProtocol.self)
                    connection.interruptionHandler = {
                        print("TEST: XPC connection interrupted")
                    }
                    connection.invalidationHandler = {
                        print("TEST: XPC connection invalidated")
                    }
                    connection.resume()
                    print("TEST: Connection resumed")

                    if let proxy = connection.remoteObjectProxy as? HelperProtocol {
                        print("TEST: Proxy: \(proxy)")
                        proxy.performCalculation(firstNumber: 23, secondNumber: 19) { result in
                            print("Result of calculation is: \(result)")
                            testResult = result
                        }
                        print("TEST: Done")
                    }

                    // connection.invalidate()
                }
            }

            if testResult != nil {
                Text("Test Result: \(testResult!)")
            }
        }
        .padding()
        .navigationTitle("LaunchDaemon Testing")
        .onAppear() {
            checkHelperStatus()
        }
    }

    func checkHelperStatus() {
        print("Checking Helper Daemon Service Status")
        let service = SMAppService.daemon(plistName: helperServicePlist)
        print("Helper Daemon Service Status: \(service.status)")

        if service.status == .enabled {
            print("Helper Daemon Service is enabled")
            helperRegistered = true

            if service.status == .requiresApproval {
                print("Helper Daemon Service requires approval")
                SMAppService.openSystemSettingsLoginItems()
            } else {
                print("Helper Daemon Service is approved")
                helperApproved = true
            }
        }
    }
}

The Test Helper button contains all of the code to connect to the daemon over XPC and then invoke it via the protocol defined before. The key line is here:

if let proxy = connection.remoteObjectProxy as? HelperProtocol {

The HelperProtocol is being used for the proxy object and all of the methods our daemon accepts are exposed for use in a type safe manner.

Remember, this code is directly taken from the XPC project template using High Level - NSXPCConnection API. Check out Apple's docs for a deep dive into this.

Securing the Helper

Not covered in the example above is locking down communication to our Helper to only the app. In some cases you might want to design a background tool in this way so it is usable across many apps, but I do not recommend leaving it completely open.

As this example is a daemon running with root permissions you should never allow just any process to call it.

In the main file for the Helper we can add code that will perform a codesigning check on the caller and reject mismatches. The ellipsis (...) indicate skipped code from the full example earlier in this post.

class ServiceDelegate: ...
    func listener(_ listener: ...
        ...
        let exportedObject = Helper()
        newConnection.exportedObject = exportedObject

         // Only allow connections from the main app
         let requirement = "identifier \"com.example.DaemonExample\" and anchor apple generic and certificate leaf[subject.CN] = \"Apple Development: me@mac.com (<Team ID>)\""
         newConnection.setCodeSigningRequirement(requirement)

        newConnection.resume()
        ...
    }
}

This anchor string can be made as loose or as specific as you need for your goals. This code requirement string represents basic check against an individual Apple Developer account.

On the Hardened Runtime & App Sandbox

For most apps you should always have the hardened runtime and app sandboxes enabled in your projects. These are platform security features and are good things.

For my tool, which I stated is a niche case, my daemon would have been running shell commands as root which means I would need to remove the app sandbox as sandboxed apps are not allowed to do this.

These two capabilities are set for each target in Xcode. If the app is sandboxed the helper must also be sandboxed. If your helper isn't sandboxed your app can't be sandboxed.

If the app is sandboxed it must also have the App Groups capability for XPC communication to ensure the app and the Helper are using the same container and are allowed to communicate.

App Sandboxed	Helper Sandboxed	App Group Required?
Yes	Yes	Yes
No	No	No

Go to the Project > DaemonExample app target > Signing & Capabilities.
Click the + Capability button.
In the new App Groups section click the + button.

Apple has been making changes to how App Groups work. This forum post by an Apple engineer goes into detail on the topic and the changes to unify iOS/Mac App Groups as of Feb 2025.

For this example project change the default ${TeamIdentifierPrefix} value to com.example.DaemonExample. This will work, but it's not what you'll want to do in an app you intend to release.

Troubleshooting

Troubles do arise, and with background services it becomes trickier because their output will not appear in Xcode. Only the main app's logs will.

The below log commands will help you debug issues registering and running your background service. This is one of the times where I will whole heartedly endorse the use of an LLM: they are great and taking verbose log output and telling you what you're looking at and possible causes.

SMAppService

Stream logs relevant to service registration.

sudo log stream --debug --info --predicate "process in { '<my process>', 'smd', 'backgroundtaskmanagementd'} and sender in {'ServiceManagement', 'BackgroundTaskManagement', 'smd', 'backgroundtaskmanagementd'}"

Taken from an Apple Framework Engineer's post on the Developer Forums.

Helper Logs

sudo log show --debug --predicate 'eventMessage CONTAINS "com.example.DaemonExample.Helper"' --last 30s

Using the Swift OpenAPI Generator for the Jamf Pro API

Bryson Tyrrell — Mon, 26 Aug 2024 17:35:53 +0000

For the past several months I have been learning Swift and SwiftUI and have finally reached the point where I want to build a few small, but capable apps to start putting together my new skills. One of these ideas requires interacting with the Jamf Pro API. I had not done much with network code at this point, but I remembered a session from WWDC 2023 that I was very interested in: Meet Swift OpenAPI Generator.

These Swift packages create API clients and code models from OpenAPI documents. This is an approach known as "spec-driven development." While it's not a lot of work to get a few API requests written using URLSession, there's a lot more effort that goes into the interfaces for those operations, and even more work to write the models that the responses become.

My approach to learning Swift has also been to focus on where we are going as platform engineers, and using OpenAPI to drive client code feels like the most correct approach.

There's a bit of process to get through.

Xcode Setup: Install the Swift OpenAPI packages required and configure the build settings.
OpenAPI Doc: Copy the Jamf Pro OpenAPI document, update it, and configure the generator.
Auth Middleware: Requests need to be authenticated with an access token. This is handled by creating a middleware that will fetch and insert tokens into client requests.
Client Code: The generated client needs to be configured so that it can be used in the main application.

It is a bit of work up front, but I'll showcase the benefits with a small example app, and how to extend these resources further.

This entire example project is now available on my GitHub.

The OpenAPI Generator

You will first need to install three packages using the Swift Package Manager. There is no central repository for packages with Swift as you might expect with languages like Python and Javascript. Swift packages are shared through git repositories. From the menu bar, select File > Add Package Dependencies... This brings up Xcode's interface for the package manager.

There is a default collection of Apple Swift Packages in the sidebar. The OpenAPI packages are not included in this. You will need to copy and paste the GitHub URLs for three required packages into the search bar in the upper-right. I have provided them below:

Plugin: https://github.com/apple/swift-openapi-generator This package plugin is what will generate all of the client and type code from the OpenAPI document each time you build your project.
Runtime: https://github.com/apple/swift-openapi-runtime This package contains functionality used by the generated client code.
Transport: https://github.com/apple/swift-openapi-urlsession Transports are what performs the HTTP operations for your client. This transport uses URLSession. There is another available for the AsyncHTTPClient package.

When viewing a package you will see the Dependency Rule defaults to Up to Next Major Version. Swift packages follow semantic versioning. Each Swift OpenAPI package is at major version 1 at the time of this post. This dependency rule will pull in all updates for those packages up until they move to the next major version (2).

This is a sane default for your dependencies and I recommend keeping it.

For each package, paste in the URL to the search and click Add Package. There will be a pop-up window asking you to add package products to targets in your project.

When you install the Plugin there will be two products listed. Do not add them (leave at None).

When you install the Runtime and Transport they contain one product each and both should be added to your project's target.

In Xcode's sidebar a new Package Dependencies section will appear below your project files. It will list every package installed into your project. You'll notice that there are a lot more than the three you just added. These are sub-dependencies the OpenAPI packages rely on.

Now the OpenAPI plugin must be added to the project target's build phase. Navigate back to the project settingstarget. Go to the Build Phases section and expand Run Build Tool Plug-ins. Click the + button. In the pop-up window you will see under the swift-openapi-generator package a OpenAPIGenerator item with a bullseye icon. Select this and click Add.

Expand the Link Binary With Libraries section below and you should see both OpenAPIRuntime and OpenAPIURLSession already listed. This was done when you added the package products to the target.

The Xcode project is now setup and ready for the API client.

Jamf Pro OpenAPI Doc

This post will only cover the Pro API and not the Classic API.

Any Jamf Pro server has the OpenAPI document for its version available at the following URL:

https://<instance-name>.jamfcloud.com/api/schema/

As of version 11.7.1, this JSON file is 1.5 MB in size and over 45,000 lines long. If you tried to build the client using this raw file you're going to encounter errors. and then encounter new errors as you start to patch them over.

Some of these errors are due to the Swift OpenAPI Generator not supporting an option that was defined, but most are errors when Jamf generated the document.

In the Appendix of this blog post I will include guidance for how to correct the errors I encountered in the 11.7.1 Pro OpenAPI doc.

There are still two remaining issues with Jamf's OpenAPI doc to address before using it to generate client code.

For the overwhelming majority of paths there is no operationId. The OpenAPI generator would use this to create the method name in the client. Without this, it will autogenerate names that look like this: get_sol_v1_sol_computers_hyphen_inventory. That is the default generated name for GET /v1/computers-inventory. It makes for hard to read and hard to discover code.

The other issue is you are generating client code for hundreds of API endpoints that you will not use, and likely would never use. The generated Client file for the full OpenAPI doc was 57,000+ lines long, and the generated Types file a staggering 155,500+ lines. ~10 MB of unused Swift code.

The missing operationId properties can be manually addressed. For the APIs you intend to use you would add them into the path objects like so:

{
...
"/v1/computers-inventory" : {
  "get" : {
    "operationId": "ComputersInventoryGetV1",
    ...
}

The naming scheme I recommend is {Path}{Method}{Version} in capital-case without spaces, underscores, or hyphens as shown above. This naming scheme makes it easy to see all of the available methods and versions of an API when Xcode shows autocompletion options as you type.

The challenge of the large number of APIs you don't intend to use is addressed by properly configuring the OpenAPI generator.

I have also tried creating a minimal OpenAPI document using openapi-extract to pull out the paths and schemas I wanted. I could then manually merge them into a single file after. This is, however, a very manual process, and it is a Javascript command line tool with very little instruction on how to setup.

Plugin Configuration

The next file you are going to add will be openapi-generator-config.yaml with the following contents:

generate:
  - client
  - types
filter:
  paths:
    - /v1/computers-inventory
    - /v1/jamf-pro-version

This file will instruct the generator to create client code from the OpenAPI doc and Swift types from the schemas. The types are critically important. These will be Swift structs returned by the client operations with properties that can be accessed through dot notation. Xcode's autocomplete will show all of the possible values as you type making interacting with the response data simple and easy.

The third option for generate is server. You can create all of the stubs for the API itself using a web framework like Vapor. This will be worth exploring another day.

The filter property will only generate code for items that match the criteria. In the example above I am only asking for two APIs. At any time you can add additional paths to expand the capabilities of the client code.

Less code is the best code.

The First Build

Without adding a single Swift file you can now attempt the first build.

Go to the menu bar and select Product > Build or press ⌘ + B on your keyboard. For the very first time you use the plugin a dialog will appear asking for confirmation that you trust it. To continue, click Trust & Enable All.

If you encounter build errors at this step you will need to investigate the Issue and Reports navigators to find the cause. If there are errors related to the OpenAPI doc jump to the bottom of the blog in the Appendix where I have a section on how to address errors I encountered.

Sometimes your changes to the OpenAPI doc won't reflect correctly in your code when you rebuild. You can clean the build caches by pressing ⌘ + ⌥ + ⇧ + K.

The Client Code

The generated Client, Operations, and Components objects are now available to import.

Were this API unauthenticated the Client could be used directly, but Jamf Pro requires authentication with an access token. The example in this post is going to focus on authentication using client credentials flow using a Jamf Pro API Client.

Press ⌘ + N and create a new Swift file in your project called JamfAPIClient.swift.

Add these imports:

// JamfAPIClient.swift

import Foundation
import HTTPTypes
import OpenAPIRuntime
import OpenAPIURLSession

A wrapper struct will be needed to handle all of the configuration and token management boilerplate code. This will become the main interface for the Jamf Pro API instead of using the Client directly.

struct JamfProAPIClient {
    let api: Client

    let clientId: String
    private let clientSecret: String

    init(hostname: String, clientID: String, clientSecret: String) {
        self.clientId = clientID
        self.clientSecret = clientSecret
        self.api = Client(
            serverURL: URL(string: "https://\(hostname):443/api")!,
            configuration: Configuration(dateTranscoder: .iso8601WithFractionalSeconds),
            transport: URLSessionTransport()
        )
    }
}

Where the inner Client is being instantiated a URL concatenated together from the passed hostname. The URLSessionTransport is the one installed with swift-openapi-urlsession package.

The Configuration being passed sets a different date transcoder than the default. Date strings in Jamf Pro contain fractional seconds*. This needs to be set or else decoding errors will occur for timestamps that include them.

Configuration(dateTranscoder: .iso8601WithFractionalSeconds)

See the Appendix for issues I encountered with ISO8601 date string decoding.

With all the work for setup now handled by the wrapper, here is the new client in action:

// Example use
let client = JamfProAPIClient(
    hostname: "dummy.jamfcloud.com",
    clientID: "43fd12fc...",
    clientSecret: "Fn96LFQP..."
)

print(client.clientId) // Inspect and identify clients

let jamfProVersion = try await client.api.JamfProVersionGetV1()

Adding Authentication

The code thus far does not yet include authentication. To do this a middleware must be created that handles obtaining access tokens using the client credentials and injecting that token into the requests. It should also cache the token, reusing it for its lifetime, and refresh the token in a way that is thread-safe.

The ClientMiddleware protocol allows custom code for inspecting and modifying requests before they are sent to the transport. Multiple middlewares can be passed to a client to handle different operations like logging, header manipulation, and authentication.

This is the minimal code to start:

struct APIClientMiddleware: ClientMiddleware {
    // Store the access token here
    func intercept(
        _ request: HTTPRequest,
        body: HTTPBody?,
        baseURL: URL,
        operationID: String,
        next: (HTTPRequest, HTTPBody?, URL) async throws -> (HTTPResponse, HTTPBody?)
    ) async throws -> (HTTPResponse, HTTPBody?) {
        var request = request
        // Retrieve and inject the access token here
        return try await next(request, body, baseURL)
    }
}

Because this is conforming to a protocol, Xcode can autocomplete the entire signature for intercept for you as you type.

The comments identify where the code for the token needs to be added. Before writing the code that calls POST /api/oauth/token there needs to be an object to store the token data from the response and evaluate if it is still valid.

This struct is written to be instantiated from the JSON response for client credentials authentication:

struct AccessToken: Codable {
    let access_token: String
    let expires_in: Int
    let expiration_date: Date

    var isExpired: Bool {
        return expiration_date < Date()
    }

    init(from decoder: any Decoder) throws {
        let container = try decoder.container(keyedBy: CodingKeys.self)
        self.access_token = try container.decode(String.self, forKey: .access_token)
        self.expires_in = try container.decode(Int.self, forKey: .expires_in)
        self.expiration_date = Date().addingTimeInterval(Double(expires_in))
    }
}

isExpired is a computed property that will return true if the calculated expiration exceeds the current time when it is called.

Because both the client and the middleware are asynchronous there is a risk of a race condition where multiple threads attempt to refresh the token at the same time. Implementing the AccessTokenManager as an Actor will help address this.

Actors are like classes, but access to their properties and methods are serialized. If multiple threads performing requests all trigger the creation of a new token only one needs to occur and the rest will queue until they retrieve the newly cached token.

actor AccessTokenManager {
    private let tokenURL: URL
    private let clientId: String
    private let clientSecret: String

    var currentToken: AccessToken?
    var activeTokenTask: Task<AccessToken, Error>?

    init(tokenURL: URL, clientId: String, clientSecret: String) {
        self.tokenURL = tokenURL
        self.clientId = clientId
        self.clientSecret = clientSecret
    }
}

The AccessTokenManager will take in the URL to request tokens from, the client ID, and client secret. Internally, it will store the current access token using the struct from above, and a Task. The task will be used to control concurrency on retrieving tokens.

The token manager requires its own network code apart from the API client. This is a custom error that will be throw if any part of the token requests fail:

enum JamfProAPIClientError: Error {
    case AuthError(String)
}

The method to request access tokens will look similar to many other examples of URLSession you may have seen. It is also a look at the verbose code we want to avoid having to write. Every API would require data model code (the AccessToken struct above), and HTTP request code.

This code follows Jamf's recipe for client credentials auth on the developer portal.

func requestAccessToken() async throws -> AccessToken {
    var request = URLRequest(url: tokenURL)

    request.httpMethod = "POST"

    request.setValue("application/json", forHTTPHeaderField: "Accept")
    request.setValue("application/x-www-form-urlencoded", forHTTPHeaderField: "Content-Type")

    var body = URLComponents()
    body.queryItems = [
        URLQueryItem(name: "grant_type", value: "client_credentials"),
        URLQueryItem(name: "client_id", value: clientId),
        URLQueryItem(name: "client_secret", value: clientSecret)
    ]
    request.httpBody = body.query?.data(using: .utf8)

    let (data, response) = try await URLSession.shared.data(for: request)

    guard let httpResponse = response as? HTTPURLResponse else {
        throw JamfProAPIClientError.AuthError("Token request failed with response: \(response)")
    }

    if httpResponse.statusCode != 200 {
        throw JamfProAPIClientError.AuthError("Token request failed with status code: \(httpResponse.statusCode)")
    }

    guard let newAccessToken = try? JSONDecoder().decode(AccessToken.self, from: data) else {
        throw JamfProAPIClientError.AuthError("Failed to decode access token: \(data)")
    }

    return newAccessToken
}

Now the interface for thread-safe token requests. getAccessToken will be called by the middleware to return the current valid token that has been cached.

func getAccessToken() async throws -> AccessToken {
    if let activeTokenTask {
        return try await activeTokenTask.value
    }

    if let currentToken, currentToken.isExpired {
        return currentToken
    }

    activeTokenTask = Task {
        try await requestAccessToken()
    }

    guard let newToken = try await activeTokenTask?.value else {
        throw JamfProAPIClientError.AuthError("Failed to return access token")
    }
    currentToken = newToken
    activeTokenTask = nil

    return newToken
}

Here is a breakdown of the logic above:

Check if there is an active task. If there is, another thread is requesting a new access token and this one will wait for it to complete and return the value.
Check if there is a current token and that it is not expired. If the token exists and is valid it will be returned.
If neither of the above conditions are met a new token will be requested and returned.

Here is the complete AccessTokenManager:

actor AccessTokenManager {
    private let tokenURL: URL
    private let clientId: String
    private let clientSecret: String

    var currentToken: AccessToken?
    var activeTokenTask: Task<AccessToken, Error>?

    init(tokenURL: URL, clientId: String, clientSecret: String) {
        self.tokenURL = tokenURL
        self.clientId = clientId
        self.clientSecret = clientSecret
    }

    func getAccessToken() async throws -> AccessToken {
        if let activeTokenTask {
            return try await activeTokenTask.value
        }

        if let currentToken, currentToken.isExpired {
            return currentToken
        }

        activeTokenTask = Task {
            try await requestAccessToken()
        }

        guard let newToken = try await activeTokenTask?.value else {
            throw JamfProAPIClientError.AuthError("Failed to return access token")
        }
        currentToken = newToken
        activeTokenTask = nil

        return newToken
    }

    func requestAccessToken() async throws -> AccessToken {
        var request = URLRequest(url: tokenURL)

        request.httpMethod = "POST"

        request.setValue("application/json", forHTTPHeaderField: "Accept")
        request.setValue("application/x-www-form-urlencoded", forHTTPHeaderField: "Content-Type")

        var body = URLComponents()
        body.queryItems = [
            URLQueryItem(name: "grant_type", value: "client_credentials"),
            URLQueryItem(name: "client_id", value: clientId),
            URLQueryItem(name: "client_secret", value: clientSecret)
        ]
        request.httpBody = body.query?.data(using: .utf8)

        let (data, response) = try await URLSession.shared.data(for: request)

        guard let httpResponse = response as? HTTPURLResponse else {
            throw JamfProAPIClientError.AuthError("Token request failed with response: \(response)")
        }

        if httpResponse.statusCode != 200 {
            throw JamfProAPIClientError.AuthError("Token request failed with status code: \(httpResponse.statusCode)")
        }

        guard let newAccessToken = try? JSONDecoder().decode(AccessToken.self, from: data) else {
            throw JamfProAPIClientError.AuthError("Failed to decode access token: \(data)")
        }

        return newAccessToken
    }
}

And here it is integrated back into the APIClientMiddleware:

struct APIClientMiddleware: ClientMiddleware {
    let accessTokenManager: AccessTokenManager

    init(accessTokenManager: AccessTokenManager) {
        self.accessTokenManager = accessTokenManager
    }

    func intercept(
        _ request: HTTPRequest,
        body: HTTPBody?,
        baseURL: URL,
        operationID: String,
        next: (HTTPRequest, HTTPBody?, URL) async throws -> (HTTPResponse, HTTPBody?)
    ) async throws -> (HTTPResponse, HTTPBody?) {
        guard let accessToken = try? await accessTokenManager.getAccessToken() else {
            throw JamfProAPIClientError.AuthError("Failed to fetch access token")
        }

        var request = request
        request.headerFields[.authorization] = "Bearer \(accessToken.access_token)"

        return try await next(request, body, baseURL)
    }
}

The complete middleware solution can now be passed to the client code:

struct JamfProAPIClient {
    public let api: Client

    let clientId: String
    private let clientSecret: String

    init(hostname: String, clientID: String, clientSecret: String) {
        self.clientId = clientID
        self.clientSecret = clientSecret
        self.api = Client(
            serverURL: URL(string: "https://\(hostname):443/api")!,
            configuration: Configuration(dateTranscoder: .iso8601WithFractionalSeconds),
            transport: URLSessionTransport(),
            middlewares: [
                APIClientMiddleware(
                    accessTokenManager: AccessTokenManager(
                        tokenURL: URL(string: "https://\(hostname):443/api/oauth/token")!,
                        clientId: clientID,
                        clientSecret: clientSecret
                    )
                )
            ]
        )
    }
}

Using the Client

Now that all of the work for setting up and creating the Jamf Pro API client is done it is time to put it to use and demonstrate how powerful the Swift OpenAPI Generator is.

Below is a small SwiftUI app using the JamfProAPIClient above to render a list of computers displaying their names, the management ID, and the assigned user. It also displays the total number of computers at the top.

Here is the complete code:

// ContentView.swift

import SwiftUI

struct ContentView: View {
    @State private var client = JamfProAPIClient(
        hostname: "dummy.jamfcloud.com",
        clientID: "43fd12fc...",
        clientSecret: "Fn96LFQP..."
    )

    @State private var computerSearchResults: Components.Schemas.ComputerInventorySearchResults?

    var body: some View {
        List {
            Section {
                HStack {
                    Text("Total computers:")
                        .font(.headline)
                    Spacer()
                    Text(String(computerSearchResults?.totalCount ?? 0))
                }
            }

            Section {
                if let computerResults = computerSearchResults?.results {
                    ForEach(computerResults, id: \.self) { computer in
                        VStack(alignment: .leading) {
                            Text("\(computer.general?.name ?? "Unknown") | \(computer.id!)")
                                .font(.headline)
                            Text(computer.general?.managementId ?? "Unknown")
                                .font(.caption)
                                .textSelection(.enabled)
                            HStack {
                                Text("Assigned User:")
                                Text(computer.userAndLocation?.username ?? "Unkown")
                            }
                        }
                    }
                }
            }
        }
        .task {
            do {
                let response = try await client.api.ComputersInventoryGetV1(
                    .init(
                        query: .init(
                            section: [.GENERAL, .USER_AND_LOCATION],
                            page: 0,
                            page_hyphen_size: 1000
                        )
                    )
                )
                computerSearchResults = try response.ok.body.json
            } catch {
                print(error.localizedDescription)
            }
        }
    }
}

The client is instantiated as a property of the view struct. The other property is to hold the response of the GET /v1/computers-inventory API. Components contains generated types from the OpenAPI doc. It follows the same structure and names as the components object in the doc.

@State private var computerSearchResults: Components.Schemas.ComputerInventorySearchResults?

The view will automatically load data into computerSearchResults at launch. The task modifier contains the client call to ComputersInventoryGetV1.

let response = try await client.api.ComputersInventoryGetV1(
    .init(
        query: .init(
            section: [.GENERAL, .USER_AND_LOCATION],
            page: 0,
            page_hyphen_size: 1000
        )
    )
)
computerSearchResults = try response.ok.body.json

For the sake simplicity this code is embedded with the .task {}. A better, more organized approach would be to move this its own function and call that.

This is a very elegant interface to what is a fairly complex API. GET /v1/computers-inventory uses query string parameters to control and filter the returned computers. The sections are parts of the computer object to include. In code it takes an array ComputerSection enums that have all of the valid values because it was generated from the OpenAPI definition.

Imagine having to code all of this by hand.

response.ok.body.json returns the ComputerInventorySearchResults type. Once this happens the SwiftUI code will automatically render the list.

if let computerResults = computerSearchResults?.results {
    ForEach(computerResults, id: \.self) { computer in
        VStack(alignment: .leading) {
            Text("\(computer.general?.name ?? "Unknown") | \(computer.id ?? "Unknown")")
                .font(.headline)
            Text(computer.general?.managementId ?? "Unknown")
                .font(.caption)
                .textSelection(.enabled)
            HStack {
                Text("Assigned User:")
                Text(computer.userAndLocation?.username ?? "Unkown")
            }
        }
    }
}

The results property is an array of ComputerInventory types. If the results have been loaded, the ForEach loop will display a row for every computer. All of the information that is being displayed is being accessed through dot notation on the record.

Because most properties in the Jamf Pro OpenAPI schemas are optional (meaning it may be null / nil) nil coalescing using ?? is needed to provide a default value if it cannot be read.

Note that computerResults does not conform to Identifiable. This appears to be the case for any array in the generated types, and this would be expected as the generator cannot guarantee that the contained items are unique.

Extending the Client

Now that you have seen how easy it is to use the Jamf Pro API after creating a client using the OpenAPI generator, let's see how easy it is to extend this foundation with new capabilities.

First, new APIs can be included with the client by adding them to the filter of the openapi-generator-config.yaml.

generate:
  - client
  - types
filter:
  paths:
    - /v1/computers-inventory
    - /v1/computers-inventory-detail/{id}
    - /v1/jamf-pro-version

Now in code a single, full computer record can be requested by its ID:

let response = try await client.api.ComputersInventoryDetailByIdGetV1(
    .init(
        path: .init(
            id: "117"
        )
    )
)

You may be wondering about the shorthand inits that are happening, and why there are so many of them. It may make more sense if you see the full names for the same method call:

let response = try await client.api.ComputersInventoryDetailByIdGetV1(
    Operations.ComputersInventoryDetailByIdGetV1.Input.init(
        path: Operations.ComputersInventoryDetailByIdGetV1.Input.Path.init(
            id: "117")
    )
)

Every API request's input and response are defined as types, and those objects define all of the possible options as types. GET /v1/computers-inventory-details/{id} takes a path argument as a string - the computer ID. When writing the request using the OpenAPI client each of these types must be instantiated. Swift provides shorthand syntax to spare you all of that verbose typing.

Go back and take another look at ComputersInventoryGetV1 with this newfound knowledge.

Extending OpenAPI

Missing or undocumented APIs can also be added to the OpenAPI doc and be made available in the client. The POST /api/oauth/token endpoint used by the AccessTokenManager is not documented. While all of the code in the token manager is available, it would be more convenient to have a method to request arbitrary tokens as needed.

Here is the OpenAPI JSON for the token endpoint:

{
  "paths": {
    "/oauth/token": {
      "post": {
        "operationId": "AccessTokenRequest",
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "required": [
                  "client_id",
                  "client_secret",
                  "grant_type"
                ],
                "properties": {
                  "client_id": {
                    "type": "string"
                  },
                  "client_secret": {
                    "type": "string"
                  },
                  "grant_type": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "access_token": {
                      "type": "string"
                    },
                    "expires_in": {
                      "type": "integer"
                    },
                    "scope": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

This can be added to the top of the paths object in the OpenAPI doc. Once added, trigger a new build and the API method will be available. Scroll back to the AccessTokenManager to remember the code required for that single URLSession request.

Now compare to the new AccessTokenRequest method:

let response = try await client.api.AccessTokenRequest(
    body: .urlEncodedForm(
        .init(
            client_id: clientId,
            client_secret: clientSecret,
            grant_type: "client_credentials"
        )
    )
)
return try response.ok.body.json.access_token

All our code should be so pleasant.

Helper Methods

The earlier example usage of ComputersInventoryGetV1 set the page size to 100, but the total count for all computers was 101. New APIs in the Jamf Pro API are paginated and in larger datasets repeat calls are required to obtain the full result.

Below is a method I wrote and added to the JamfProAPIClient that wraps ComputersInventoryGetV1, detects if there are more computers reported for the total than have been returned, and loops requests until it has exhausted all possible pages of the original query.

func ComputerInventoryGetV1AllPages(
    query: Operations.ComputersInventoryGetV1.Input.Query = .init(page: 0, page_hyphen_size: 2000)
) async throws -> Components.Schemas.ComputerInventorySearchResults {
    var currentPage = max(query.page ?? 0 - 1, -1)
    var computerResults = Components.Schemas.ComputerInventorySearchResults(totalCount: 1, results: [])

    while computerResults.results!.count < computerResults.totalCount! {
        currentPage += 1

        let nextPage = try await api.ComputersInventoryGetV1(
            .init(
                query: .init(
                    section: query.section,
                    page: currentPage,
                    page_hyphen_size: query.page_hyphen_size,
                    sort: query.sort,
                    filter: query.filter
                )
            )
        )

        let nextPageResults = try nextPage.ok.body.json

        computerResults.totalCount = nextPageResults.totalCount ?? 0

        if nextPageResults.results!.count == 0 {
            return computerResults
        } else {
            computerResults.results?.append(contentsOf: nextPageResults.results!)
        }
    }

    return computerResults
}

There are a lot of force unwraps ! in this code for the totalCount and results of the inventory response. This is intentional: those values are guaranteed to exist. Neither of these can actually ever be nil/null. The API will return a 0 and an empty array if there aren’t any results.

Most of the Pro API schemas do not list required properties. This defines which properties are not optional and must be present. This applies to both writes and reads. On the ComputerInventory schema you'll find that the id, another known guaranteed property, is not marked as required and thus becomes an optional in the generated struct.

The task code that automatically loads the list of computers can now call this and be guaranteed to fetch the entire inventory for display.

computerSearchResults = try await client.ComputerInventoryGetV1AllPages(
    query: .init(
        section: [.GENERAL, .USER_AND_LOCATION]
    )
)

Note that for this helper method I reused Operations.ComputersInventoryGetV1.Input.Query so Xcode would provide the same autocompletion and help text as the lower-level non-paginated call.

Schema Extensions

Earlier in the example app code I explained that by default the generated types from the OpenAPI generator do not conform to Identifiable. The line that loops over the results to display them requires setting the id argument:

ForEach(computerResults, id: \.self) { computer in
    // View code here
}

My friend Nindi pointed out that this can be fixed by using an Extension. The ComputerInventory types all have id attributes and will automatically fulfill the requirements for Identifiable (as will any other Jamf schema that includes an id).

This is all the code that is needed to add the protocol:

//  Extensions+Components.Schemas.swift

extension Components.Schemas.ComputerInventory: Identifiable {}

Putting these in their own file is another best practice for code organization.

Now the ForEach loop can be simplified:

ForEach(computerResults) { computer in
    // View code here
}

What's Next?

Getting all of this working has been great "aha!" moment.

Even as I wrote this post I was going back and further simplifying and improving the original example code I had intended to share. Next I'll be taking all this work and applying back to another project I intend to bring to the App Store. I'll be updating this post with any new learnings from that.

If you are learning or using Swift and are trying out the steps in the guide for your own projects drop a comment and let me know!

Appendix

Fixing the OpenAPI Doc

These are the errors I encountered trying to build a client from the 11.7.1 Pro API OpenAPI doc and how I remediated them. Errors during the build will appear in the Reports navigator. The most recent report will be at the top. The Build has a hammer icon, and there should also be a yellow warning or red error symbol to the right. Select this to view those logs.

Invalid content type string...
There were two .../history APIs where Jamf generated an invalid content-type label for the 200 responses. Instead of documenting two types of responses they were concatenated together as text/csv,application/json. Edit these to just one of the types to clear the error.
Feature "Cookie params" is not supported...
The generator does not support cookie parameters. The PATCH /v2/account-preferences API has JSESSIONID as in the cookie. Delete this object.
warning: A property name only appears in the required list, but not in the properties map...
An API lists a required field that doesn't exist. There will be multiples of this and you will need to inspect the error message to get the location and the value. For example, context: foundIn=Components.Schemas.CloudLdapServerUpdate (#/components/schemas/CloudLdapServerUpdate)/providerName shows the schema at issue is CloudLdapServerUpdate and the property that's required but does not exist is providerName.
Invalid discriminator.mapping value... must be an internal JSON reference.
In the MdmCommandRequest the discriminator mapping still includes external file references. Those schemas all exist within the OpenAPI document. Remove all of the *.yaml prefixes.

Date Decoding Errors

Between two different Jamf Pro instances while testing I have encountered this issue in my console logs when returning device data:

Client error - cause description: 'Unknown', underlying error: DecodingError: dataCorrupted - at : Expected date string to be ISO8601-formatted.

I suspect this is an issue due to old, inconsistent formats for dates between the two. In one of the Jamf Pro instances a record had timestamps with and without the fractional seconds.

Here is the date transcoder I am using in this post's client configuration:

configuration: Configuration(dateTranscoder: .iso8601WithFractionalSeconds)

That sets up an ISO8601DateFormatter with the following options:

ISO8601DateTranscoder(options: [.withInternetDateTime, .withFractionalSeconds])

When .withFractionalSeconds is set it requires that all timestamps contain fractional seconds. Responses with mixed types of ISO8601 formats will throw the decoding error. To work around this, I wrote my own date transcoder based on the generator's that will attempt a factional decoding first, and fall back to non-fractional.

struct CustomDateTranscoder: DateTranscoder {
    private let lock: NSLock

    public init() {
        lock = NSLock()
    }

    public func encode(_ date: Date) throws -> String {
        lock.lock()
        defer { lock.unlock() }
        return Date.ISO8601FormatStyle(includingFractionalSeconds: true).format(date)
    }

    public func decode(_ dateString: String) throws -> Date {
        lock.lock()
        defer { lock.unlock() }
        do {
            return try Date.ISO8601FormatStyle(includingFractionalSeconds: true).parse(dateString)
        } catch {
            do {
                return try Date.ISO8601FormatStyle().parse(dateString)
            } catch {
                throw DecodingError.dataCorrupted(
                    .init(codingPath: [], debugDescription: "Expected date string '\(dateString)' to be ISO8601-formatted.")
                )
            }
        }
    }
}

This is a drop-in replacement for the builtin date transcoder:

configuration: .init(dateTranscoder: CustomDateTranscoder())

This custom date transcoder is also Swift 6 compliant. In Xcode 16 if you try to encode/decode using ISO8601DateFormatter (as the ISO8601DateTranscoder does) there will be a warning that it does not conform to Sendable.

Building project docs for GitHub Pages

Bryson Tyrrell — Mon, 28 Aug 2023 19:59:36 +0000

While working on publishing a new Python package, I wanted to publish the documentation built from the source code to GitHub Pages. This process has become much simpler and more streamlined than the last time I setup a workflow to do so (and that was building OpenAPI docs).

Disclaimer: as of the time of this post the method I'm using is still labeled as Beta, so ymmv).

This is a Python project and I'm using Sphinx for my docs. Below is the complete GitHub Actions YAML file that builds and publishes documentation for the project. I'm going to break down each section and describe the entire workflow.

name: Publish Documentation

on:
  push:
    branches:
      - 'main'
    paths:
      - 'docs/**'
      - 'src/**'

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:

  build:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v3

      - name: Setup Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.9'

      - name: Install Dependencies
        run: python3 -m pip install --editable '.[dev]'

      - name: Build Sphinx Docs
        run: sphinx-build -b html docs/ build/docs/

      - name: Upload Artifact
        uses: actions/upload-pages-artifact@v2
        with:
          path: 'build/docs/'

      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v2

Repository Setup

First, GitHub Pages needs to be setup for the repository. This is done in Settings -> Pages (in sidebar) -> Build and deployment. I am using GitHub Actions (Beta) and not deploying from a branch - the old method.

There also needs to be an Environment specifically for the GitHub Pages build. This was created by default for me in a new repo. Environments let you define additional rules and secrets around associated builds. The key thing here is that only the main branch is allowed for deployments of the docs.

Check Settings -> Environment (in sidebar) to see if you have a github-pages environment. If not, create one and add the main branch as the only deployment branch. For the workflow I'm describing here no other environment settings are required.

Trigger (On)

on:
  push:
    branches:
      - 'main'
    paths:
      - 'docs/**'
      - 'src/**'

In this project I made the decision that docs are always built on any push to main where changes have been made ion the docs/ and src/ directories. Any other changes (like to tests, the README, etc.) that don't impact the docs skips this.

The filtering options for branches and paths are powerful tools for preventing workflows from running when they shouldn't.

Permissions

permissions:
  contents: read
  pages: write
  id-token: write

For certain actions the workflow will need to be granted permissions to perform them. The possible permissions are documented here. There are three permissions I've granted to this workflow:

contents - Grants read access to the repository's contents. This was only required while the repository was set to private. Once switched to public this permission is no longer needed.
pages - This allows the workflow to request a GitHub Pages build.
id-token - The workflow will fetch an OIDC token. This permission is used for a lot of other GitHub Actions workflows (like PyPI publishing, or AWS IAM role assumption). Here it used to verify the deployment originates from an appropriate source.

I've defined permissions at a global level for the workflow, but you can also define permissions at the job level for more fine-grained access control.

Concurrency

concurrency:
  group: "pages"
  cancel-in-progress: false

This is a very handy control to remember for any workflow where you want to ensure only one instance is happening at any given moment. I don't want multiple commits to main to trigger multiple parallel docs builds. By setting a group label for the workflow and cancel-in-progress to false I now have a queue where each commit will build and publish in order.

Alternatively, if I set cancel-in-progress to true each subsequent commit to main will cancel any builds in progress in favor of the new one.

The Job

The workflow's job is comprised of a number of steps. The job itself has two keys set for configuration.

jobs:

  build:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest

environment - This defines which environment is used for the job.
name - The name of the environment. I've set github-pages to use the environment from earlier in setup.
url - This is the URL to the output of the job. As this is publishing to GitHub Pages the URL will be the link to the final docs (a static github.io URL). This syntax is referencing value from the outputs of a step with the ID deployment.
runs-on - The type of host the job will execute on. This is usually ubuntu-latest in most examples, and you should leave it as unless you have specific build needs.

Job Setup

    steps:
      - name: Checkout
        uses: actions/checkout@v3

      - name: Setup Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.9'

The first two steps are setting up the job's environment. The checkout action will checkout out the repository at the triggering ref. The setup-python action will setup the desired Python runtime. My package supports Python 3.9+ so I'm targeting the minimum version for my build environments.

Docs Build

      - name: Install Dependencies
        run: python3 -m pip install --editable '.[dev]'

      - name: Build Sphinx Docs
        run: sphinx-build -b html docs/ build/docs/

The next two steps don't have an action associated. They are only running two commands: a pip install of all the dev requirements defined to the package, and the sphinx-build to generate the HTML docs.

Splitting out certain commands into their own steps can help with troubleshooting. If this workflow fails I will know if it failed during dependency installs or if it failed during the build.

Publishing

      - name: Upload Artifact
        uses: actions/upload-pages-artifact@v2
        with:
          path: 'build/docs/'

      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v2

The last two steps complete the process by uploading the artifact for the docs (the build/docs/ directory that sphinx-build outputted to) and then using the deploy-pages action.

The id field has the value deployment which was used earlier in the environment section:

url: ${{ steps.deployment.outputs.page_url }}

The action for uploading the artifact doesn't do too much, but it takes care of all the nuance around GitHub Pages artifacts specifically. You can view the action's source here. It will tar the path (provided by the with option) and then call the upload artifact action. The artifact's name is github-pages and has a 1 day expiration. This artifact has the name and format required for the deploy action. It all just works (so far).

Success

The result is a fresh build of the documentation on every commit to main available at the project's GitHub Pages URL.

My workflow is for a Python package's docs, but there are only two parts that are specific to that: the runtime setup, and the step that installs dependencies and builds the docs. You could swap those out for any other runtime and/or documentation framework and the rest should be pretty much the same.

Notes on Jamf Pro API Roles and Clients

Bryson Tyrrell — Mon, 21 Aug 2023 19:43:52 +0000

With Jamf Pro 10.49 admins can now use OAuth client credentials flow for authenticating to the product's APIs.

The documentation for the new API Roles and Clients can be found here. The implementation is straightforward:

Go to Settings > System > API Roles and Clients
Create an API Role
Select all of the applicable Jamf Pro API role privileges it should grant.
Create an API Client.
Select one or more API Roles to assign to it.
Enable the API Client.
Generate the Client Secret.

You can now use the client ID and secret to obtain access tokens. This shell example below is taken from Jamf's developer docs.

curl --request POST "${url}/api/oauth/token" \
    --header "Content-Type: application/x-www-form-urlencoded" \
    --data-urlencode "grant_type=client_credentials" \
    --data-urlencode "client_id=${client_id}" \
    --data-urlencode "client_secret=${client_secret}"

API Client access tokens have different claims than those returned using user-based basic authentication.

{
  "sub": "55ed202f-371c-41aa-9dc5-c63d6a1f6b3c",
  "aud": "55ed202f-371c-41aa-9dc5-c63d6a1f6b3c",
  "nbf": 1692646434,
  "token-uuid": "eaa92ecb-644f-4a8a-8591-6d6f08f50288",
  "subject-type": "REGISTERED_CLIENT_ID",
  "authentication-type": "CLIENT_CREDENTIALS",
  "scope": [
    "api-role:2"
  ],
  "iss": "http://<redacted>.jamfcloud.com",
  "exp": 1692646494,
  "iat": 1692646434
}

Note that the scope claim contains api-role:2 as the value. Jamf Pro is referencing API Roles by their database IDs and not their name or other identifier. Each assigned roles is represented using the same api-role:ID scheme. When the server validates the token it is querying for API Roles using the IDs found in the scope and applying those privileges.

Role assignments are cumulative. The API Client will have the sum of all API privileges across all of the assigned roles.

This means that changing API Role assignments on an API Client is a scope change.

In Jamf's implementation of client credentials flow the scope change requires generating a new client secret for the assignment change to take effect. Until this happen the role assignments (scope) at the time the secret was generated will continue to be returned.

Conversely, changing the privileges assigned to an API Role takes effect immediately and do not require generating a new client secret for API Clients that are assigned those the role.

I would recommend that admins adopt a 1:1 relationship of API Role to API Client and not attempt to re-use roles across clients. Otherwise, you may find yourself in a headache situation where you can't update your client's role assignments without interruption.

Misadventures Playing in Rust on AWS Lambda

Bryson Tyrrell — Sat, 19 Feb 2022 00:54:09 +0000

That feeling of embarking on something new.

Not pictured is the wall I ran into.

I am a Python developer. My life has been lived within the safe confines of an interpreter and devoid of realities of compilers and platform architectures. Life is sweet. Despite this, I have found myself being lured by the prospects and promises of what compiled languages can bring: ludicrous speed.

Since 2020 it has been clear to me that AWS has decided on Rust as their Go. The release of the official AWS SDK for Rust, and a maturing Rust runtime for Lambda, signaled that it might be time for me to explore what developing my functions in this language might look like.

The Setup

Up until now I've heard that Rust can be difficult, but I can safely say that getting started with Rust itself is not difficult. Following the instructions in the Rust Book resulted in my ability to write and compile a program without a single hitch.

Where I really ran into trouble was trying to use the Rust runtime and AWS SDK and deploy a Lambda Function. I am writing code on an Apple Silicon MacBook Pro (M1 Pro to be precise). This is an arm64 architecture. My goal was to compile for the standard x86 architecture in Lambda.

Yes, arm64 is available as a target, but the availability of x86 is 24 regions (including GovCloud) vs 10 (and no GovCloud). These regions lists are available on the AWS Lambda pricing page.

Head First

My goals going into this were not very ambitious. That is, beyond jumping in headfirst to running Rust code in Lambda. The code I used was taken straight from the lambda-http crate example. I wanted to get a feel for what the experience was going to be like moving from serverless Python to serverless Rust.

use lambda_runtime::{handler_fn, Context, Error};
use serde_json::{json, Value};

#[tokio::main]
async fn main() -> Result<(), Error> {
    let func = handler_fn(func);
    lambda_runtime::run(func).await?;
    Ok(())
}

async fn func(event: Value, _: Context) -> Result<Value, Error> {
    let first_name = event["firstName"].as_str().unwrap_or("world");

    Ok(json!({ "message": format!("Hello, {}!", first_name) }))
}

Running cargo build here introduced me to Rust's fantastic and helpful compiler errors, and managing my dependencies in Cargo.toml.

error[E0432]: unresolved import `serde_json`
 --> src/main.rs:2:5
  |
2 | use serde_json::{json, Value};
  |     ^^^^^^^^^^ use of undeclared crate or module `serde_json`

error[E0433]: failed to resolve: use of undeclared crate or module `tokio`
 --> src/main.rs:4:3
  |
4 | #[tokio::main]
  |   ^^^^^ use of undeclared crate or module `tokio`

Using cargo feels very familiar to me as pipenv works much the same way. Nice.

[package]
name = "rust_demo_api"
version = "0.1.0"
edition = "2021"

[dependencies]
lambda_runtime = "*"
lambda_http = "*"
serde_json = "*"
tokio = "*"

Re-running cargo build now results in success! Great! Now to compile my function for x86 and deploy is using SAM. The documentation is straightforward and cross compiling is something that is touted with Rust. So I...

% rustup target add x86_64-unknown-linux-gnu
% cargo build --target x86_64-unknown-linux-gnu

The Wall

This is where I hit it. The very first thing I tried to do was switch my target from x86 to arm64 to see if I could compile for Graviton.

% rustup target add aarch64-unknown-linux-gnu
% cargo build --target aarch64-unknown-linux-gnu

More errors.

I begin a process we are all very familiar with: encounter issue, Google appropriate errors and terms, and test solutions. I did indeed find posts and GitHub issues that related to the various compiling errors I was trying to work through, but in the process I came to the realization that I was trying to solve cross compiling issues in the opposite direction of most of the Rust community.

When cross compiling is discussed it is about an x86 host targeting arm64 platforms. I'm trying to go from an arm64 host to an x86 platform. At this point I come back to the Rust runtime's documentation.

At the time of writing, the ability to cross compile to x86 or aarch64 AL2 on MacOS is limited. The most robust way we've found is using Docker to produce the artifacts for you.

% PLATFORM="linux/amd64" \ # linux/arm64
% TARGET="x86_64-unknown-linux-gnu" # aarch64-unknown-linux-gnu
% docker run \
  --platform "${PLATFORM}"
  --rm --user "$(id -u)":"$(id -g)" \
  -v "${PWD}":/usr/src/myapp -w /usr/src/myapp rust:latest \
  cargo build --release --target "$(TARGET}"

The x86 build did not work, but the arm64 build did!

Finished release [optimized] target(s) in 2m 56s

Oof that's slow. An immediate repeat run clocked in at 58.81 seconds. The update of the crates.io index is taking up the bulk of that time, and the compiling will only go so fast as the number of CPUs I assign to Docker.

Still, this is progress. I can copy the resulting binary to build/get/bootstrap, the location set in my SAM template shown below, and deploy my first function.

AWSTemplateFormatVersion: 2010-09-09
Transform: AWS::Serverless-2016-10-31

Globals:

  Function:
    Architectures:
      - arm64
    Runtime: provided.al2
    Handler: rust

Resources:

  Api:
    Type: AWS::Serverless::HttpApi
    Properties:
      FailOnWarnings: true

  GetFunction:
    Type: AWS::Serverless::Function
    Properties:
      CodeUri: ./build/get
      Events:
        read:
          Type: HttpApi
          Properties:
            ApiId: !Ref Api
            Method: get
            Path: /

Outputs:

  ApiUrl:
    Value: !Sub https://${Api}.execute-api.${AWS::Region}.${AWS::URLSuffix}

I had partially achieved my goals. I have a sample Rust function deployed behind an API Gateway that I can invoke. I had to fall back to arm64, and it doesn't use the new SDK to perform operations (i.e. DynamoDB).

Professional Help

During all of this I had an AWS Solutions Architect guided me through my pitfalls. Nicolas Moutschen has a fully realized version of what I was prototyping sitting in a pull request to the AWS SAM CLI, and a much larger and more comprehensive Rust application available here.

I took the code in his PR (it writes a JSON body to a DynamoDB table) and added a second function.

...
  PostFunction:
    Type: AWS::Serverless::Function
    Properties:
      CodeUri: ./build/post
      Policies:
        - DynamoDBWritePolicy:
            TableName: !Ref Table
      Events:
        create:
          Type: HttpApi
          Properties:
            ApiId: !Ref Api
            Method: post
            Path: /create/{id}
...

The results were nothing short of fantastic.

// Detect dark theme var iframe = document.getElementById('tweet-1492587703640154115-906'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1492587703640154115&theme=dark" }

In addition to learning a great deal from Nicolas' code, I also followed suggestions he made to fix my issue of running builds for x86. He came across cargo-zigbuild which uses ziglang as the linker for cross compiling.

% python3 -m venv zigenv
...
% source zigenv/bin/activate
(zigenv) % pip install ziglang
...
(zigenv) % cargo install cargo-zigbuild
...
(zigenv) % cargo zigbuild --release --target x86_64-unknown-linux-gnu
...
Finished release [optimized] target(s) in 20.85s

First try!

That is night and day with the earlier two minutes plus in Docker! The re-run without changes - just as before - clocked at 0.04 seconds. These are the kinds of build speeds I wanted to see!

This Was the Hard Way

The Rust Book - linked again to emphasize its importance - is a fantastic getting started resource. Kicking the tires on Rust as a language was quick and easy and lived up to much of the promise of having the cake and eating it too.

Jumping immediately into running Rust code in AWS Lambda also shouldn't have been too difficult had I been on an Intel based Mac. I came across what felt like ALL of the edge cases in cross compiling Rust code.

I still need to learn much of the how of Rust, but seeing working code from Nicolas demonstrating the use of the new SDK in the context of a Lambda function taught me a great deal. If I really wanted to I could probably cobble together a basic CRUDL API with my current knowledge.

Would I use such a thing in production? I'm not nearly that irresponsible.

This adventure did bear unexpected fruits.

// Detect dark theme var iframe = document.getElementById('tweet-1494747974861312002-337'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1494747974861312002&theme=dark" }
// Detect dark theme var iframe = document.getElementById('tweet-1494748990809722884-642'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1494748990809722884&theme=dark" }
// Detect dark theme var iframe = document.getElementById('tweet-1494751112037031945-743'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1494751112037031945&theme=dark" }

I'm going to be continuing my Rust journey by completing the Rust Book. If by the end of this post you haven't gone and followed @NMoutschen on Twitter yet you can do so now!

🦀

Musings on Revolution: Bootstrapping

Bryson Tyrrell — Wed, 01 Dec 2021 02:17:29 +0000

I recently started a new team at Jamf dedicated to building out our internal and external developer platform. Something my team has had to do with our formation is document the decisions we were making to not only have a record of them, but to understand why we made them at the time (look up Architectural Decision Records some time). These decisions cover things like specific technologies, methods, or standards we adopt.

When Emily Freeman (@editingemily) pitched a replacement to the SDLC, the Revolution Model, I was immediately captivated by the idea. Much of my time spent building cloud native services and applications at Jamf has never followed a linear path. It’s far more fluid in direction, and it has been hard to reconcile that kind of chaotic workflow with other parts of my org. Revolution provides a compelling means of doing this.

My first two days here at AWS re:Invent leading up to the latest version of her presentation (it changes a little every time) has given me time to muse on the application of Revolution to my work. I started to relate the model to the ongoing decision documenting process my team has been engaged in, on and off, the past couple of months.

Emily’s first pass at the Revolution Model is actually really good (despite her claims that if it doesn’t change she considers it a failure). Architecture exists at the outer most level with operating the very thing we are building the ultimate goal at the center. In her talks, she has walked through examples of mapping incident responses, or the path developing a new feature has taken from ideation to operation. I am looking now at how the model may be used for the initial phases of a team or a project where the foundational questions need to be asked and answered.

I’m writing this post with no plan. I’m going to have a copy of the model open next to me, and I’m going to explore the process free form.

The Model

The Revolution Model consists of six layers: Architecting, Developing, Automating, Deploying (I might actually reverse those last two), and Operating. Each layer has six considerations to evaluate in order: Testability, Securability, Reliability, Observability, Flexibility, and Scalability.

Taking Revolution in, the ideal happy path appears as a spiral. We start at Architecting, make our way around each consideration, and then we move in one level to Developing. Each layer requires a complete revolution through all considerations before moving further in. Ideas happen in the central segment, and those ideas are implemented according to the considerations as we progress.

Architecting

Ideation: I’m going to build a new API. It will be RESTful, follow a CRUDL model, and be built using AWS’s serverless stack: API Gateway HTTP API, Lambda Functions, and DynamoDB.
Testability: Unit tests are (should?) be a given, but I need to know how I will test my active service. CloudWatch Synthetics seem like a good choice as the interface is an HTTP API.
Securability: Now here’s an interesting development. Depending on how my API is going to be used - internally, or by third parties - I could go two different ways. Internal use I might want to stick with IAM authentication. Third party I would go with Cognito. If I want to use IAM I need to go back to Ideation because HTTP APIs don’t support it! If I did, I would now reevaluate the Testability of my technology choice. Tthe decision to use CloudWatch Sythetics thankfully remains unchanged as I’m swapping out one API Gateway for another.
Reliability: I have a high degree of confidence in the availability and operational consistency of the services of choice here. Writes will be durable, and reads should return the most up to date version of my data.
Observability: CloudWatch Alarms and Metrics can give me actionable data. Adding X-Ray will add even more to my ability to inspect the state of my service, but there’s another wrench thrown: HTTP APIs do not support X-Ray. The trace would initiate from Lambda, and I would not have the context of the request. This is again another point where I might reevaluate in favor of using a REST API.
Flexibility: Adding new endpoints, new Lambda functions, and changing how I write items to DynamoDB are all very simple here. Versioning API routes and tying those versions to independent functions is a pattern that makes changes manageable. Migrating old items to new items is an active consideration. I need to determine how I will handle item version migrations for when I move on to development. Do I handle this at runtime, or asynchronously after an update? The former means there’s no additional action needed on my part during deployments as long as everything is handled on a per-request basis, but it has the threat of old versioned data stagnating within the table.
Scalability: Within the default quotas provided by AWS for my account I know that my service will scale pretty far for usage. Separating Lambda functions out by endpoint and API version solved for flexibility, but there is overhead for managing the shared code between all of them. An internal Lambda Layer looks to be a good fit to solve for this.

Taking It In

This was just my first revolution around the model. At two points I identified issues with one of my technology choices: the HTTP API. I’m going to drop it and switch to a REST API so I can use IAM authentication for security and initiate X-Ray traces for better overall observation. There was a lot to consider (ha) here, and I haven’t even touched on getting into the Development layer. But, this has given me a clear and defined path to navigate as I move into that level.

My decisions during Development should implement and reinforce what I decided during Architecting, but if I hit a wall I will need to drop back down to Architecting and reevaluate again. I can imagine that by the time I get to Deploying I may encounter issues that stem from decisions during Development that might require another loop back to address to ensure a better overall design.

This may have to become a series if I continue this exercise through the rest of Revolution’s levels. But I have to say, even better than having Revolution as my guide to designing, building, and then implementing my project is that I can visualize the path it took to achieve release. The end result is something that can be used to inform projects that follow.

There’s so much more to do.

Dynamically Configure Your Lambda@Edge Functions

Bryson Tyrrell — Sun, 06 Jun 2021 22:24:54 +0000

Lambda@Edge is the thing I always find something new to gripe about each time I come back to it. Almost every time the core of my issue is the lack of any ability to perform dynamic configuration of that running code.

This is a situation that I find the AWS blog doesn't help with. Go look and you will find all sorts of examples where the configuration and/or secrets are hard coded in their functions.

I don't consider this to be best practice at all. My serverless app should be able to be redeployed without branching to commit different resource ARNs, or customizing the build process to inject values at deployment. I need to be able to have my template - the definition of my app in CloudFormation - to be able to determine all of this using the standard tooling AWS provides.

Limitations

There are two sets of event types for Lambda@Edge functions with CloudFront: viewer-request, origin-request, origin-response, and viewer-response. I wrote them in the order they occur during the client request lifecycle. As the names imply, viewer- event occur on the client's side of the CloudFront distribution, while origin- events occur the origin/source's side.

For Lambda@Edge, the triggering defines where our limitations are going to be. origin- events allow the most freedom. We can set function memory as high as we want, the timeout can be a full 30 seconds (same as an API Gateway event source), and the size of the function code can be up to 50 MB.

Switching to viewer- events severely restricts our resources. Function memory can only be the default 128 MB, our timeout can not exceed 5 seconds, and the function code cannot be more than 1 MB.

Beyond this, both event types allow us network access. As long as our functions work without the bounds set on them, we are able to leverage AWS (or other) services in our code.

For any other serverless app we would rely on environment variables to determine how we configure our code at runtime. Things like ARNs of required resources, paths or locations to read in needed secrets, all the usual suspects. With Lambda@Edge we not allow to use environment variables. At all. Period.

Origin-Request Example

For origin-request event functions there is a trick we have available: origin custom headers. These are a configuration on the origin for our CloudFront distribution, and we can dynamically set these values in our CloudFormation template. Essentially, the custom headers will become our missing environment variables.

Here's an example of one I implemented once. The use case here is that my distribution serves content from a variety of S3 buckets in numerous AWS regions. I have an API, deployed in all those regions, that can take a file identifier and then return the key name and bucket domain of where it is located. I need the Lambda@Edge function to take the file from the request, look it up in the API, and then set the origin for the request to serve it. My implementation is a variation on this AWS blog post.

In this example, my API uses a Cognito User Pool for authentication. I created an app client specifically for the CloudFront distribution's use, and it can obtain access tokens uses client credentials flow.

I'm going to skip most of the template as the important piece is how we configure the default origin of the CloudFront distribution.

Origins:
  - DomainName: !GetAtt DefaultBucket.DomainName # See comment below
    Id: default-origin
    OriginCustomHeaders:
      - HeaderName:api-domain
        HeaderValue: !Ref ApiDomainName # Template parameter
      - HeaderName: cognito-domain
        HeaderValue: !Ref UserPoolDomain # Template parameter
      - HeaderName: client-id
        HeaderValue: !Ref DistributionClientId
      - HeaderName: client-secret
        HeaderValue: !Ref DistributionClientSecret
    S3OriginConfig:
      OriginAccessIdentity: !Sub origin-access-identity/cloudfront/${CloudFrontOAI} # Template parameter

In this template I do have a DefaultBucket S3 bucket resource to use with this. You don't have to do that, but the DomainName attribute must be set. In any event, this never gets used as our function is routing to another origin or returning 404 responses.

This isn't without drawbacks. We are exposing the client credentials to CloudFront (though they are also visible in the Cognito console). The client that made the original request will never see these headers, and because they're injected by CloudFront after receiving the request. Our Lambda@Edge function processes the event before the origin, and we have the option of removing these headers as we modify the event and pass it back to CloudFormation (thus preventing exposed to the origin).

Consider an adaptations of this pattern where you pass SSM or Secrets Manager paths that the code can then read at runtime and cache for successive invocations.

Viewer Request Example

The next example I'm going to show really applies to the remaining three event types (custom headers apply only to origin-request events), but my example is specifically around implementing HTTP basic auth for resources behind my CloudFront distribution.

Here, my plan was to have the function perform a lookup in a DynamoDB table for the user that it would perform the comparison against and allow or deny access. My challenge is to

I'm not entirely sure how I was struck by this inspiration, but it occurred to me one day that the Lambda@Edge function does indeed already know exactly what it needs to talk to. That information is in the IAM role I assigned to it.

This solution can be distilled down very simply to granting the function the ability to read its own IAM role and then extract the DynamoDB ARN to configure the boto3 client. It feels wrong, but it works, and it works within the 128 MB memory and 5 second timeout limits imposed by this event type (including cold start invocations).

Let's look at the fuction's definition in my CloudFormation/SAM template first.

  DistributionAuthorizer:
    Type: AWS::Serverless::Function
    Properties:
      Runtime: python3.8
      Handler: index.lambda_handler
      CodeUri: ./src/distribution/authorizer
      Role: !GetAtt DistributionAuthorizerRole.Arn
      MemorySize: 128 # Max for viewer-request
      Timeout: 5 # Max for viewer-request
      AutoPublishAlias: live

  DistributionAuthorizerRole:
    Type: AWS::IAM::Role
    Properties:
      Path: "/"
      ManagedPolicyArns:
          - arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole
      AssumeRolePolicyDocument:
        Version: 2012-10-17
        Statement:
          - Effect: Allow
            Action:
              - sts:AssumeRole
            Principal:
              Service:
                - lambda.amazonaws.com
                - edgelambda.amazonaws.com
      Policies:
        - PolicyName: root
          PolicyDocument:
            Version: "2012-10-17"
            Statement:
              - Effect: Allow
                Action: iam:GetRole
                Resource: !Sub arn:aws:iam::${AWS::AccountId}:role/${AWS::StackName}-DistributionAuthorizer-*
              - Effect: Allow
                Action: dynamodb:GetItem
                Resource: !GetAtt ServiceTable.Arn

All very standard for a Lambda@Edge function, but I have added a new permission for this: iam:GetRole. Because we have a chicken-and-the-egg scenario unfolding where I am grating a permission to read the IAM role that the permission is defined within, I'm taking advantage of how CloudFormation names resources ( {stack name}-{logical ID}-{random suffix} ) to be sure I've targeted down the resource as best as I can without having to name it (it is best practice to not name your resources and let CloudFormation do it for you).

To make this happen in code, I need to use STS GetCallerIdentity to find out the name of the IAM role used for the credentials my function was provided, then use IAM GetRolePolicy to read the policy of the role, and then after parsing it I can find the ARN of the DynamoDB table and configure my client.

Here's the code.

import boto3


session = boto3.Session()
iam_client = session.client("iam")
sts_client = session.client("sts")

ROLE_NAME = sts_client.get_caller_identity()["Arn"].split("/")[-2]
ROLE_POLICY = iam_client.get_role_policy(RoleName=ROLE_NAME, PolicyName="root")[
    "PolicyDocument"
]

for arn in ROLE_POLICY["Statement"][0]["Resource"]:
    if arn.startswith("arn:aws:dynamodb:"):
        arn_parts = arn.split("/")
        TABLE_NAME = arn_parts[-1]
        TABLE_REGION = arn_parts[0].split(":")[3]

dynamodb_table = session.resource("dynamodb", region_name=TABLE_REGION).Table(
    TABLE_NAME
)


def lambda_handler(event, context):
    result = dynamodb_table.get_item(Key={"pk": "U#username", "sk": "A"})
    # Basic auth code will go here. L@E function always returns a 401 response for now.

    return {
        "status": "401",
        "statusDescription": "Unauthorized",
        "body": "Unauthorized",
        "headers": {
            "www-authenticate": [{"key": "WWW-Authenticate", "value": "Basic"}]
        },
    }

This is an incomplete HTTP basic authorizer as it isn't parsing the authorization header to get the username to perform the lookup, but it does demonstrate all the working pieces of configuring boto3 by referencing the IAM role policy and then performing a lookup against the table.

The runtime results, despite the number of AWS API calls being made (across three services) are encouraging:

# Cold Start
Duration: 171.38 ms Billed Duration: 172 ms Memory Size: 128 MB Max Memory Used: 80 MB  Init Duration: 519.87 ms

# Warm Executions
Duration: 24.46 ms  Billed Duration: 25 ms  Memory Size: 128 MB Max Memory Used: 80 MB
Duration: 43.25 ms  Billed Duration: 44 ms  Memory Size: 128 MB Max Memory Used: 80 MB
Duration: 25.76 ms  Billed Duration: 26 ms  Memory Size: 128 MB Max Memory Used: 80 MB
Duration: 30.47 ms  Billed Duration: 31 ms  Memory Size: 128 MB Max Memory Used: 80 MB

Well within limits. It works.

It's not really good, through, is it?

We Shouldn't Have To Do This

All of the above might sound very clever, and if it does that should tell us that it shouldn't have to be this way. My issue with Lambda@Edge is I don't feel it's developer friendly. Look at the mental hoops I've gone through to figure out how to configure my Lambda@Edge functions the way I would a normal Lambda function. There's a massive ripple effect that comes from not having environmental configuration built in.

I've reached out on this topic before, and I've never received a really good answer on the "how" to do it. If anyone from AWS's CloudFront, Lambda@Edge, CloudFormation, and/or SAM teams are stumbling across this; I ask you to reflect on the what many other customers must also have to contend with for something that should be simple, straightforward, and is easy for developers to do.