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.
To authenticate a REST application via OAuth 2.0, do all of the following:
Configure the resource server containing the REST application as an OAuth 2.0 resource server.
Allow delegated authentication for %Service_WebGateway.
Make sure that the web application (for the REST application) is configured to use delegated authentication.
Create a routine named ZAUTHENTICATE in the %SYS namespace. InterSystems provides a sample routine, REST.ZAUTHENTICATE.mac, that you can copy and modify. This routine is part of the Samples-Security sample on GitHub (https://github.com/intersystems/Samples-SecurityOpens in a new tab). You can download the entire sample as described in Downloading Samples for Use with InterSystems IRIS, but it may be more convenient to simply open the routine on GitHub and copy its contents.
In your routine, modify the value of applicationName and make other changes as needed.
To specify privileges needed to execute code or access data, InterSystems technologies use Role-Based Access Control (RBAC). For details, see Authorization: Controlling User Access.
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.
Define the resources that you refer to in the specification class.
Define roles that provide sets of privileges. For example, a role could provide read access to an endpoint or write access to a different endpoint. A role can contain multiple sets of privileges.
Place users into all the roles needed for their tasks.
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:
"swagger":"2.0",
"info":{
"version":"1.0.0",
"title":"Swagger Petstore",
"description":"A sample API that uses a petstore as an example to demonstrate features in the swagger-2.0 specification",
"termsOfService":"http://swagger.io/terms/",
"x-ISC_RequiredResource":["resource1:read","resource2:read","resource3:read"],
"contact":{
"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:
"post":{
"description":"Creates a new pet in the store. Duplicates are allowed",
"operationId":"addPet",
"x-ISC_RequiredResource":["resource1:read","resource2:read","resource3:read"],
"produces":[
"application/json"
],
...
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.
Note:
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.
