GakuNinmAPpublic

ページ ツリー

比較バージョン

古いバージョン 37

changes.mady.by.user Sota Kaneko

保存しました

次と比較

新しいバージョン 現在

changes.mady.by.user KUROSAKA Shoichi

保存しました

キー

  • この行は追加されました。
  • この行は削除されました。
  • 書式設定が変更されました。

...

いずれも、認証は学認における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=言語]

...

フィールド名

内容

備考

totalResults

ユーザ数（全ての属性が許可されない場合そのユーザ分は差し引く）

Required

id

学認クラウドゲートウェイサービスのeduPersonTargetedID


displayName

氏名


aboutMe

自己紹介

未有効化

emails

メールアドレス


languagesSpoken

使用言語

"en"もしくは"ja"

未有効化

organizations

所属

未有効化

map_IdPEntityIDs

認証に利用するIdP（entityID）

複数可

未有効化

eduPersonPrincipalNames所属機関IdPから送信されたeduPersonPrincipalName複数可

※ Required以外のフィールドは、利用者が同意したフィールドのみ送られます。また、全てのフィールドが存在しない（同意されていないもしくはSPが要求していない）場合はオブジェクトごと無くなります。
※ id には、学認クラウドゲートウェイサービスが発行する永続的な識別子のJavaScriptでの表現が入ります。SP毎に異なる値になりますが、同一SPに対しては同一ユーザについて常に同じ値を返します。
　例: "https:\/\/cg.gakunin.jp\/idp\/shibboleth!https:\/\/sp.example.ac.jp\/shibboleth-sp!S8Xi7R5Wf1pd8k8lq9eoiXyCtmw="
※ ここで送信される id と、ユーザ認証時にSimpleAggregationで学認クラウドゲートウェイサービスから送信されるeduPersonTargetedIDは一致します。
※ 特に、文字列中にUnicodeのコード表記（例:\u3042）の形式の文字を含む可能性があります。
※ 指定されたグループに下位グループが存在する場合、下位グループのメンバーも含まれます。

※ 未有効化のフィールドについては現状利用できません。受信を希望するフィールドがございましたら学認クラウドゲートウェイサービスサポートまでご連絡ください。

※ 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=言語]
     

SPコネクタentityIDorID には SPコネクタentityID もしくは SPコネクタID を指定します。

...

※ <グループ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

  • 当該URLへのアクセスをソースIPアドレスで制限している場合には、少なくとも学認クラウドゲートウェイサービスからのアクセスを許可してください。アクセス元は natgw1.cg.gakunin.jp, natgw2.cg.gakunin.jp (52.192.180.249 , 52.199.121.28) となります。学認クラウドゲートウェイサービスがURLへアクセスできない場合には「SPコネクタとは接続できません」とのエラーメッセージが出力されます。

    注意

    グループ管理者の操作によって、同じリクエストが複数あることがあります。そのため、問題がない場合は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側ではリクエストを受け取った際に、学認クラウドゲートウェイサービスの証明書であることを確認してください。

...