...

いずれも、認証は学認におけるSPメタデータに記載されている証明書を用いたTLSクライアント証明書認証により行います。証明書の extended Key Usage (eKU) に clientAuth が記載されていなければなりません。
また、学認クラウドゲートウェイサービスが提示する証明書も学認におけるSPメタデータに記載されているものとなりますので、SP側で適切に検証してください。

People API

グループを指定してそのメンバーに関する情報を取得するためのAPI

リクエストURL

• メンバーのみを取得
  https://cg.gakunin.jp/api/people/@me/グループentityIDorID[?lang=言語]
• 管理者のみを取得
  https://cg.gakunin.jp/api/people/@me/グループentityIDorID%2Fadmin[?lang=言語]

...

※ People APIで取得できる属性については FAQ#学認クラウドゲートウェイサービスとIdPから得られる情報の違いについて も合わせてご参照ください。

Groups API

SPコネクタに接続しているグループに関する情報を取得するためのAPI

リクエストURL

• SPコネクタに接続しているグループ情報の取得
  

  https://cg.gakunin.jp/api/groups/@me[?lang=言語]

  https://cg.gakunin.jp/api/groups/SPコネクタentityIDorID[?lang=言語]
   

...

※ <グループentityID> は、isMemberOfで取得することができるURL形式の値（のJavaScriptでの表現）
　例: "https:\/\/cg.gakunin.jp\/gr\/GakuNinTF"
※ このAPIで取得できるグループはSPコネクタに直接接続しているもののみです。上位グループ経由で接続している下位グループのグループ情報は含まれません。
※ <グループのメンバー数> には、管理者のみの人（管理者であるがメンバーでない人）は含まれません。また、属性送信に同意しているかどうかに関わらずカウントされますので、people APIを通して取得した数より大きい可能性があります。
※ 特に、文字列中にUnicodeのコード表記（例:\u3042）の形式の文字を含む可能性があります。

New Group API

...

新たなグループから接続があった場合に学認クラウドゲートウェイサービスから呼び出されるSPのAPI

コールバックURL

• URLのフォーマットは特に定めません。SPコネクタの設定項目の一つである「New Group API」欄にSP側のAPIのURLを登録してください。

• URLに以下の変数を含めると、API呼び出し時に当該部分が学認クラウドゲートウェイサービスが持つ情報で置換されます。

  変数名	置換される値
  $groupID	グループID（グループentityIDの短縮形）
  $adminEmail	接続を行ったグループ管理者のメールアドレス（つまり当該グループに管理者が複数人いても1つのみ渡されます）

• 例えばmeatmailでは以下のように登録しており、

  書式設定済み
  https://meatmail.nii.ac.jp/meatmail-api/newlist/$groupID/$adminEmail

  実際の呼び出し例は以下のようになります。

  書式設定済み
  https://meatmail.nii.ac.jp/meatmail-api/newlist/TestGroup/user%40example.jp

  注意
  グループ管理者の操作によって、同じリクエストが複数あることがあります。そのため、問題がない場合はOKを返すようにしてください。 例えば、メーリングリストの作成リクエストの1回目は実際にメーリングリストを作成し、2回目は既に作成されているのでそのままOKを返します。

レスポンス

上記リクエストのレスポンスを以下に示します。SP側では下記のようなJSON形式で、学認クラウドゲートウェイサービスにレスポンスを返す必要があります。上記コールバックのレスポンスを以下に示します。SP側では下記のようなJSON形式で、学認クラウドゲートウェイサービスにレスポンスを返す必要があります。

成功時

{
 "result" :  "OK",
 "message" : "メッセージ"
}

...

result

HTTPステータス

※ HTTPステータスが200以外の場合、および上記resultがNGの場合は、接続したグループ管理者に対して「meatmailへのAPI呼び出しが失敗しました」と画面にメッセージが表示されます。HTTPステータスが200以外の場合、および上記resultがNGの場合は、接続したグループ管理者に対して「meatmailへのAPI呼び出しが失敗しました」のように画面にメッセージが表示されます。

サーバ認証およびクライアント認証

学認クラウドゲートウェイサービスからのリクエストではTLSクライアント証明書認証を使います。
学認フェデレーションのメタデータにある学認クラウドゲートウェイサービス（entityID:https://cg.gakunin.jp/idp/shibboleth）の証明書を使いSPにリクエストします。
SP側ではリクエストを受け取った際に、学認クラウドゲートウェイサービスの証明書であることを確認してください。

...