RESTful web service PIP

When you add or modify a RESTful web service policy information point (PIP), you must specify its properties.

Connection properties

Name

A unique name for the policy information point. Use this name as the Issuer for the attributes that are returned by this policy information point.

Description

A description of the policy information point. (Optional)

Type

The type is RESTful Web Service. This field is read only.

URL

The URL for the RESTful web service that starts with http (plain-text) or https (secure HTTP). For example:

 https://example.ibm.com/jaxrs/getApprovedAmount/

You can also dynamically create the URL by using the attribute values in a request at run time. The attribute that you use must match the name field of that attribute.

Attention: Do not use confuse the attribute name in the name field with the attribute identifier in the identifier field. Use the name that matches the name in the name field.

In the following example, the user name for the request is substituted in the URL at run time. The name of the attribute is username:

 https://example.ibm.com/jaxrs/getApprovedAmount/{username}

In the following example, the user name and IP address for the request are substituted in the URL at run time. The attribute names are username and ipAddress.

 https://example.ibm.com/jaxrs/getApprovedAmount/{username}/{ipAddress}

Attention: The server name in the URL value must match the cn= value in the SSL server certificate for the policy information point server. For the example, if the URL is https://example.ibm.com/jaxrs/getApprovedAmount/, then the SSL server certificate value must be cn=example.ibm.com.

Also, the cn= value in the server certificate must be the host name for the server, not the IP address.

Response Format

The format of the response as requested by the service through the URL. Select XML, JSON, or Text.

Media Type

The Accept header in the request. The default values correspond with the response formats:

application/json
application/xml
text/plain

However, you can use any MIME type that you want to use.

Certificate Database

If https is used on the RESTful web service URL, specify the key database for the server SSL certificate. For example, rt_profile_keys

Client Authentication

If you require client authentication, select the type of authentication and its appropriate properties:

Basic Authentication: An authentication method that uses a user name and a password.
Client Certificate: An authentication method that requires the client to present an SSL certificate. Specify the database that stores the certificate and the certificate label.
Attention: This property is valid only if the RESTful web service uses HTTPS.

Attributes properties

Attribute

The attributes that are retrieved from a response and that can be used in a policy or risk score. The values are mapped to the associated attributes. You can use one or more attributes, and you can add, modify, or delete attributes.

Attention:

You must add the attributes to the appliance before you can use the attributes in this property.See the steps for adding an attribute in Managing attributes.
Do not delete an attribute that is used in a policy or risk score.

Selector

XML

XPath 1.0 expressions are supported for XML selectors. Any valid XPath expression is supported.

Plain Text

The plain text selector is a delimiter. The response from the web service can be a single value or list of values for an attribute. The selector specifies the character that separates the values. For example:

The selector is a comma (,)
The response from the web service is "LabA,LabB,LabC"
The returned attribute has three values: LabA, LabB, and LabC

Note: If you specify None for the delimiter, the RESTful web service policy information point returns the entire response as the attribute's value. If you do not specify a delimiter, the appliance defaults to None.

JSON

The JSON selector string. All attribute selectors must return either a primitive type or an array of primitive types. If the selector references complex types, a policy evaluation error occurs, and access to the system is denied.

JSON Selector format	Description
`$.x`	Returns the value for the property that is named x in the JSON object. Example: `{"name": "Bill", "loan": {"amount":100, "rate":0.15, "duration":60}, "accounts":[10000, 2000, 500]}` `$.name` returns `'Bill'`.
`$.x....z`	Returns the value for the property within a nested JSON object. Example: `{"name": "Bill", "loan": {"amount":100, "rate":0.15, "duration":60}, "accounts":[10000, 2000, 500]}` `$.loan.amount` returns `100`.
`$.x[*]`	Returns the array found at the specified property. Example: `{"name": "Bill", "loan": {"amount":100, "rate":0.15, "duration":60}, "accounts":[10000, 2000, 500]}` `$.accounts[*]` returns `[10000, 2000, 500]`. The attribute is multivalued with each object in the array as a value.
`$.[*]`	Returns an array that is contained in the JSON response. The attribute is multivalued with each object in the array as a value. Example: If the data is `["joe", "bob", "ted"]` , `$.[*]` returns `["joe", "bob", "ted"]`
`$.[x]`	Returns a value from a JSON array index, where `$.[x]` represents the index on the array of the value you want to return. Example: If the data is `["joe", "bob", "ted"]` , `$.[1]` returns `["bob"]`
`$.[*].x`	Returns values from a property within an array of JSON objects. Example: If the data is `[ {"name":"joe", "phone":"555-1212"}, {"name":"bill", "phone":"555-1213"}, {"name":"ted", "phone":"555-1214"} ]` `$.[*].name` returns `["joe", "bill", "ted"]`