Authorization REST API

The authorization REST API provides a mechanism by which an external client can evaluate an authorization decision. It can be used as a potential replacement for the legacy ISAM Java authorization API.

Security Considerations

This API can potentially expose sensitive information to callers of the API. For example, it can be used to determine if a user is known to the system or not. As a result of this, an administrator should take care to only enable this API on systems with controlled network access. The administrator should also ensure the ACL which protects this API is appropriately restrictive on access.

Configuration

To enable the authorization REST, a configuration entry maps the API to a specific URI in the [local-apps] stanza. The URI defines a single path segment. It must not include multiple '/' and will be relative to the root of the local junction.

[local-apps]
azn-decision = aznapi

In example above, the API is enabled and mapped to the aznapi path segment. If the local junction is configured with a path of '/', which is the standard local junction path in a WebSEAL environment, the API can then be accessed at the following URL:

http[s]://<webseal-host>:<webseal-port>/aznapi

For example:

https://www.ibm.com/aznapi

Caching

The generation of the user credential used in the authorization decision can be an expensive operation. To help improve the performance of the API these credentials can be temporarily stored in a cache for future decisions. The [azn-decision-app] configuration stanza (see [aznapi-decision-app] stanza) can be used to help configure this cache. In particular it allows us to set the maximum size of the cache (a least-recently-used algorithm is used to make room in the cache when it becomes full) and the maximum lifetime of a credential in the cache.

API Definition

A single API is provided by the authorization decision application:

Method: POST

Request Headers:

Content-Type: application/json

Required for requests to this service as the request data must be provided in JSON format.

Request Body:

user_name	The name of the user to be used in the authorization decision.
user_attributes	A JSON object containing name/value pairs which are added as attributes to the credential used in the authorization decision.
permission_bits	A string representation of the permission bits used in the authorization decision.
object_name	The name of the object used in the authorization decision.

Request Example:

{ 
  "user_name": "joe", 
  "user_attributes": {       
      "AUTHENTICATION_LEVEL": "2"     
  },
  "permission_bits": "Tr", 
  "object_name": "/WebSEAL/default-ibm.com/test"
}

Response Code:

200

The request was successful.

Response Body:

authorized	A Boolean value which indicates the authorization decision result.
attributes	A JSON object containing name/value pairs which correspond to the attributes associated with the authorization decision.

Response Example

 { 
  "authorized": false, 
  "attributes": {     
    "AZN_PERMINFO_FAIL_REASON": "268809242"     
  }  
}

400

An issue was found with the request which prevented the authorization decision from being made.

Response Body

error_code	A code which can be used to identify the error. This code will correspond to an ISAM error code.
error_description	A textual description of the error.

Response Example:

{ 
   "error_code": 949498922,
   "error_description": "DPWAD1066E   An error occurred while parsing the JSON data: Object item not found: user_name."
}

Parent topic: Embedded Applications