ページ ツリー

比較バージョン

キー

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

現在連携SPがGakuNin mAP(クラウドゲートウェイ)で利用できるAPIは3種類あります。前二者はOpenSocialおよび現在連携SPがクラウドゲートウェイで利用できるAPIは3種類あります。前二者はOpenSocialおよびVOOT 1.0をベースとしたフォーマットでレスポンスはJSON形式です。最後のものは呼び出しが逆向きです。

  • People API
    グループを指定してそのメンバーに関する情報を取得するためのAPI
  • Groups API
    SPコネクタに接続しているグループに関する情報を取得するためのAPI
  • New Group API
    新たなグループから接続があった場合にGakuNin mAP(クラウドゲートウェイ)から呼び出されるSPのAPI新たなグループから接続があった場合にクラウドゲートウェイから呼び出されるSPのAPI

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

People API

リクエストURL

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

...

言語 はオプション項目であり、レスポンスで返す言語を指定します。
指定できるTYPEは、en と ja で、下記の優先順位でレスポンスを返します。
           リクエストURLの言語指定 > 英語入力 > 日本語入力
なお、英語、日本語ともGakuNin mAP(クラウドゲートウェイ)に登録がなければ、当該属性自体が存在しない状態で返します。 なお、英語、日本語ともクラウドゲートウェイに登録がなければ、当該属性自体が存在しない状態で返します。

認可: 認証に用いた証明書に紐付くSPを対象SPとするSPコネクタについて、当該SPコネクタと指定したグループが接続している場合のみメンバー情報を取得することができます。なお、グループentityID/IDとして指定できるのは、SPコネクタに直接接続しているグループのみです。

下記に例を示します。
GakuNin mAP(クラウドゲートウェイ)に、氏名「日/英」、自己紹介「英」、所属「日/英とも空欄」で登録されていた場合、 クラウドゲートウェイに、氏名「日/英」、自己紹介「英」、所属「日/英とも空欄」で登録されていた場合、
リクエストの言語指定が「ja」であった場合は、氏名「日」、自己紹介「英」、所属「無し」を、
リクエストの言語指定が「en」であった場合は、氏名「英」、自己紹介「英」、所属「無し」を、
リクエストの言語指定がない場合は、氏名「英」、自己紹介「英」、所属「無し」を返します。

...

書式設定済み
{
    "totalResults" : <ユーザ数>,
    "entry" : [
        {
            "id" : "<mAPのeduPersonTargetedID><クラウドゲートウェイのeduPersonTargetedID>",
            "displayName" : "<氏名>",
            "aboutMe" : "<自己紹介>",
            "emails" : [
                {"type" : "email", "value" : "<mAPに登録したメールアドレス><クラウドゲートウェイに登録したメールアドレス>"}
            ],
            "languagesSpoken" : [
                {"type" : "languageSpoken", "value" : "<mAPに登録した使用言語><クラウドゲートウェイに登録した使用言語>"}
            ],
            "organizations" : [
                {"type" : "organization","value" : {"name" : "<mAPに登録した所属><クラウドゲートウェイに登録した所属>"}}
            ],
            "map_IdPEntityIDs" : [
                {"type" : "map_IdPEntityID", "value" : "https://xxxxxx/idp/shibboleth"},
                ...
            ],
        },
        ...
    ]
}

フィールド名

内容

備考

totalResults

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

Required

id

mAPのeduPersonTargetedIDクラウドゲートウェイのeduPersonTargetedID

 

displayName

氏名

 

aboutMe

自己紹介

 

emails

メールアドレス

 

languagesSpoken

使用言語

"en"もしくは"ja"

organizations

所属

 

map_IdPEntityIDs

認証に利用するIdP(entityID)

複数可

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

...

言語 はオプション項目で、レスポンスで返す言語を指定します。
指定できるTYPEは、enとjaであり、下記の優先順位でレスポンスを返します。
          リクエストURLの言語指定 > 英語入力 > 日本語入力
なお、英語、日本語ともGakuNin mAP(クラウドゲートウェイ)に登録がなければ、当該属性自体が存在しない状態で返します。 なお、英語、日本語ともクラウドゲートウェイに登録がなければ、当該属性自体が存在しない状態で返します。

認可: 指定されたSPコネクタは、認証に用いた証明書に紐付くSPを対象SPとするSPコネクタでなければなりません。

下記に例を示します。
GakuNin mAP(クラウドゲートウェイ)に、グループ名「日/英」、紹介文「日」で登録されていた場合、 クラウドゲートウェイに、グループ名「日/英」、紹介文「日」で登録されていた場合、
リクエストの言語指定が「ja」であった場合は、グループ名「日」、紹介文「日」を、
リクエストの言語指定が「en」であった場合は、グループ名「英」、紹介文「日」を、
リクエストの言語指定がない場合は、グループ名「英」、紹介文「日」を返します。

...

  • URLのフォーマットは特に定めません。SPコネクタの設定項目の一つである「New Group API」欄にSP側のAPIのURLを登録してください。
  • URLに以下の変数を含めると、API呼び出し時に当該部分がGakuNin mAP(クラウドゲートウェイ)が持つ情報で置換されます。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形式で、GakuNin mAP(クラウドゲートウェイ)にレスポンスを返す必要があります。上記リクエストのレスポンスを以下に示します。SP側では下記のようなJSON形式で、クラウドゲートウェイにレスポンスを返す必要があります。

成功時

書式設定済み
{
 "result" :  "OK",
 "message" : "メッセージ"
}

...

項目必須説明
result
成功時はOK、失敗時はNGを設定します。
message成功時、失敗時ともメッセージを入れてください。現状これはGakuNin mAP(クラウドゲートウェイ)のログに記録されるのみです。成功時、失敗時ともメッセージを入れてください。現状これはクラウドゲートウェイのログに記録されるのみです。

 

HTTPステータス

HTTPステータス説明
200GakuNin mAP(クラウドゲートウェイ)からリクエストを受け付けた場合、ステータスを200で返してくださいクラウドゲートウェイからリクエストを受け付けた場合、ステータスを200で返してください

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

 

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

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

また、mAP側はTLSサーバ証明書認証によりリクエスト先の正当性確認を行ないます。登録したURLのスキームがHTTPSであること、および当該URLのサーバ証明書がSPメタデータに記載されたものと一致することをご確認ください。また、クラウドゲートウェイ側はTLSサーバ証明書認証によりリクエスト先の正当性確認を行ないます。登録したURLのスキームがHTTPSであること、および当該URLのサーバ証明書がSPメタデータに記載されたものと一致することをご確認ください。

エラーレスポンス(共通)

HTTPステータス

原因

400

APIのURL不正

403

・提示された証明書が学認参加SPのものでない場合
・セレクタ(@me)が未設定の場合
・指定されたグループが対象となるSPコネクタと接続していない場合

404

指定されたグループがない場合

...