...
いずれも、認証は学認における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 | ○ | 成功時はOK、失敗時はNGを設定します。 |
message | ○ | 成功時、失敗時ともメッセージを入れてください。現状これは学認クラウドゲートウェイサービスのログに記録されるのみです。 |
HTTPステータス
HTTPステータス | 説明 |
---|---|
200 | 学認クラウドゲートウェイサービスからリクエストを受け付けた場合、ステータスを200で返してください学認クラウドゲートウェイサービスからのコールバックを受け付けた場合、ステータスを200で返してください |
※ HTTPステータスが200以外の場合、および上記resultがNGの場合は、接続したグループ管理者に対して「meatmailへのAPI呼び出しが失敗しました」と画面にメッセージが表示されます。HTTPステータスが200以外の場合、および上記resultがNGの場合は、接続したグループ管理者に対して「meatmailへのAPI呼び出しが失敗しました」のように画面にメッセージが表示されます。
サーバ認証およびクライアント認証
学認クラウドゲートウェイサービスからのリクエストではTLSクライアント証明書認証を使います。
学認フェデレーションのメタデータにある学認クラウドゲートウェイサービス(entityID:https://cg.gakunin.jp/idp/shibboleth)の証明書を使いSPにリクエストします。
SP側ではリクエストを受け取った際に、学認クラウドゲートウェイサービスの証明書であることを確認してください。
...