ここでは、
GeneXus で安全な REST Web サービスを開発する方法とその簡潔な概要を説明します。
REST Web サービスのセキュリティは
OAuth に基づいています。
通常、さまざまなアプリケーションが
REST を使用してデータ更新サービスやデータ復旧サービスを公開するため、データのプライバシーに関するセキュリティが非常に重要になります。
GeneXus では、この問題のソリューションとして、
GAM (OAuth テクノロジーの複雑さがエンドユーザーに表示されることはありません) を使用します。
GAM API により、アプリケーションで定義した
REST Web サービスへのユーザーのアクセスを制限できます。
下記に示すガイドでは、REST Web サービスにセキュリティを組み込む手順と、GeneXus アプリケーションからこれらの Web サービスを利用する方法についても説明します。GeneXus 以外のアプリケーションから Web サービスを利用する方法についても、以下と同じ考え方に従う必要があります。
この例では、HTTP を使ってトークンを手動で取得します。これは、Web サービスを利用するアプリケーションが GAM を使用していないか、GeneXus 16 Upgrade 7 より前のバージョンを使用している (GAM リモート REST がサポートされていない) 場合にあたります。
1.アプリケーションの
REST Web サービスを作成します。REST Web サービスは、
ビジネスコンポーネント、
データプロバイダー、
プロシージャーのいずれかで、POST、PUT、DELETE、GET メソッドを公開できます。
2.ナレッジベースのセキュリティのプロパティを確認します (
[ Enable Integrated Security ] プロパティ)。このプロパティを設定すると、GAM オブジェクトがナレッジベースに組み込まれ、再編成を行って GAM リポジトリを作成するとともに、このリポジトリの初期化が行われます。詳しくは、「
GeneXus での GAM リポジトリの管理」を参照してください。
3.GAM API (または
GAM Backend) を使用して
GAM アプリケーションを作成し、GAM リポジトリ内で REST Web サービスのアプリケーションを識別します。
4.アプリケーションへのアクセス許可を許可するユーザーを作成します。一部のユーザーにアクセスを制限する場合、
GAM アクセス許可を設定する必要があります。
GAM Examples フォルダに、
GAM アプリケーション、
GAM ロール、GAM ユーザー、
GAM アクセス許可の管理を容易にする Web アプリケーション (GAM Backend) が含まれています。
5.REST サービスへのアクセスを有効にするには、利用者に Client_Id、ユーザー名、パスワードを提供する必要があります。
GAM API を使用して Client_Id を取得する方法については、GAMExampleApplicationEntry オブジェクト (GAM Examples フォルダにあります) を参照してください。
特に、GAMExampleWWApplications を実行する場合、リポジトリの任意のアプリケーションのアプリケーションプロパティを編集するときに、このアプリケーションの Client_Id を確認します。
OAuth には、クライアント (アプリケーション)、ユーザー (userId、userPwd)、アクセス許可 (適用範囲= Read、Write、FullControl) の概念があります。
GAM を使用するよう設定されている GeneXus アプリケーションは、各
GAM アプリケーションの Client_Id を生成します。
安全な GX REST Web サービスを利用するには、次の操作を行う必要があります:
1.アプリケーションの Client_Id、このアプリケーションへのアクセス権限を持つユーザー名およびパスワードを指定します。
2.Web サービスへの POST を試みる前に、
access_token を取得します。この access_token を取得するには、Client_Id とユーザーの資格情報を POST するか、GAMRepository.GetOauthAccessToken() メソッドを使用する必要があります。詳細な手順は次のとおりです:
- まず、access_token を取得します。
HTTP://<SERVER>/<APPDIR>/oauth/access_token
本文の構成:
client_id=<client_id>&grant_type=password&scope=FullControl&username=<user_name>&password=<user_pwd>
例:
client_id=f719771ad52a42919a221bc796d0d6b0&granttype=password&scope=FullControl&username=admin&password=admin123
次の例に示すように、HTTPResponse では、access_token を含む JSON 応答になります:
{
"access token" : "c9919e10e118" << 以降のすべての呼び出しで使用する必要があるアクセストークン
"scope" : "FullControl"
}
注: GAMRepository.GetOauthAccessToken() は、GeneXus 16 Upgrade 8 以降で利用できます。
- GetOauthAccessToken を使用します
GAMRepository.GetOauthAccessToken(&UserName, &Password, &GAMLoginAdditionalParameters, &GAMOauthAdditionalParameters, &GAMSession, &GAMErrors)
例:
&GAMOauthAdditionalParameters.ClientId = "f719771ad52a42919a221bc796d0d6b0"
&GAMOauthAdditionalParameters.ClientSecret = &ClientSecret
&GAMLoginAdditionalParameters.AuthenticationTypeName = !"local"
&AccessTokenSDT = GAMRepository.GetOauthAccessToken(!"admin", !"admin123",&GAMLoginAdditionalParameters,&GAMOauthAdditionalParameters,&GAMSession,&GAMErrors)
2.REST Web サービスへのすべての呼び出しにこのヘッダーを含める必要があります (同じ例に従います):
Authorization: OAuth c9919e10e118
下記に示す例は、製品リスト ("DPProduct" は REST Web サービスとして公開されるデータプロバイダー) の取得方法を示している完全なサンプルコードです。これは安全な Web サービスです (ナレッジベースで GAM が有効になっています)。
Client Id は、GAM Backend で自動的に定義されたアプリケーションから取得されます。
HTTPClient データタイプを使用して、REST Web サービスを利用します。
//最初に HTTP POST で access_token を取得
&addstring ='client_id=be47d883307446b4b93fea47f9264f88&grant_type=password&scope=FullControl&username=test&password=test'
&httpclient.Host= &server
&httpclient.Port = &port
&httpclient.BaseUrl = &urlbase + '/oauth/'
&httpclient.AddHeader("Content-Type", "application/x-www-form-urlencoded")
&httpclient.AddString(&addstring)
&httpclient.Execute('POST','access_token')
&httpstatus = &httpclient.StatusCode
msg('Http status: ' + &httpstatus,status)
&result = &httpclient.ToString()
&AccessTokenSDT.FromJson(&result) //この構造を持つ SDT にアクセストークンをロード (*)
//DPProduct Web サービスの呼び出し
&httpclient.BaseUrl = &urlbase + '/rest/'
&httpclient.AddHeader("Content-Type", "application/json")
&httpclient.AddHeader('Authorization','OAuth ' + &AccessTokenSDT.access_token)
&httpclient.AddHeader("GENEXUS-AGENT","SmartDevice Application")
&httpclient.Execute('GET','DPProduct')
これはもう 1 つの例で、今回は GAMRepository.GetOauthAccessToken() メソッドを使用しています。
//最初に access_token を取得
&httpclient.Host= &server
&httpclient.Port = &port
&GAMOauthAdditionalParameters.ClientId = "f719771ad52a42919a221bc796d0d6b0"
&GAMOauthAdditionalParameters.ClientSecret = &ClientSecret
&GAMLoginAdditionalParameters.AuthenticationTypeName = !"local"
&AccessTokenSDT = GAMRepository.GetOauthAccessToken(!"admin", !"admin123",&GAMLoginAdditionalParameters,&GAMOauthAdditionalParameters,&GAMSession,&GAMErrors)
//DPProduct Web サービスの呼び出し
&httpclient.BaseUrl = &urlbase + '/rest/'
&httpclient.AddHeader("Content-Type", "application/json")
&httpclient.AddHeader('Authorization','OAuth ' + &AccessTokenSDT.access_token)
&httpclient.AddHeader("GENEXUS-AGENT","SmartDevice Application")
&httpclient.Execute('GET','DPProduct')
複数のテナントに対応するサーバー上でサービスを実行する場合は (GAM には、それぞれ異なるテナントに対応する
n 個のリポジトリがあります)、HTTP POST の本文に情報を追加して、GAM がどのリポジトリに接続するかを確立する必要があります。この場合、サーバー上の
connection.gam には、リポジトリごとに 1 つの
リポジトリ接続があります。
この操作は、本文の additional_parameters (AuthenticationTypeName と Repository (接続先リポジトリの GUID) を含む JSON) を使用して実行します。
前述の additional_parameters を含む、access_token サービスへの HTTP POST の例は次のとおりです:
POST /Customer1.NetEnvironment/oauth/access_token HTTP/1.1
GeneXus-Agent: SmartDevice Application
Content-Length: 248
Content-Type: application/x-www-form-urlencoded
Host: 10.0.2.2:88
client_id=ad80c07c0a1046029c0655cdd9d99493&grant_type=password&scope=FullControl&username=adminfull&password=adminfull&additional_parameters={"AuthenticationTypeName":"local","Repository":"1e89a9ca-bc52-482b-a344-c4cda4a9cc8f"}
注:
- Xev2U4 以降、Genexus-Agent:SmartDevice Application ヘッダーは必須です。
- 「access_token」サービスに送信された JSON 本文内の grant_type は GAM の認証タイプに対応するため、「password」はローカル認証を意味します。その他の有効な値は Facebook、Twitter、Google、externalwebservice、custom、device (自動登録用) です。
- 「エラー 39: アプリケーションが見つかりません」が返された場合は、次のヘッダーを追加してみてください: Content-Type: application/x-www-form-urlencoded
認証が成功した後、GAMUser 静的メソッドを使用してユーザー情報を取得できます。
クライアントとサーバー間の通信チャネルを保護するために HTTPS を使用することを推奨します。
安全なネイティブ モバイル アプリケーションのアーキテクチャ
Troubleshooting secure rest services