見出し画像

Jamf Pro の API を調べてみました

pirox

Jamf Pro の API の使い方を調べたので整理 & 気づいたことを残しておきます。

Jamf Pro の API は 2 種類ある

Jamf Pro では 2 種類 (2 つのバージョン) の API が提供されています。
・Jamf Classic API (以下、 Classic API)
・Jamf Pro API

個別に紹介していきます。

Classic API

Classic の名のとおり、先に提供されていたのがこちらの API のようです。

Overview,  API Referrence に加えて Code Samples のページが用意されており、 Curl コマンドや Python を使ったサンプルコードが紹介されていることからもなんとなく歴史を感じます。 (Jamf Pro API には無かった)

画像1

Overview には認証方式やエラーコード等の情報が、API Referlence には各エンドポイントへのアクセス方法が記述されています。いくつか抜粋・要約します。 


■ ベース URL

Classic API の ベース URL は "https://<your-tenant-name>.jamfcloud.com/JSSResource" です。

この後ろにエンドポイントの文字列が追加されます。たとえば、 Policy を操作したい場合は "https://<your-tenant-name>.jamfcloud.com/JSSResource/policies" となります。

ちなみに "JSS" は "Jamf Software Server" という旧名称 ?? の略称のようです。


■ 認証・認可

※ 追記
Jamf Pro v10.35.0 以降、Classic API での Basic 認証の利用が非推奨 (2022 年 8 月 ~ 12 月で廃止予定) となり、Jamf Pro API と同様に Bearer Token による認証が導入されました。


Classic API では Basic 認証をサポートしています。
・The Classic API Overview#Authentication and Authorization

Jamf Pro に登録しているユーザアカウントのユーザ名、パスワードを BASE64 でエンコードした文字列を、エンドポイントへの HTTP リクエストの Authorization ヘッダにセットします。

Authorization: Basic <"ユーザ名:パスワード"を BASE64 でエンコードした文字列>

> BASE64 でエンコード
デコードすれば元の情報がわかる(ユーザ名、パスワードがわかる)ので、エンコードした文字列の取り扱いには注意です。

認証で利用するユーザアカウントに付与した権限の範囲内で、各エンドポイントの操作が可能です。「この操作をするにはどの権限が必要 ?? 」は以下のページで確認することができます。
・Classic API Minimum Required Privileges and Endpoint Mapping

また認証に利用するユーザアカウントは「アクセスステータス」が「有効」である必要があります。

画像12


(「無効」にするとダッシュボードへのアクセスは禁止されるが、API でのアクセスは許可されるのでは？と妄想してみましたが、そんなことはありませんでした。。)


■ 扱えるデータ形式

Script のエンドポイントの場合、指定できる Accept, Content-Type ヘッダは以下のとおりです。

・GET : (Accept) application/xml, application/json から選択
・POST, PUT : (Content-Type) application/xml のみ
・DELETE : (Accept) application/xml のみ

Jamf Pro から情報を取得するだけであれば JSON が使えますが、リソースの作成・更新・削除では XML でのやりとりになります。



Jamf Pro API

下記のページで "The Jamf Pro API is currently in beta, but will be the future for interacting with Jamf Pro programmatically." と記述されているとおり、Jamf Pro API は新しく開発されている API です。

リリースノートをさかのぼると、 Version 10.25.0 までは "The Jamf Pro API beta is open for user testing. " とありますが、Version 10.26.0 以降は "The Jamf Pro API is open for user testing. " と "beta" の表現が無くなりました。

最新の Version 10.30.0 でもエンドポイントが追加されています。

The following endpoints were added:
- POST /v1/icon
- GET /v1/icon/{id}
- GET /v1/jamf-connect
 ~

リファレンス を参照して、目的のエンドポイントが提供されているか確認しましょう。


■ ベース URL

Jamf Pro API のベース URL は "https://<your-tenant-name>.jamfcloud.com/api" です。

(2021.09.20)
ベース URL を ~/uapi -> /api に修正しました。理由は後述。


直後に v1, v2 とバージョン情報が、次にオブジェクトごとのエンドポイントが続きます。preview とタグ付けされているエンドポイントは仕様が変わる可能性があるので、本番利用は控えたほうが良さそうです。

画像13

※ ベース URL は ~/api 説
API ドキュメントには "The base URL for the Jamf Pro API is located at /uapi on each Jamf Pro instance." とある一方、リリースノート (Version 10.22.0 以降) では "The base URL for the Jamf Pro API is /api." と記述されています。いくつかのエンドポイントで確認したところ、どちらでも意図した操作ができました。混乱しますし、 ~/uapi のままでよいのかも心配なので、ドキュメントに説明を追加する等してほしいと感じました。

(2021/09/20 追記)
Jamf のドキュメントページが一新されまして、新しいページを見るとどうも　~/api の方を採用しているような。
https://developer.jamf.com/jamf-pro/reference/jamf-pro-api

サポートに問い合わせてみたら以下の回答だったので、~/api に切り替えていきましょう。※ 念のため、すでに作成済みのツールも改修しておいた方が良さげです。

(サポートとのやりとりを要約)
Q. 現在公開されているドキュメントを確認すると、ベース URL が ~/api となっているようだが、将来的に ~/uapi が使えなくなることはあるのか？

A. 
・/uapiが使用できなくなる予定(※使用できなくなるかどうかも含めて)
は未定のままですが、予定日が決まる前にお使いのAPIコマンドを /uapiから/ apiに更新頂く様お勧め致します。

・新しい認証エンドポイントは /api をベースパスとして使用する必要があります。

・他のすべてのエンドポイントは/uapiまたは /apiのどちらを使用されても問題なく機能します。


■ 認証・認可

Bearer Token による認証方式をとっています。ただし Token 取得時には Basic 認証を必要とします。

・Jamf Pro API Documentation - Authentication and Authorization

① ~/v1/auth/tokens へアクセス (POST) して Token を取得
  ・Jamf Pro アカウントによる Basic 認証が必要

(※ 2021.09.20 追記)
~/uapi/auth/tokens -> ~/v1/auth/token に修正


② 各エンドポイントへのアクセス時は ① で取得した Token を Authorization ヘッダにセット
  ・Authorization: Bearer <TOKEN_VALUE>
  ・トークンの有効期間は発行から 30 分 (延長も可能)

Token に付与される権限は、 Basic 認証で利用したユーザアカウントがもつ権限と同一です。


■ 扱えるデータ形式

Script のエンドポイントの場合、指定できる Accept, Content-Type ヘッダは application/json に統一されています。嬉しい。



Classic API と Jamf Pro API で微妙に違ったところ

ベース URL や認証方式、提供されているエンドポイント以外にも微妙に違いがあったのでメモしておきます。(Policy, Script のエンドポイントを操作した範囲で気づいたものです。)

■ [ Classic API ] リソースの新規作成時に ID を指定 ??

Classic API で Script を作成する場合、URI に ID を含める必要があります。
・Jamf Classic API - Creates a new Script by ID

画像12

「これから作成するリソースの ID をどうやって確認するの」と悩みましたが、結論としては Default value とされている 0 (ゼロ) ( ~/policies/id/0) をセットしておけばよいです。この挙動は Policy の作成でも同じだったので、他のエンドポイントでもおそらく同様かと思います。

ちなみに 999… といった未割り当ての ID をセットしてもリソースは作成されます。「それならユーザ側で ID をセットする必要ないのでは… 」という気持ちは Jamf 側にも伝わっているようで、 Jamf Pro API のエンドポイントでは ID が不要となっています。

画像14


■ ID の型が違う ??

Classic API では、 Script のパラメータである ID (id) が integer 型(整数型)として定義されていますが、 Jamf Pro API では string 型 (文字列型) に変更されています。

画像14
画像15

他のエンドポイントでも同様に ID が string 型に変更されているもの、 integer 型のままであるものが混在しており、規則性はよくわからなかったです。

型の取り扱いが厳密な言語 (Go とか)で API アクセス用のツールを作成したり、別の SaaS と連携させる場合に考慮が必要となるケースがありそうです。


■ Enum の文字列

Script のパラメータの priority (優先度) は指定可能な値が決められています。 3 つの選択肢があるのですが、 Classic API では単語の先頭のみ大文字で、 Jamf Pro API ではすべて大文字で指定、と変更されています。

画像6
画像7



(困りごと) 必須のパラメータがわかりづらい

POST, PUT でリソースを作成・更新する場合に定義が必須となるパラメータがあるのですが、リファレンスからは読み取ることができず、試行錯誤で把握しました。

Script を作成する場合、 name のパラメータだけ定義して POST すると、 StatusCode: 500 のエラーが返ります。

画像8

500 は "Internal server error. Retry the request or contact Jamf support if the error is persistent." とのことなので、何度か繰り返してみたのですが状況は変わらず。

Jamf Pro API - Erros

画像9

そこからパラメータを足し引きしていって、どうやら Script の作成時には name, priority, categoryId の 3 つが必須らしい、と確認できました。

画像10

リファレンスに Required: Yes / No の記述があると嬉しいですが、「ダッシュボード上でリソースの新規作成をするときに『デフォルト値が設定されている項目の定義は必須』っぽい」という判別方法を見出したので、なんとか頑張れそうです。


感想

新バージョンのリリースの都度 Jamf Pro API のエンドポイントが追加されていますが、今はまだ Classic API のラインナップには届きません。その一方、 比較的新しい機能に関するエンドポイントは Jamf Pro API でのみ提供しているケースもあるようです。(↓はクラウドアイデンティティプロバイダに関するエンドポイントのはず)

画像15

過渡期のようなので難しいですが「用途に応じて使い分けましょう」となるのでしょうか。。

開発中の Jamf Pro API には要望もあります。
・API アクセス用に Client ID, Client Secret を発行・権限の Scope を設定できるようにしてほしい (ツール用にユーザアカウントを作成・有効のままにしておくのは怖い)
・ドキュメントがもう少しわかりやすいと嬉しい (ベース URL や必須パラメータの件)

・・・と、ここに書くだけでは伝わらないので、ちゃんと Feature Request をあげたいと思います。================================================

Jamf Nation にサインインして
・[ Feature Requests ] タブから [ + Create Feature Request ] をクリック

画像11

・このリンク↓で直接アクセス
　https://www.jamf.com/jamf-nation/feature-requests/new

のどちらかでリクエストページが開きます。届けるべきところに声を届けていきましょう。================================================

API が使いやすいサービスはエコシステムに組み込んでいけるので可能性が広がります。自動化とも相性バッチリです。 Jamf Pro でも API を活用していきましょ〜。

というわけで、次回は API を使ったツールについて note を書こうと思います。

いただいたサポートは記事を書くためのエネルギー(珈琲、甘いもの)に変えさせていただきます！