If your REST service is accessing confidential data, you should use authentication for the service. If you need to provide different levels of access to different users, also specify privileges needed for the endpoints.
This chapter assumes that you have previously generated REST service classes as described in “Creating and Editing REST Services.”
Setting Up Authentication for REST Services
You can use any of the following forms of authentication with InterSystems IRIS REST services:
HTTP authentication headers — This is the recommended form of authentication for REST services.
Web session authentication — Where the username and password are specified in the URL following a question mark.
If you need to provide different levels of access to different users, do the following to specify the permissions:
Modify the specification class to specify the privileges that are needed to use the REST service or specific endpoints in the REST service; then recompile. A privilege is a permission (such as read or write), combined with the name of a resource.
You can specify a list of privileges for the entire REST service, and you can specify a list of privileges for each endpoint. To do so:
To specify the privileges needed to access the service, edit the OpenAPI XData block in the specification class. For the info object, add a new property named x-ISC_RequiredResource whose value is a comma-separated list of defined resources and their access modes (resource:mode) which are required for access to any endpoint of the REST service.
The following shows an example:
"description":"A sample API that uses a petstore as an example to demonstrate features in the swagger-2.0 specification",
"name":"Swagger API Team"
To specify the privileges needed to access a specific endpoint, add the x-ISC_RequiredResource property to the operation object that defines that endpoint, as in the following example:
"description":"Creates a new pet in the store. Duplicates are allowed",
Compile the specification class. This action regenerates the dispatch class.
Using the SECURITYRESOURCE Parameter
As an additional authorization tool, dispatch classes that subclass %CSP.RESTOpens in a new tab have a SECURITYRESOURCE parameter. The value of SECURITYRESOURCE is either a resource and its permission or simply the resource (in which case the relevant permission is Use). The system checks if a user has the required permission on the resource associated with SECURITYRESOURCE.
If the dispatch class specifies a value for SECURITYRESOURCE and the CSPSystem user is not sufficiently privileged, then this may result in unexpected HTTP error codes for failed login attempts. To prevent this from occurring, InterSystems recommends that you give permissions on the specified resource to the CSPSystem user.