Create service
curl -i -X POST 

--url http://localhost:8001/services/ 

--data 'name=crud' 

--data 'url=http://iris:52773/crud/'


What do we see here, to create a service we simply need it's url.
3.2. Create a route


 IAM Portal 
 Rest API 







Create route
curl -i -X POST 

--url http://localhost:8001/services/crud/routes 

--data 'name=crud-route' 

--data 'paths=/persons/*' 

--data 'strip_path=false'

What do we see here, to create a route we need :

it's service name
a path where RegEx is allowed

3.3. Test it !
Original API

Legacy
curl –i --location --request GET 'http://localhost:52773/crud/persons/all' 

--header 'Authorization: Basic U3VwZXJVc2VyOlNZUw=='

Proxy API

KONG
curl –i --location --request GET 'http://localhost:8000/persons/all' 

--header 'Authorization: Basic U3VwZXJVc2VyOlNZUw=='

What do we see here :

Nothing new on legacy side.
On kong side :

We change the port
The path corresponds to the route
We still need to authenticate



4. Second, go further with plugin
To go further, we will try to auto-authenticate Kong to the IRIS endpoint.
To do so, we will use and plugin, resquest-transformer.

4.1. Add a plugin to the service


 IAM Portal 
 Rest API 






Create plugin
curl -i -X POST 

--url http://localhost:8001/services/crud/plugins 

--data 'name=request-transformer' 

--data 'config.add.headers=Authorization:Basic U3VwZXJVc2VyOlNZUw==' 

--data 'config.replace.headers=Authorization:Basic U3VwZXJVc2VyOlNZUw=='

4.2. Test it !

Legacy
Original API
curl –i --location --request GET 'http://localhost:52773/crud/persons/all'

Proxy API

KONG
curl –i --location --request GET 'http://localhost:8000/persons/all'

What do we see here :

Error 401 on the original API
We reach the data without authentication

5. Third, add our own authentication
What we want to achieved here is to add our own authentication without any distuption of the original API.

5.1. Add consumers


 IAM Portal 
 Rest API 






Add consumer anonymous
curl -i -X POST 

--url http://localhost:8001/consumers/ 

--data "username=anonymous" 

--data "custom_id=anonymous"






Add consumer user
curl -i -X POST 

--url http://localhost:8001/consumers/ 

--data "username=user" 

--data "custom_id=user"


5.2. Add Basic auth plugin


 IAM Portal 
 Rest API 






Enable basic auth for service
curl -i -X POST http://localhost:8001/routes/crud-route/plugins 

--data "name=basic-auth" 

--data "config.anonymous=5cc8dee4-066d-492e-b2f8-bd77eb0a4c86" 

--data "config.hide_credentials=false"


Where :

config.anonymous = uuid of anonymous consumer

5.3. Add ACL Plugin


 IAM Portal 
 Rest API 







Enable ACL
curl -i -X POST http://localhost:8001/routes/crud-route/plugins 

--data "name=acl" 

--data "config.whitelist=user"


5.4. Configure USER with ACL and credentials


 IAM Portal 
 Rest API 






Add consumer group
curl -i -X POST 

--url http://localhost:8001/consumers/user/acls 

--data "group=user"
Add consumer credentials
curl -i -X POST http://localhost:8001/consumers/user/basic-auth 

--data "username=user" 

--data "password=user"


5.5. Test it !
Original API

Legacy
curl –i --location --request GET 'http://localhost:52773/crud/persons/all' 

--header 'Authorization:Basic dXNlcjp1c2Vy'

**Proxy API **

KONG
curl –i --location --request GET 'http://localhost:8000/persons/all' 

--header 'Authorization:Basic dXNlcjp1c2Vy'

6. Exercice, Rate-Limiting

Enable Unauthenticated user
Limit rate by 2 calls per minutes to Unauthenticated user

6.1. Solution

Enable Unauthenticated user



 IAM Portal 
 Rest API 






Add consumer group
curl -i -X POST 

--url http://localhost:8001/consumers/anonymous/acls 

--data "group=user"



Limit rate by 2 calls per minutes to Unauthenticated user



 IAM Portal 
 Rest API 






Add rate limit consumer
curl -i -X POST 

--url http://localhost:8001/consumers/anonymous/plugins 

--data "name=rate-limiting" 

--data "config.limit_by=consumer" 

--data "config.minute=2"


7. Dev Portal

7.1. Overview
The Kong Developer Portal provides :

a single source of truth for all developers
intuitive content management for documentation
streamlined developer onboarding
role-based access control (RBAC)


7.2. Enable it !


 IAM Portal 
 Rest API 






curl -X PATCH http://localhost:8001/workspaces/default --data "config.portal=true"


7.3. Add your first spec
IAM Portal


Rest API

curl -X POST http://localhost:8001/default/files -F "path=specs/iam-training.yml" -F "contents=@misc/spec.yml"

7.4. Test it !
http://localhost:8003/default/documentation/iam-training

What happen ?
How-to solve it ?
7.5. Exercise

Add CORS plugin on route

7.5.1. Solution


 IAM Portal 
 Rest API 






Enable CORS
curl -i -X POST http://localhost:8001/routes/crud-route/plugins 

--data "name=cors"


8. Dev Portal, Part two, Authentication
8.1. Enable Basic Auth


 IAM Portal 
 Session Config (JSON) 






{
"cookie_secure": false,
"cookie_name": "portal_session",
"secret": "SYS",
"storage": "kong"
}

Enable role
curl -i -X POST http://localhost:8001/default/developers/roles 

--data "name=dev"


8.2.2. Add role to Spec
IAM Portal

Rest API

Enable role
curl 'http://localhost:8001/default/files/specs/iam-training.yml' -X PATCH -H 'Accept: application/json, text/plain, /'  --compressed -H 'Content-Type: application/json;charset=utf-8' -H 'Origin: http://localhost:8002' -H 'Referer: http://localhost:8002/default/portal/permissions/' --data-raw $'{"contents":"x-headmatter:\n  readable_by:\n    - dev\nswagger: '2.0'\ninfo:\n  title: InterSystems IRIS REST CRUD demo\n  description: Demo of a simple rest API on IRIS\n  version: '0.1'\n  contact:\n    email: apiteam@swagger.io\n  license:\n    name: Apache 2.0\n    url: 'http://www.apache.org/licenses/LICENSE-2.0.html'\nhost: 'localhost:8000'\nbasePath: /\nschemes:\n  - http\nsecurityDefinitions:\n  basicAuth:\n    type: basic\nsecurity:\n  - basicAuth: []\npaths:\n  /:\n    get:\n      description: ' PersonsREST general information '\n      summary: ' Server Info '\n      operationId: GetInfo\n      x-ISC_CORS: true\n      x-ISC_ServiceMethod: GetInfo\n      responses:\n        '200':\n          description: (Expected Result)\n          schema:\n            type: object\n            properties:\n              version:\n                type: string\n        default:\n          description: (Unexpected Error)\n  /persons/all:\n    get:\n      description: ' Retreive all the records of Sample.Person '\n      summary: ' Get all records of Person class '\n      operationId: GetAllPersons\n      x-ISC_ServiceMethod: GetAllPersons\n      responses:\n        '200':\n          description: (Expected Result)\n          schema:\n            type: array\n            items:\n              $ref: '#/definitions/Person'\n        default:\n          description: (Unexpected Error)\n  '/persons/{id}':\n    get:\n      description: ' Return one record fo Sample.Person '\n      summary: ' GET method to return JSON for a given person id'\n      operationId: GetPerson\n      x-ISC_ServiceMethod: GetPerson\n      parameters:\n        - name: id\n          in: path\n          required: true\n          type: string\n      responses:\n        '200':\n          description: (Expected Result)\n          schema:\n            $ref: '#/definitions/Person'\n        default:\n          description: (Unexpected Error)\n    put:\n      description: ' Update a record in Sample.Person with id '\n      summary: ' Update a person with id'\n      operationId: UpdatePerson\n      x-ISC_ServiceMethod: UpdatePerson\n      parameters:\n        - name: id\n          in: path\n          required: true\n          type: string\n        - name: payloadBody\n          in: body\n          description: Request body contents\n          required: false\n          schema:\n            type: string\n      responses:\n        '200':\n          description: (Expected Result)\n        default:\n          description: (Unexpected Error)\n    delete:\n      description: ' Delete a record with id in Sample.Person '\n      summary: ' Delete a person with id'\n      operationId: DeletePerson\n      x-ISC_ServiceMethod: DeletePerson\n      parameters:\n        - name: id\n          in: path\n          required: true\n          type: string\n      responses:\n        '200':\n          description: (Expected Result)\n        default:\n          description: (Unexpected Error)\n  /persons/:\n    post:\n      description: ' Creates a new Sample.Person record '\n      summary: ' Create a person'\n      operationId: CreatePerson\n      x-ISC_ServiceMethod: CreatePerson\n      parameters:\n        - name: payloadBody\n          in: body\n          description: Request body contents\n          required: false\n          schema:\n            type: string\n      responses:\n        '200':\n          description: (Expected Result)\n        default:\n          description: (Unexpected Error)\ndefinitions:\n  Person:\n    type: object\n    properties:\n      Name:\n        type: string\n      Title:\n        type: string\n      Company:\n        type: string\n      Phone:\n        type: string\n      DOB:\n        type: string\n        format: date-time\n"}'

What's important here is this part :
x-headmatter:
  readable_by:
    - dev

Refere to this documentation :
readable_by attribute
8.2.3. Test it !
8.2.3.1. Register a new developer

8.2.3.2. Approve this developer

8.2.3.3. Add role for this developer


curl 'http://localhost:8001/default/developers/dev@dev.com' -X PATCH --compressed -H 'Content-Type: application/json;charset=utf-8' -H 'Cache-Control: no-cache' -H 'Origin: http://localhost:8002' -H 'DNT: 1' -H 'Connection: keep-alive' -H 'Referer: http://localhost:8002/default/portal/permissions/dev/update' -H 'Pragma: no-cache' --data-raw '{"roles":["dev"]}'

8.3. Add Oauth2 for developer
In this part we will add an Oauth2 authentication for developers to use securely our crud API.
This flow will provide self-registration from developer and grant them access to the crud API.
8.3.1. First, remove basic auth
To do so, we will replace our basic auth to a bearToken one.
First disable our basic auth/acl.
IAM Portal

Rest API

Disable ACL Plugin
curl 'http://localhost:8001/default/routes/afefe836-b9be-49a8-927a-1324a8597a9c/plugins/3f2e605e-9cb6-454a-83ec-d1b1929b1d30' -X PATCH --compressed -H 'Content-Type: application/json;charset=utf-8' -H 'Cache-Control: no-cache' -H 'Origin: http://localhost:8002' -H 'DNT: 1' -H 'Connection: keep-alive' -H 'Referer: http://localhost:8002/default/plugins/acl/3f2e605e-9cb6-454a-83ec-d1b1929b1d30/update' -H 'Pragma: no-cache' --data-raw '{"enabled":false,"name":"acl","route":{"id":"afefe836-b9be-49a8-927a-1324a8597a9c"},"config":{"hide_groups_header":false,"whitelist":["user","dev","crud"]}}'

8.3.2. Second, add application-registration plugin


 IAM Portal 
 Rest API 






Create application-registration plugin
curl -i -X POST 

--url http://localhost:8001/services/crud/plugins 

--data 'name=application-registration' 

--data 'config.auth_header_name=authorization' 

--data 'config.auto_approve=true' 

--data 'config.display_name=auth' 

--data 'config.enable_client_credentials=true'


8.3.3. Link service and documentation
IAM Porta

Rest API

curl 'http://localhost:8001/default/document_objects' --compressed -H 'Content-Type: application/json;charset=utf-8' -H 'Cache-Control: no-cache' -H 'Origin: http://localhost:8002' -H 'DNT: 1' -H 'Connection: keep-alive' -H 'Referer: http://localhost:8002/default/services/create-documentation' -H 'Pragma: no-cache' --data-raw '{"service":{"id":"7bcef2e6-117c-487a-aab2-c7e57a0bf61a"},"path":"specs/iam-training.yml"}'

8.3.3.1. Test it !
From the dev portal logged as dev@dev.com, create a new application.

This will give you client_id and client_secret.
Theses can be used in the swagger dev portal.
Register this application to the crud service :

Get token:

curl --insecure -X POST https://localhost:8443/persons/oauth2/token 

--data "grant_type=client_credentials" 

--data "client_id=2TXNvDqjeVMHydJbjv9t96lWTXOKAtU8" 

--data "client_secret=V6Vma6AtIvl04UYssz6gAxPc92eCF4KR"

Use token :

curl --insecure -X GET https://localhost:8443/persons/all 

--header "authorization: Bearer u5guWaYR3BjZ1KdwuBSC6C7udCYxj5vK"

9. Secure Management Portal
9.1. Create an admin
As we have bootstrap Kong without a seed password.
We have to create an admin before enforcing RBAC.
To do so:

Go to Teams
Invite admin

Set Mail
Set Username

Set role to super admin


Invite


Go to Invited Admin
View
Generate link


9.2. Enable Basic Auth for Kong Manager
To enable this feature, we have to change the docker-compose file.
Add this to the iam service, environment
      KONG_ENFORCE_RBAC: 'on'
      KONG_ADMIN_GUI_AUTH: 'basic-auth'
      KONG_ADMIN_GUI_SESSION_CONF: '{"secret":"${IRIS_PASSWORD}","storage":"kong","cookie_secure":false}'

Restart the container

docker-compose down && docker-compose up -d

Go to the invited admin link :
http://localhost:8002/register?email=test.test%40gmail.com&username=admin&token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2MTYzMzYzNzEsImlkIjoiY2JiZGE5Y2UtODQ3NS00MmM2LTk4ZjItNDgwZTI4MjQ4NWNkIn0.sFeOc_5UPIr3MdlQrgyGvmvIjRFvSn3nQjo2ph8GrJA

9.3. Use Kong Admin API with RBAC
As RBAC is set, we can't use kong admin api anymore :

curl -s -X GET 

--url http://localhost:8001/routes

Get this error :
{"message":"Invalid credentials. Token or User credentials required"}

9.3.1. Create and admin user with a token

Go to Teams
RBAC Users
Add new user



curl -s -X GET 

--url http://localhost:8001/routes 

--header "Kong-Admin-Token: SYS"

10. Plugins

Kong come with high quality plugins.
But, what if, we need plugin that are not embedded. If we want community plugins ?
In this chapiter, we will talk about community plugins, how to import them.
Then, we will see how-to build our own plugin.
10.1. Import a community plugin
For this part, we will be using the jwt-crafter plugin.
This plugin adds the possibility to generate a JWT token within Kong itself, eliminating the need for an upstream service doing the token generation.
Here is the plugin :
https://github.com/grongierisc/kong-plugin-jwt-crafter

To install this plugin, as we are using the docker version, we have to build a new image who embed the plugin.
10.1.1. Build a new Kong/IAM docker image with the community plugin

Create a folder named iam at root of this git.
Create a dockerfile in this new folder
Create a folder named plugins

This is where we will add all our community plugins


Update the docker-compose file to enable the new plug in

In the plugins folder, git clone our community plugin.

git clone https://github.com/grongierisc/kong-plugin-jwt-crafter

The dockerfile should look like this:
FROM intersystems/iam:1.5.0.9-4

USER root
COPY ./plugins /custom/plugins

RUN cd /custom/plugins/kong-plugin-jwt-crafter && luarocks make

USER kong

What we see in this dockerfile ?
Simply to install a community plugin, we have to move to its root folder (where the rockspec is) and call luarocks make. That's it. You have installed the plugin.
For the docker-compose part :

Edit the iam iamge tag

intersystems/iam:1.5.0.9-4 -> intersystems/iam-custom:1.5.0.9-4


Add a build context

    build: 
      context: iam
      dockerfile: dockerfile


Enable the plugin in the environment variables

KONG_PLUGINS: 'bundled,jwt-crafter'

Now build our new iam image :

docker-compose build iam

10.1.2. Test it !

docker-compose up -d

If you go to plugin -> new, at the bottom of the list you should see the jwt-crafter plugin.

10.1.2.1. Use it !

Create a new service :



 IAM Portal 
 Rest API 






Create service
curl -i -X POST 

--url http://localhost:8001/services/ 

--data 'name=crud-persons' 

--data 'url=http://iris:52773/crud/persons/'



Create a route



 IAM Portal 
 Rest API 






Create route
curl -i -X POST 

--url http://localhost:8001/services/crud-persons/routes 

--data 'name=crud-route-jwt' 

--data 'paths=/crud/persons/*' 

--data 'strip_path=true'

Create plugin
curl -i -X POST 

--url http://localhost:8001/services/crud-persons/plugins 

--data 'name=request-transformer' 

--data 'config.add.headers=Authorization:Basic U3VwZXJVc2VyOlNZUw==' 

--data 'config.replace.headers=Authorization:Basic U3VwZXJVc2VyOlNZUw=='

Now we are set. The real use of jwt-crafter.

# Add acl to route
curl -i -X POST http://localhost:8001/routes/crud-route-jwt/plugins \
    --data "name=acl"  \
    --data "config.whitelist=test" \
    --data "config.hide_groups_header=false"

# Create service
curl -i -X POST \
  --url http://localhost:8001/services/ \
  --data 'name=jwt-login' \
  --data 'url=http://neverinvoked/'

# Create route
curl -i -X POST \
  --url http://localhost:8001/services/jwt-login/routes \
  --data 'name=jwt-login-route' \
  --data 'paths=/jwt/log-in'

# Enable basic auth for service
curl -i -X POST http://localhost:8001/routes/jwt-login-route/plugins \
    --data "name=basic-auth"  \
    --data "config.hide_credentials=false"

# Enable basic auth for service
curl -i -X POST http://localhost:8001/routes/jwt-login-route/plugins \
    --data "name=jwt-crafter"  \
    --data "config.expires_in=86400"

# Add consumer
curl -i -X POST \
   --url http://localhost:8001/consumers/ \
   --data "username=test"

# Add consumer group
curl -i -X POST \
   --url http://localhost:8001/consumers/test/acls \
   --data "group=test"

# Add consumer credentials
curl -i -X POST http://localhost:8001/consumers/test/basic-auth \
    --data "username=test" \
    --data "password=test"
curl -i -X POST http://localhost:8001/consumers/test/jwt \
    --data "key=test" \
    --data "algorithm=HS256"

# JWT plugins
curl -i -X POST http://localhost:8001/routes/crud-route-jwt/plugins \
    --data "name=jwt" 

Test it !

# test:test is base64 encoded
curl -H 'Authorization: basic dGVzdDp0ZXN0' localhost:8000/jwt/log-in

curl --location --request GET 'http://localhost:8000/crud/persons/all' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYW0iOiJ0ZXN0Iiwic3ViIjoiODJiNjcwZDgtNmY2OC00NDE5LWJiMmMtMmYxZjMxNTViN2E2Iiwicm9sIjpbInRlc3QiXSwiZXhwIjoxNjE2MjUyMTIwLCJpc3MiOiJ0ZXN0In0.g2jFqe0hDPumy8_gG7J3nYsuZ8KUz9SgZOecdBDhfns'

10.2. Create a new plugin

This is not the place to learn lua.

But I'll give you some tips like how to quickly restart IAM to test our new development.

10.2.1. File structure

kong-plugin-helloworld
├── kong
│   └── plugins
│       └── helloworld
│           ├── handler.lua
│           └── schema.lua
└── kong-plugin-helloworld-0.1.0-1.rockspec

By convention, kong plugins must be prefix by kong-plugin.

In our example, the name of the plugin is helloworld.

Three files are mandatory :

• handler.lua: the core of your plugin. It is an interface to implement, in which each function will be run at the desired moment in the lifecycle of a request / connection.
• schema.lua: your plugin probably has to retain some configuration entered by the user. This module holds the schema of that configuration and defines rules on it, so that the user can only enter valid configuration values.
• *.rockspec: Rockspec: a package specification file A declarative Lua script, with rules on how to build and package rocks *.rockspec - a Lua file containing some tables.

10.2.1.1. handler.lua

The plugins interface allows you to override any of the following methods in your handler.lua file to implement custom logic at various entry-points of the execution life-cycle of Kong:

var id = pm.response.json().id;
var name = pm.response.json().name;
pm.globals.set("service_crud_id", id);
pm.globals.set("service_crud_name", name);


Here we save from the response the id and name of the new services.
Then we can use it in the next route creation :


 Screen 
 Script 






service_crud_name = pm.globals.get("service_crud_name");


Here we retrieve the global variable "service_crud_name".
Then, use it in the actual call.


 Screen 
 Script 






{
"paths": [
"/persons/*"
],
"protocols": [
"http"
],
"name": "crud-persons",
"strip_path": false,
"service": {
"name": "{{service_crud_name}}"
}
}


11.1.3.1. Tips

paylaod can be either json or form-data

form-data :





json :


Easy way to get the json format, go to the manager portal, view, copy json :

11.2. Run it with newman

docker run  --rm -v "pwd/ci/":"/etc/newman" 

--network="iam-training_default" 

-t postman/newman run "DevOps_IAM.postman_collection.json" 

--environment="DevOps_IAM.postman_environment.json"