Home Products API Security Mediator

API Security Mediator

1 reviews
Pull requests
InterSystems IRIS Declarative Security Rules for REST APIs

What's new in this version

YouTube video and header rule implementation


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

  1. Clone the project
$ git clone git@github.com:yurimarx/iris-api-security-mediator.git
  1. Build and up the project source code
$ docker-compose up -d --build
  1. 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


  1. Above the ClassMethod you see:
@security.and: roles: { PersonAdmin }
  1. When you set @security.and, you enforce the API calls to this method to authenticate to any user
  2. When you set roles: { YOURROLENAME }, you enforce the API calls to this method to the user have the role between {}
  3. So, in this example, the user needs the role PersonAdmin
  4. First all, test without the role, call http://localhost:52773/crud/persons/all (use _SYSTEM user or another user to authenticate)
  5. 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"
  1. Now Go to Management Portal -> System Administration -> Security -> Roles
  2. Press button Create New Role. In the Name set PersonAdmin and press Save button
  3. Go to Members tab and select _SYSTEM (or the user that you want to login) and Assign to the PersonAdmin
  4. Now call http://localhost:52773/crud/persons/all again
  5. Now you be able to call with success! You get []
  6. If you want to test with data, populate the database using http://localhost:52773/crud/persons/populate
  7. Call http://localhost:52773/crud/persons/all again and you get JSON results!
  8. Test security restriction by header value
  9. 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)
  1. Above the ClassMethod you see:
@security.and: header: { HTTP_ORGANIZATION = InterSystems }
  1. When you set @security.and, you enforce the API calls to this method to follows the security rule
  2. When you set header: { HTTP_NAMEHEADER }, you enforce the API calls to this method have the NAMEHEADER as a request header item
  3. So, in this example, the request needs the Organization header with InterSystems value
  4. First all, test without the header, call http://localhost:52773/crud/
  5. 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"
  1. 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!

  2. Enjoy!

Use online this sample on-line

This app is on-line in the URL: http://ymservices.tech:52773/crud/

Future features

  1. Rule to enforce to request param and attributes values
  2. Rule to enforce to date/time values
  3. Rule to enforce to IP values
  4. Rule to enforce to regex expressions
  5. Rule to enforce to custom method evalution

Thanks to:

  1. Robert Cemper: beta tester
  2. Evgeny Shvarov: iris-rest-api-template was the base to this app
Read more
Made with
zpm install iris-api-security-mediator download archive
1.2.030 Nov, 2021
Works with
InterSystems IRISInterSystems IRIS for Health
First published
22 Nov, 2021