初めに
AWS のAPIGatewayには開発者ポータルの機能が設けられており、今回そちらをご紹介します。
まず、初めに開発者ポータルは機能といいましたが、厳密には機能ではなく、AWSが開発者ポータル用のアプリを公開しており、ユーザがデプロイして利用する形となります。
開発者ポータルを利用することで開発者に安全にAPIを公開することが可能となります。
主な機能は以下の通りです。
- ポータルへの認証/認可機能
- 公開APIのアクセス制御
- APIドキュメント表示
- APIのキー発行
- APIのテスト実行
- APIの使用状況確認
- API の SDK提供
開発者ポータルは Apache 2.0 ライセンスで提供されており、以下で公開されています。
その為、ユーザは必要に応じてアプリをカスタマイズして利用することも可能です。
尚、AWSが以下にサンプルアプリも公開しております。
https://developer.exampleapigateway.com/
AWS構成について
AWSの構成については、SPAで実装されております。
以下に構成図が公開されております。
https://github.com/awslabs/aws-api-gateway-developer-portal/wiki/Components
デプロイ方法
開発者ポータルのデプロイ方法についてですが、主に2つの方法が提供されています。
- AWS Serverless Application Repositoryからデプロイ
- Github からPullしてきてAWS SAMでデプロイ
詳細は以下公式ドキュメントに記載されているため割愛いたします。
https://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/apigateway-developer-portal.ht
デプロイするとCloudFormationでリソースが作成され、デプロイ後、CloudFormationでURLが確認できます。
以降は補足説明となります。
デプロイ時のオプション
開発者ポータルを起動する際にはさまざまなオプションが存在しています。
多くはデプロイするときのリソース名(S3バケット名等)を指定するオプションですが、それ以外にアプリの構成や設定に関係するオプションがあります。
今回はそちらを紹介します。
| オプション名 | 内容 |
|---|---|
| AccountRegistrationMode | アプリのサインアップする方法を設定できます。 open：ユーザ自身がサインアップすることが可能なモード invite：管理者がユーザを招待してサインアップするモード |
| CustomDomainName | 独自ドメインを利用するときに利用。 利用時にはACM証明書を発行している必要はある様です。 |
| DevPortalAdminEmail | 開発者ポータルにはユーザから問い合わせを受ける機能があります。 その問い合わせ先のメールアドレスを指定します。 |
| DevelopmentMode | true を選択するとセキュリティ機能が緩めた構成でデプロイできます。 これを利用することでポータルの開発を容易にすることが目的の様です。 その為、ポータルのカスタイズ等での開発利用時以外はセキュリティの 観点で利用しないほうが良いです。 緩まるセキュリティ内容 OAI、SSL、S3バケットポリシー、Cognitoコールバック検証、CORSなど |
| LocalDevelopmentMode | Localで開発する場合のオプションです。 |
| UseRoute53Nameservers | 独自ドメインを利用する際に指定するオプションです。 TrueにするとR53に指定したドメインのHosted Zone の設定と、レコードセットの設定を行います。 |
また、追加オプションは以下の通りです。
| オプション名 | 内容 |
|---|---|
| StaticAssetRebuildMode | S3 にアップされたコンテンツを上書きするかの指定です。置き換えるときはoverwrite-content を指定します。 使用目的はデプロイ後にアプリをカスタマイズした際に、カスタマイズしたアプリに置き換えたい場合に本オプションを指定しています。 |
デプロイ時のTips
AccountRegistrationModeでinviteを指定すると管理者ユーザが作成できない
AccountRegistrationModeをinvite で設定するとユーザ作成は管理者ユーザが行う事になります。
管理者ユーザの作成は公式の情報では以下の手順となっておりますが、 AccountRegistrationModeをinvite とした状態では、下記1の管理者ユーザ用のユーザが作成できませんでした。
- アプリ側でユーザをサインアップ
- CognitoのUserPoolでサインアップしたユーザのグループにadminグループを追加
その為、最初のデプロイの際には AccountRegistrationModeをopenでデプロイし、上記手順に従い管理者ユーザを作成、その後、CloudFormationの変更セットでAccountRegistrationModeのパラメータをinviteに変更する対応を行いました。
機能説明
認証/認可
認証/認可はCognitoを利用して実装されており、Cognitoでユーザが作成されていない場合は、APIの参照や実行が出来ません。
ユーザ登録は前述の通り、デプロイ時のモード選択により以下2通りの方法を選択できます。
- ユーザ自身がサインアップ
- 管理者が招待
ユーザ自身がサインアップする際には、アプリのサインアップ画面にメールアドレスとパスワードを入力すると、指定したメールアドレス宛に確認メールが送付されるため、メールのリンクをクリックすることでサインアップが完了します。
管理者が招待する場合は、管理者でアプリにログインし、管理者メニューからメールアドレスを入力し、invite操作を行うと、入力したメールアドレス宛にユーザ名(メールアドレス)とパスワードが記載されたメールが送信され、ユーザが追加されます。
inviteされたユーザは初サインイン時に強制的にパスワード変更が求められます。
公開APIのアクセス制御
管理者ユーザのみが行えます。アプリで公開するAPIを設定することができます。
公開するAPIの指定はステージ毎に行える為、dev ステージのみ公開することも可能です。
ただし、ユーザ毎に権限を分けることができないため、ユーザ毎に権限を変更したい場合は、開発者ポータル自体を分ける必要があります。
APIと使用量プランが紐づいている場合、アクセス制御画面で紐づいている使用量プランが確認ができ、後述する「APIのアクセスキー発行」ではその使用量プランに対するAPIキーが発行されます。
なお、一つのAPIに複数の使用量プランがひもづいているケースの場合でも、開発者ポータルで確認ができるのは一つの使用量プランのみで、且つ利用できる使用量プランは選択できない仕様になっている様です。
APIの公開設定にはSDKのダウンロード許可設定もあり、こちらをEnableにするとユーザが開発者ポータルからSDKがダウンロードできる様になります。
APIドキュメント表示
APIドキュメントとしてリソース毎にメソッド、パラメータ、レスポンスが確認できます。
APIキー発行
ユーザがサインアップするとそのユーザ用のAPIキーが自動で発効されます。APIキーはMydashboard画面で確認ができます。
ただし、この時点ではAPIキーが各APIの使用量プランとは紐づいていない状態です。
APIキーと使用量プランを紐づける場合、API画面でSubscribeボタンを押す事により実施できます。
尚、使用量プランと紐づいていないAPIについては、Subscribeボタン自体が存在していなく、APIキーがなくてもAPIは実行が可能です。(当然ではありますが…)
APIのテスト実行
API画面でAPIのテスト実行が行えます。
自身が実行したAPIの利用状況については、Mydashboard画面で確認ができます。
SDKのダウンロード
管理者設定でAPIのSDKのダウンロード許可設定を与えている場合、以下の様にAPI画面からSDKがダウンロードできる様になります。
開発者ポータルのカスタマイズについて
前述したとおり、開発者ポータルは Apache 2.0 ライセンスで提供されておりGithubで公開されているため、カスタマイズして利用することも可能です。
公開されているコードはフロントエンドのコード、バックエンドのコード、SAMテンプレートが公開されています。
簡単なカスタマイズ内容については以下に掲載されています。
https://github.com/awslabs/aws-api-gateway-developer-portal/wiki/Customization
また、応用としてSAMテンプレートも変更が可能であるため、AWSの構成自体もカスタマイズして利用することが可能です。
具体例としては、以下の様な事が行えます。
- 開発者ポータルにIP制限をかけたい
- AWS WAF 付きの構成に変更 or
- API Gateway にリソースポリシーを設定