iris-api-security-mediator
This is a ObjectScript Application to enforce authorization rules using XDATA into API methods.
Can be developed with Docker and VSCode,
can be deployed as ZPM module.
Installation for development
Clone/git pull the repo into any local directory e.g. like it is shown below (here I show all the examples related to this repository, but I assume you have your own derived from the template):
$ git clone git@github.com:yurimarx/iris-api-security-mediator.git
Open the terminal in this directory and run:
$ docker-compose up -d --build
Installation with ZPM
zpm:USER>install iris-api-security-mediator
How it Works
- Clone the project
$ git clone git@github.com:yurimarx/iris-api-security-mediator.git
- Build and up the project source code
$ docker-compose up -d --build
- Open the class src\dc\Sample\PersonREST and go to GetAllPersons ClassMethod (line 41). You will see this:
/// Retreive all the records of dc.Sample.Person
/// @security.and: roles: { PersonAdmin }
ClassMethod GetAllPersons() As %Status
{
#dim tSC As %Status = $$$OK
....
}
- Above the ClassMethod you see:
@security.and: roles: { PersonAdmin }
- When you set @security.and, you enforce the API calls to this method to authenticate to any user
- When you set roles: { YOURROLENAME }, you enforce the API calls to this method to the user have the role between {}
- So, in this example, the user needs the role PersonAdmin
- First all, test without the role, call http://localhost:52773/crud/persons/all (use _SYSTEM user or another user to authenticate)
- You will get the following message error:
{
"verb": "GET",
"url": "/persons/all",
"application": "/crud/",
"method": "GetAllPersons",
"error": "_SYSTEM is not authorized for this request. User Roles Allowed is not in User Roles"
}
- Now Go to Management Portal -> System Administration -> Security -> Roles
- Press button Create New Role. In the Name set PersonAdmin and press Save button
- Go to Members tab and select _SYSTEM (or the user that you want to login) and Assign to the PersonAdmin
- Now call http://localhost:52773/crud/persons/all again
- Now you be able to call with success! You get []
- If you want to test with data, populate the database using http://localhost:52773/crud/persons/populate
- Call http://localhost:52773/crud/persons/all again and you get JSON results!
- Test security restriction by header value
- Open the class src\dc\Sample\PersonREST and go to GetInfo ClassMethod (line 30). You will see this:
/// @security.and: header: { HTTP_ORGANIZATION = InterSystems }
ClassMethod GetInfo() As %Status
{
SET version = ..#Version
SET info = {
"version": (version),
"organization": (%request.GetCgiEnv("HTTP_ORGANIZATION"))
}
RETURN ..%ProcessResult($$$OK, info)
}
- Above the ClassMethod you see:
@security.and: header: { HTTP_ORGANIZATION = InterSystems }
- When you set @security.and, you enforce the API calls to this method to follows the security rule
- When you set header: { HTTP_NAMEHEADER }, you enforce the API calls to this method have the NAMEHEADER as a request header item
- So, in this example, the request needs the Organization header with InterSystems value
- First all, test without the header, call http://localhost:52773/crud/
- You will get the following message error:
{
"verb": "GET",
"url": "/",
"application": "/crud/",
"method": "GetInfo",
"header": "",
"error": "HTTP_ORGANIZATION = InterSystems is required in the request header"
}
-
Now, include into your Postman, or other REST Client the header key organization with value InterSystems and call http://localhost:52773/crud/ again. You have success!
-
Enjoy!
Use online this sample on-line
This app is on-line in the URL: http://ymservices.tech:52773/crud/
Future features
- Rule to enforce to request param and attributes values
- Rule to enforce to date/time values
- Rule to enforce to IP values
- Rule to enforce to regex expressions
- Rule to enforce to custom method evalution
Thanks to:
- Robert Cemper: beta tester
- Evgeny Shvarov: iris-rest-api-template was the base to this app