Swagger UIを利用して、APIのセキュリティを確認する

Kurocoでは、作成したAPIごとに動作や仕様を確認する用途として、Swagger UIを利用できます。

このチュートリアルでは、下記パターンのセキュリティ設定で、実際に記事データをSwagger UI上で確認する方法を紹介します。

参考) APIのセキュリティ設定については、API Securityを参照してください。

Swagger UIについて

Swagger UIは、APIの標準仕様であるOpenAPIをWEB上で可視化するオープンソースのプレイグラウンドです。
Swagger UIの詳細な使い方はこのチュートリアルでは省略しますので、詳しくはSwagger公式サイトをご確認ください。

Swagger UI画面の表示方法

サイドメニューより[API]を選択し、API画面より[API INFO]をクリックします。
Image (fetched from Gyazo)

Swagger UI画面が表示されます。
Image (fetched from Gyazo)

前提条件

今回はすでに基本的なAPIが作成済みであることを前提としています。
まだAPIを作成していない場合は、「KurocoとNuxt.jsで、コンテンツ一覧ページを作成する」を参考に、APIの設定をお願いいたします。

それではSwagger UI上で記事データを確認していきます。

セキュリティ設定:なし で記事データを表示する

ここではAPIのセキュリティ設定:なしの状態で、下記2点をSwagger UI上で確認します。

  • エンドポイントの認証がNoneのときは正常にリクエスト/レスポンスする
  • エンドポイントの認証がNone以外のときはリクエストが拒否される

エンドポイントの認証がNoneのときは正常にリクエスト/レスポンスする

まずはエンドポイントの認証がNoneのときの確認を行います。

1. セキュリティ設定を変更する
まずAPIのセキュリティ設定を変更します。
API画面より、[セキュリティ]をクリックします。
Image (fetched from Gyazo)

セキュリティより、APIのセキュリティ設定を[無し]に変更し、[Save]をクリックします。
Image (fetched from Gyazo)

2. エンドポイントの認証を変更する
次に作成済みのエンドポイントnewsの設定を変更します。
API一覧画面より、対象エンドポイントの[更新]をクリックします。
Image (fetched from Gyazo)

認証でNoneを選択し、[Update]をクリックします。
Image (fetched from Gyazo)

3. Swagger UI画面にて表示を確認する
[API INFO]をクリックしてSwagger UI画面に移動します。
Image (fetched from Gyazo)

newsエンドポイントを選択します。
Image (fetched from Gyazo)

[Try It Out]をクリックします。
Image (fetched from Gyazo)

画面下部に移動し、[Execute]をクリックします。
Image (fetched from Gyazo)

レスポンスコード:200でデータがレスポンスされることが確認できました。
Image (fetched from Gyazo)

エンドポイントの認証がNone以外のときはリクエストが拒否される

次に、newsが認証を要求する設定である場合、Swagger UI上でアクセス拒否されることを確認します。

1. エンドポイントの認証を変更する
作成済みのエンドポイントnewsの設定を変更します。
API一覧画面より、対象エンドポイントの[更新]をクリックします。
Image (fetched from Gyazo)

認証をNone以外にします。ここでは「GroupAuth:管理者」を指定します。
Image (fetched from Gyazo)

2. Swagger UI画面にて表示を確認する
[API INFO]をクリックしてSwagger UI画面に移動します。
Image (fetched from Gyazo)

newsエンドポイントを選択します。
Image (fetched from Gyazo)

[Try It Out]をクリックします。
Image (fetched from Gyazo)

画面下部に移動し、[Execute]をクリックします。
Image (fetched from Gyazo)

すると、レスポンスコード:401でデータがレスポンスされないことが確認できました。
Image (fetched from Gyazo)

以上でセキュリティ設定:なし の場合の確認が完了です。

セキュリティ設定:Cookie で記事データを表示する

次に、APIのセキュリティ設定:Cookie で、Swagger UI上で記事データを確認します。

1. セキュリティ設定を変更する
APIのセキュリティ設定を[Cookie]に変更します。
API画面より、[セキュリティ]をクリックします。
Image (fetched from Gyazo)

セキュリティより、APIのセキュリティ設定を[Cookie]に変更し、[Save]をクリックします。 Image (fetched from Gyazo)

2. エンドポイントの認証を変更する
次に作成済みのエンドポイントnewsの設定を変更します。 API一覧画面より、対象エンドポイントの[更新]をクリックします。
Image (fetched from Gyazo)

newsの認証をNone以外にします。ここではGroupAuth:管理者を指定して設定を変更し、[Update]をクリックします。
Image (fetched from Gyazo)

3. Swagger UI画面にてコンテンツ表示を確認する
[API INFO]をクリックしてSwagger UI画面に移動します。
Image (fetched from Gyazo)

newsエンドポイントをクリックします。
Image (fetched from Gyazo)

[Try It Out]をクリックします。
Image (fetched from Gyazo)

画面下部に移動し、[Execute]をクリックします。
Image (fetched from Gyazo)

すると、レスポンスコード:401でデータがレスポンスされないことが確認できます。
Image (fetched from Gyazo)

これはGroupAuth:管理者の権限を有するユーザーがアクセスしないとnewsはアクセス拒否するためです。
このためまずログイン用のエンドポイントを追加作成し、自分自身がGroupAuth:管理者の権限を有するユーザーであることをKurocoサーバーに伝える必要があります。
その際の認証方法は設定した通り、Cookie認証でセッションの維持をします。

そのため、次にログイン用のエンドポイントを追加作成し、ログイン後に再度[Execute]をして、データが正常にレスポンスされることを確認します。

4. アカウントを管理者の権限グループに設定する。
自分のアカウントを管理者の権限グループへと設定します。
メニューより[メンバー]をクリックし、ご自身のアカウントを選択します。
次に、「所属グループ」から「管理者」を選択し、[更新する]をクリックし、グループ設定を行います。
Image (fetched from Gyazo)

参考) グループ設定についての詳細は、管理画面マニュアルグループを作成するをご確認ください。

5. Swagger UI画面にてログインを確認する
Swagger UI画面にてログインを確認します。
[API INFO]をクリックしてSwagger UI画面に移動します。
Image (fetched from Gyazo)

loginエンドポイントをクリックします。
Image (fetched from Gyazo)

[Try it out]をクリックします。
Image (fetched from Gyazo)

すると、Request bodyフィールドが記述できるようになります。
Image (fetched from Gyazo)

こちらに下記のようにログイン情報を記載します。

Request body
{
  "email": "YOUR_MAIL_ADDRESS@example.com",
  "password": "PASSWORD",
  "login_save": 0
}

YOUR_MAIL_ADDRESS@example.comPASSWORD にはご自身のメールアドレスとパスワードを入力ください。

Request bodyに記入したら[Execute]をクリックします。
Image (fetched from Gyazo)

レスポンスコード:200でデータがレスポンスされることが確認できました。

Image (fetched from Gyazo)

6. 再度Swagger UI画面にてコンテンツ表示を確認する
この状態で、再度Swagger UI画面にて newsエンドポイントを確認します。
newsエンドポイントをクリックします。
Image (fetched from Gyazo)

[Try It Out]をクリックします。
Image (fetched from Gyazo)

画面下部に移動し、[Execute]をクリックします。
Image (fetched from Gyazo)

すると、先ほどはレスポンスコード:401でしたが、今回はレスポンスコード:200でデータがレスポンスされることが確認できます。
Image (fetched from Gyazo)

セキュリティ設定:Cookie の場合の注意点
セキュリティ設定:Cookie の場合は、サードパーティCookieの規制を回避するため、フロントとKurocoのドメインを合わせる必要があります。
(ドメインを一致させファーストパーティCookieにさせる必要があります)
そのため、例えばローカル上のフロントエンド(Nuxt.js)からlogin->newsとアクセスしても、 ドメイン(URL)がhttp://localhost:3000からのアクセスということになるため、リクエストは拒否されます。

セキュリティ設定:Static Token で記事データを表示する

次に、APIのセキュリティ設定:Static Token で、Swagger UI上で記事データを確認します。

1. セキュリティ設定を変更する
API画面より、[セキュリティ]をクリックします。
Image (fetched from Gyazo)

セキュリティより、APIのセキュリティ設定を[Static Token]に変更し、[Save]をクリックします。
Image (fetched from Gyazo)

2. エンドポイントの認証を変更する
次に作成済みのエンドポイントnewsの設定を変更します。
API一覧画面より、news エンドポイントの[更新]をクリックします。
Image (fetched from Gyazo)

認証で Noneを選択し、[Update]をクリックします。
Image (fetched from Gyazo)

3. Swagger UI画面にて表示を確認する
[API INFO]をクリックしてSwagger UI画面に移動します。
Image (fetched from Gyazo)

newsエンドポイントを選択します。
Image (fetched from Gyazo)

[Try It Out]をクリックします。
Image (fetched from Gyazo)

画面下部に移動し、[Execute]をクリックします。
Image (fetched from Gyazo)

すると、レスポンスコード:401でデータがレスポンスされないことが確認できます。
Image (fetched from Gyazo)

これはトークンがリクエストに含まれていないものは、アクセス拒否するためです。

Static Tokenにおいては、ユーザーの認証にトークンを使用します。
ユーザーがリクエストするときには、リクエストヘッダにカスタムリクエストヘッダ(x-rcms-api-access-token)を付与し、その値を照合することで認証をします。
Kurocoでは、Swagger UIをカスタマイズして、このトークンを動的に生成し、Kurocoサーバー上に保持することができます。
また、リクエストの際のカスタムリクエストヘッダの自動付与も、画面上で設定することが可能です。

4. static Tokenを生成する
次にStatic Tokenを生成します。
API情報画面の[Generate Static Access Token]からExpirationDateを指定して、[Generate]をクリックします。
Image (fetched from Gyazo)

するとTokenが発行されるので、値をコピーしておきます。
Image (fetched from Gyazo)

5. 生成したStatic Tokenの設定をする
次に、生成したStatic Tokenをリクエストヘッダに自動付与するように設定します。
API情報画面より、[Authorize]をクリックします。
Image (fetched from Gyazo)

Valueに先ほどコピーした値を入力し、[Authorize]をクリックします。
Image (fetched from Gyazo)

「Available authorizations」と表示されるので、[close]で画面を閉じます。
Image (fetched from Gyazo)

6. 再度Swagger UI画面にてコンテンツ表示を確認する
この状態で、再度Swagger UI画面にて newsエンドポイントを確認します。

newsエンドポイントを選択します。
Image (fetched from Gyazo)

[Try It Out]をクリックします。
Image (fetched from Gyazo)

画面下部に移動し、[Execute]をクリックします。
Image (fetched from Gyazo)

すると、先ほどはレスポンスコード:401でしたが、今回はレスポンスコード:200でデータがレスポンスされることが確認できます。
Image (fetched from Gyazo)

「Curl」を確認すると、このリクエストには、X-RCMS-API-ACCESS-TOKENが生成したStatic Tokenとともにリクエストされていることが確認できます。
Image (fetched from Gyazo)

セキュリティ設定:Static Token の場合の注意点
Static TokenによるリクエストはCookieとは異なり、ドメインを一致させる必要がありません。
このため、CORSが適切に設定されている場合、ローカルからアクセスすることが可能です。

Swagger UI上に表示したサンプルリクエスト(Curl)をローカル上で実行すると、以下のように正常にレスポンスすることが確認できます。

bash
curl -X 'GET' \
  'https://sample-support-kuroco.a.kuroco.app/rcms-api/2/news' \
  -H 'accept: */*' \
  -H 'X-RCMS-API-ACCESS-TOKEN: Static Tokenの値'

# レスポンスが表示されます。
# {"errors":[],"messages":[],"list":[{"topics_id": ...

また、フロントエンド(Nuxt)からもアクセスが可能です。
下記の用にpages/news/index.vueのコードを変更し、Static Tokenをリクエストヘッダで送信するように変更します。

diff
 export default {
     async asyncData ({ $axios }) {
         try {
-            const response = await $axios.$get(process.env.BASE_URL + '/rcms-api/2/news')
+            const response = await $axios.$get(process.env.BASE_URL + '/rcms-api/2/news', {
+                headers: { 'x-rcms-api-access-token': 'Static Tokenの値' }
+              }
+            )
             return { response }
         }catch (e) {
             console.log(e.message)

静的生成されたトークンは、どこからでもAPIにアクセスできるようになるものであるため、流出には十分ご注意ください。

セキュリティ設定:Dynamic Token で記事データを表示する

次に、APIのセキュリティ設定:Dynamic Token で、Swagger UI上で記事データを確認します。

1. セキュリティ設定を変更する
API画面より、[セキュリティ]をクリックします。
Image (fetched from Gyazo)

セキュリティより、APIのセキュリティ設定を[Static Token]に変更し、[Save]をクリックします。
Image (fetched from Gyazo)

2. エンドポイントの認証を変更する
次に作成済みのエンドポイントnewsの設定を変更します。
API一覧画面より、対象エンドポイントの[更新]をクリックします。
Image (fetched from Gyazo)

認証をNone以外を選択します。ここではGroupAuth:管理者を選択し、[Update]をクリックします。
Image (fetched from Gyazo)

3. Swagger UI画面にて表示を確認する
[API INFO]をクリックしてSwagger UI画面に移動します。
Image (fetched from Gyazo)

newsエンドポイントを選択します。
Image (fetched from Gyazo)

[Try It Out]をクリックします。
Image (fetched from Gyazo)

画面下部に移動し、[Execute]をクリックします。
Image (fetched from Gyazo)

すると、レスポンスコード:401でデータがレスポンスされないことが確認できます。
Image (fetched from Gyazo)

これはトークンがリクエストに含まれていない、トークンが含まれていた場合でも、GroupAuth:管理者の権限を有するユーザーが生成したトークンの値ではない場合、アクセス拒否するためです。

Dynamic Tokenにおいては、ユーザーの認証にトークンを使用します。
ユーザーがリクエストするときには、リクエストヘッダにカスタムリクエストヘッダ(x-rcms-api-access-token)を付与し、その値を照合することで認証をします。
Dynamic Tokenでは、Static Tokenとは異なり、固定のトークンを生成/設定することはできません。
このため、ログイン用のエンドポイントと、トークン生成用のエンドポイントを追加作成し、ログイン->トークン生成によりトークンを動的生成します。
セキュアなエンドポイントにアクセスするには、Static Token同様に、リクエストヘッダにカスタムリクエストヘッダ(x-rcms-api-access-token)を付与し、動的生成したトークンの値を送信します。
Kurocoサーバーはこの値を照合することで認証をします。 また、リクエストの際のカスタムリクエストヘッダの自動付与も、画面上で設定することが可能です。

4. アカウントを管理者の権限グループに設定する。
自分のアカウントを管理者の権限グループへと設定します。
メニューより[メンバー]をクリックし、ご自身のアカウントを選択します。
次に、「所属グループ」から「管理者」を選択し、[更新する]をクリックし、グループ設定を行います。
Image (fetched from Gyazo)

参考) グループ設定についての詳細は、管理画面マニュアルグループを作成するをご確認ください。

5. Swagger UI画面にてログインを確認する
Swagger UI画面にてログインを確認します。
[API INFO]をクリックしてSwagger UI画面に移動します。
Image (fetched from Gyazo)

loginをクリックします。
Image (fetched from Gyazo)

[Try it out]をクリックします。
Image (fetched from Gyazo)

すると、Request bodyフィールドが記述できるようになります。
Image (fetched from Gyazo)

こちらに下記のようにログイン情報を記載します。

Request body
{
  "email": "YOUR_MAIL_ADDRESS@example.com",
  "password": "PASSWORD",
  "login_save": 0
}

YOUR_MAIL_ADDRESS@example.comPASSWORD にはご自身のメールアドレスとパスワードを入力ください。

Request bodyに記入したら[Execute]をクリックします。
Image (fetched from Gyazo)

リクエストが成功した場合、grant_tokenを含んだレスポンスが返却されますので、値をコピーしておきます。
Image (fetched from Gyazo)

grant_tokenは、実際に必要なトークン(access_token)を取得するためのワンタイムトークンです。

次にSwagger UI画面より、tokenをクリックします。
Image (fetched from Gyazo)

[Try it out]をクリックします。
Image (fetched from Gyazo)

Request bodyフィールドが記述できるようになります。
Image (fetched from Gyazo)

Request bodyフィールドに下記のように記述します。

Request body
{
  "grant_token": "GRANT_TOKEN"
}

grant_tokenには、先ほど取得した値を入力してください

画面下部に移動し、[Execute]をクリックします。
Image (fetched from Gyazo)

リクエストが成功した場合、valueを含んだaccess_tokenのレスポンスが返却されます。
valueの値をコピーしておいてください。
Image (fetched from Gyazo)

6. 生成したDynamic Tokenの設定をする
次に、生成したDynamic Tokenをリクエストヘッダに自動付与するように設定します。
API情報画面より、[Authorize]をクリックします。
Image (fetched from Gyazo)

Valueに先ほどコピーした値を入力し、[Authorize]をクリックします。
Image (fetched from Gyazo)

「Available authorizations」と表示されるので、[close]で画面を閉じます。
Image (fetched from Gyazo)

7. 再度Swagger UI画面にてコンテンツ表示を確認する
この状態で、再度Swagger UI画面にて newsエンドポイントを確認します。
newsエンドポイントを選択します。
Image (fetched from Gyazo)

[Try It Out]をクリックします。
Image (fetched from Gyazo)

画面下部に移動し、[Execute]をクリックします。
Image (fetched from Gyazo)

すると、先ほどはレスポンスコード:401でしたが、今回はレスポンスコード:200でデータがレスポンスされることが確認できます。
Image (fetched from Gyazo)

また、Curlを確認すると、このリクエストには、x-rcms-api-access-tokenが生成したDynamic Tokenとともにリクエストされていることが確認できます。
Image (fetched from Gyazo)

セキュリティ設定:Dynamic Token の場合の注意点
Dynamic TokenによるリクエストはCookieとは異なり、ドメインを一致させる必要がありません。
このため、CORSが適切に設定されている場合、ローカルからアクセスすることが可能です。

Static Tokenのときと同様に、Swagger UI上に表示したサンプルリクエスト(Curl)をローカル上で実行して、レスポンスを表示することも可能です。
この場合は前述の通り、login->token->newsと順番に実行する必要があります。

また、フロントエンド(Nuxt)からもアクセスが可能です。 下記の用にpages/news/index.vueのコードを変更し、login->token->newsと順番に実行、生成したトークンをリクエストヘッダで送信するように変更します。 (メールアドレス、パスワードはご自分の情報を使用してください)

diff
 export default {
     async asyncData ({ $axios }) {
         try {
-            const response = await $axios.$get(process.env.BASE_URL + '/rcms-api/2/news')
+            const loginResponse = await $axios.$post(process.env.BASE_URL + '/rcms-api/2/login',  {
+              'email': 'YOUR_MAIL_ADDRESS@example.com',
+              'password': 'PASSWORD',
+              'login_save': 0
+            })
+            const grantToken = loginResponse.grant_token;
+
+            const tokenResponse = await $axios.$post(process.env.BASE_URL + '/rcms-api/2/token',  {
+              'grant_token': grantToken,
+            })
+            const accessToken = tokenResponse.access_token.value;
+
+            const response = await $axios.$get(process.env.BASE_URL + '/rcms-api/2/news', {
+                headers: { 'x-rcms-api-access-token': accessToken }
+              }
+            );
             return { response }
         }catch (e) {
             console.log(e.message)