How to check the API security using Swagger UI

In Kuroco, Swagger UI can be used to check the operation and specifications of each created API.

This tutorial explains how to check the topic data on Swagger UI with the 4 patterns of security settings below.

• Display topic data with Security: None
• Display topic data with Security: Cookie
• Display topic data with Security: Static Token
• Display topic data with Security: Dynamic Token

About Swagger UI

Swagger UI is an open-source playground that visualizes OpenAPI, which is the standard specification of API, on the WEB.
This tutorial doesn't explain the Detailed usage of Swagger UI. Please check Swagger official website for details.

How to display the Swagger UI page

Select desired API from [API] on the side menu, and click [Swagger UI] on the API page.

Swagger UI page will be displayed.

Prerequisites

This tutorial supposes that the basic API is already created.
If not done yet, please create an API configuration.

Next is how to check the topic data on Swagger UI.

Display topic data with Security: None

Check the following 2 points on Swagger UI with security settings: none.

• When the endpoint's authorization is None, the request or response is sent properly.
• When the endpoint's authorization is NOT None, the request gets rejected.

When the endpoint's authorization is None, the request or response is sent properly.

First, let's check that the response is sent properly when the endpoint's authorization is None.

1. Change the security setting.
First, change the security setting.
Click [Security] on the API page.

Change the "Security" to [None] and click [Save].

2. Change the endpoint's authorization.
Click [Update] button of the desired endpoint on the API list page. In this tutorial, news is used as an example.

Select None on "authorization" and click [Update].

3. Check on the Swagger UI page.
Click [Swagger UI] and access the Swagger UI page.

Select news endpoint.

Click [Try It Out].

Scroll to the bottom and click [Execute].

You can see that there is a response with response code: 200.

When the endpoint's authorization is NOT None, the request gets rejected.

Next, let's check that the access gets rejected when news configuration requires an authorization.

1. Change the endpoint's authorization.
Click [Update] button of news endpoint on the API list page.

Select any option except None on "authorization" and click [Update]. In this tutorial, GroupAuth:Admin is selected as an example.

2. Check on the Swagger UI page
Click [Swagger UI] and access the Swagger UI page.

Select news endpoint.

Click [Try It Out].

Scroll to the bottom and click [Execute].

You can see that there is no response with response code: 401.

The check using the "security setting: none" is now complete.

Display topic data with Security: Cookie

Next, let's check the topic data on Swagger UI with security setting: Cookie.

1. Change the security setting.
Change the security setting to [Cookie].
Click [Security] on the API page.

Change the "security" to [Cookie] and click [Save].

2. Change the authorization of the endpoint.
Click [Update] button of the desired endpoint on the API list page. In this tutorial, news is used as an example.

Select any option except None on "authorization" and click [Update]. In this tutorial, GroupAuth:Admin is selected as an example.

3. Check the contents on Swagger UI page.
Click [Swagger UI] and access the Swagger UI page.

Select news endpoint.

Click [Try It Out].

Scroll to the bottom and click [Execute].

You can see that there is no response with response code: 401.

This is because the access to news was rejected for a user without GroupAuth: Admin authorization.
Consequently, it's necessary to start by creating an additional endpoint for login, then communicate to Kuroco server that this user has the GroupAuth: Admin authorization. The authentication method is the same as previously set up, and the session is maintained using cookie authentication.

Moving forward, the next step will be to create an additional endpoint for login, then log in and try [Execute] again to finally confirm that the response is sent properly.

4. Change the account authorization to Admin.
Set your own account's authorization to Admin.
Click [Campaign] -> [Member] on the side menu and select your own account.
Then, select "Admin" on the "Belonging group" and click [Update].

5. Check the login on Swagger UI page
Let's check the login on Swagger UI page.
Click [Swagger UI] and access the Swagger UI page.

​Click login endpoint.

Click [Try it out].

You can write a code in the Request body field.

Input the following login information in it.

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

Note: Input your email address and password in YOUR_MAIL_ADDRESS@example.com and PASSWORD.

Click [Execute] after entering the code on the Request body field.

You can see that there is a response with response code: 200.

6. Recheck the contents on Swagger UI page.
Let's recheck the news endpoint again on the Swagger UI page.
Select news endpoint.

Click [Try It Out].

Scroll to the bottom and click [Execute].

You can see a response now with the code: 200, while the response code was 401 earlier.

Note about the case of security setting: Cookie
In the case of security setting: Cookie, the domains of front and Kuroco need to be the same to avoid third-party cookie restrictions.
(Have to match both domains and make it a first-party Cookie.)
Therefore, for example, even if you access login-> news from the local front-end (Nuxt.js), the request gets rejected because the domain (URL) is from http: // localhost: 3000.

Display topic data with Security: Static Token

Next, let's check the topic data on Swagger UI with security setting: Static Token.

1. Change the security setting.
Click [Security] on the API page.

Change the security setting to [Static Token] and click [Save].

2. Change the authorization of the endpoint.
Click [Update] button of the news endpoint.

Change the "Security" to [None] and click [Save].

3. Check the Swagger UI page.
Click [Swagger UI] and access the Swagger UI page.

Select news endpoint.

Click [Try It Out].

Scroll to the bottom and click [Execute].

You can see that there is no response with response code: 401.

That's because access requests without a token are rejected.

In the case of Static Token, a token is used for user authentication.
When a user sends a request, custom request header (x-rcms-api-access-token) is added to the request header and the user is authenticated by matching the value.
Kuroco allows you to customize Swagger UI to dynamically generate this token and keep it on the Kuroco server.
In addition, you can set up the automatic attachment on the custom request header when sending a request.

4. Generate static Token
Next, let's generate the Static Token.
Specify the expiration date from [Generate Static Access Token] in the Swagger UI page and click [Generate].

Copy the generated token.

5. Configure the generated Static Token
Next, configure the generated Static Token to be automatically added to the request header.
Click [Authorize] on the Swagger UI page.

Paste the token you have copied to the "Value" and click [Authorize].

"Available authorizations" will be displayed. Close it from [Close] button.

6. Recheck the contents on the Swagger UI page.
Let's recheck the news endpoint again on the Swagger UI page.
Select news endpoint.

Click [Try It Out].

Scroll to the bottom and click [Execute].

You can see a response now with the code: 200, while the response code was 401 earlier.

You can see from the "Curl" that the static token generated by X-RCMS-API-ACCESS-TOKEN is attached to this request.

Note: in case of security setting: Static Token
There is no need to match the domains in a request by Static Token, unlike the case of Cookie.
Therefore, if CORS is set up properly, you can access from the local environment.

If you execute the sample request (Curl) displayed on Swagger UI locally, you can confirm that it responds normally as shown below.

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

# Response is displayed.
# {"errors":[],"messages":[],"list":[{"topics_id": ...

In addition, you can also access from the front-end (Nuxt). Modify the code in pages / news / index.vue to send the Static Token in the request header as below.

 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': 'value of Static Token' }
+              }
+            )
             return { response }
         }catch (e) {
             console.log(e.message)

Note: Be careful not to leak the statically generated token, as it will allow access to the API from anywhere.

Display topic data with Security: Dynamic Token

Next, let's check the topic data on Swagger UI with security setting: Dynamic Token.

1. Change the security setting.
Click [Security] on the API page.

Change the security setting to [Dynamic Token] and click [Save].

2. Change the authorization of the endpoint.
Click [Update] button of the news endpoint.

Select any option except None on "authorization" and click [Update]. In this tutorial, GroupAuth:Admin is selected as an example.

3. Check Swagger UI page.
Click [Swagger UI] and access the Swagger UI page.

Select news endpoint.

Click [Try It Out].

Scroll to the bottom and click [Execute].

You can see that there is no response with response code: 401.

This is because the token is not included in the request, and even if it is included, access will be denied if it is not the value of the token generated by a user with GroupAuth: Admin authorization.

In the case of Dynamic Token, tokens are used for the user authentication.
When a user makes a request, a custom request header (x-rcms-api-access-token) is added to the request header, and authentication is performed by matching the value. Unlike Static Tokens, Dynamic Tokens cannot generate/set fixed tokens.
Therefore, create an additional endpoint for login and an endpoint for token generation, and dynamically generate tokens by login-> token generation.
To access a secure endpoint, add a custom request header (x-rcms-api-access-token) to the request header and send the value of the dynamically generated token, similar to the Static Token.
Kuroco server verifies this value for authentication.
Additionally, It's also possible to set up the automatic addition of custom request headers to requests on the page.

4. Change the account authorization to Admin.
Set your own account's authorization to Admin.
Click [Campaign] -> [Member] on the side menu and select your own account.
Then, select "Admin" on the "Belonging group" and click [Update].

**5. Let's check the login on Swagger UI page.
Click [Swagger UI] and access the Swagger UI page.

​Click login endpoint.

Click [Try it out].

You can write a code in the Request body field.

Input the following login information in it.

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

Note: Input your email address and password in YOUR_MAIL_ADDRESS@example.com and PASSWORD.

Click [Execute] after entering the code on the Request body field.

If the request is successfully sent, you will get a response containing grant_token, you should copy this value.

Note: grant_token is a one-time token to get the token you actually need ( access_token).

Next, click the token on the Swagger UI page.

Click [Try it out].

Entering code into the Request body field will become enabled now.

Input the following in the Request body field.

{
  "grant_token": "GRANT_TOKEN"
}

Note: Input the value you just copied in grant_token.

Scroll to the bottom and click [Execute].

If the request is successful, an access_token response will be displayed, copy the value shown there.

6. Set up the generated Dynamic Token.
Next, let's set up so that the generated Dynamic Token is added to the requested header automatically.
Click [Authorize] on the Swagger UI page.

Paste the token you have copied to the "Value" and click [Authorize].

"Available authorizations" will be displayed. Close it from "Close" button.

7. Recheck the contents on Swagger UI page.
Let's recheck the news endpoint again on the Swagger UI page.
Select news endpoint.

Click [Try It Out].

Scroll to the bottom and click [Execute].

You can see a response now with the code: 200, while the response code was 401 earlier.

Also, if you check Curl, you can see that this request was made with the Dynamic Token generated by x-rcms-api-access-token.

Note: in case of security setting: Dynamic Token
Unlike Cookie, in the request by Dynamic Token, there is no need to match the domain.
Therefore, if CORS is set up properly, you can access from the local environment.

As with the Static Token, it is also possible to execute the sample request (Curl) displayed on the Swagger UI locally and display the response. In this case, as mentioned above, you need to execute in the order of login-> token-> news.

You can also access it from the front-end (Nuxt).
As shown below, change the code of pages/news/index.vue, execute it in order of login->token->news, and adjust it so that the generated token is added to the request header automatically. (Input your email and password.)

 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)