Authorization REST API

Edit online

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 that the ACL which protects this API is appropriately restrictive on access.

Configuration

To enable the authorization REST API, a configuration entry for the API that is used to map the API to a specific URI, must be added to the [local-apps] stanza. See [local-apps] stanza. The supplied URI must define a single path segment. In other words, it must not include multiple '/' and will be relative to the root of the local junction.

[local-apps]
azn-decision = aznapi

In the configuration example above, the authorization REST 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 authorization REST API can 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 which is 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 you 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 which is 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 IBM Security Verify Access 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."
}