Krishna: Webservice

Webservice Connector

• Can integrate with any target system supporting Webservices.

• Able to perform read and write operation

• Supports JSON and XML for read and write.

REST APIs are some webservices which are exposed by any application to access its particular resources(information) using a browser from remote.

Identity IQ already exposed some of its REST APIs for example like can get user details etc. using those REST APIs.

What are different APIs exposed by Sailpoint. Example :

iiqIP -- IP address like localhost

iiqPort -- port number

Syntax to call rest api is :

url --> http://iiqIP:iiqPort/identityiq/rest/operation - name

Pre-Req :

• Fair understanding of – XML and JSON

– End points

– Request, response, header, body

– Authentication types

• Oauth2

– Grant types (client credentials, Refresh Token, JWT)

» Token url: URL for generating access token

» Client ID and client secret for Oauth2 authentication

» Refresh Token

» Private Key: to encrypt JWT assertion

» Private Key Password: to decrypt the Private key

• API Token

• Basic Authentication

• XML Xpath

• JSON Xpath

WebService Configuration :

• Base URL: The base URL to connect to the web service target system

• Authentication Method:

– OAuth2

• Grant Type (Refresh Token, JWT, Client Credentials)

• Client ID: optional for JWT

• Client Secret: optional for JWT

• Token URL

• Refresh Token: applicable for grant type refresh token

• Primary key: application for grant type JWT

• Private Key Passport: application for grant type JWT

– API Token

– Basic Authentication

• Username and Passport

– No Authentication

• SOAP Web Services supports only Basic Authentication method

• Schema Attribute for Account Enable status: Attribute name and value required to be provided to check the Enable status, For example, status=Active

• Request Timeout (In Seconds)

• Enable Client Certificate Authentication: Configure client certificate authentication

Configuration :

• Context URL: operation specific URL

• Method: HTTP methods - GET, POST, PUT, DELETE, PATCH

• Header: optional,

– Content-Type= application/XML or text/XML or */XML

– JSON request, JSON response: Content-Type= application/JSON (optional), Accept (optional)

– XML request, XML response: Content-Type= application/XML or text/XML or */XML (required), Accept (optional)

– JSON request, XML response: Content-Type=application/JSON (optional), Accept= application/XML or text/XML or */XML (required)

• Body

– form-data: (Applicable only for JSON) Key value. User must set the data that has to pass in the key value

– raw: Data to be sent in request body. For endpoint configuration, user must provide the XML payload by selecting the raw format.

• Response (XPATH for XML and JSON)

– (For JSON) $.members.profile

– (For XML) //wd:Response_Data/wd:Worker/wd:Worker_Data

• Successful response: accepts HTTP status code in csv format (For example, 200, 201, 203. If no value, checks the response codes 200-299 codes. You can use wild card 2**

• Before Rule:Rule that will be invoked before performing any operation (account aggregation, enable, disable account and so on).

• After Rule: Rule that will be invoked after performing any operation (account aggregation, enable, disable account and so on)

Configuration -- Pagination (Account Aggregation) :

Pagination (Account Aggregation) :

• Every paging configuration step must start on a new line

• SailPoint recommends to provide a after every operator, condition or placeholder for correct evaluation of paging expression

• Paging mechanism follows the placeholder notation for resolution of attribute values, that is., $response.attribute_key$. Any attribute which follows the placeholder notation would be resolved or assigned a value depending upon the operator being used.

• For complex expressions or conditions, multiple conditions can be clubbed together using '(' and ')'. For example, TERMINATE_IF ($someattribute$ == TRUE) && ($otherattribute$ == NULL)

Additional Configure Parameters :

• throwBeforeAfterRuleException: During aggregation if an exception is displayed from WebServiceBeforeOperationRule or WebServiceAfterOperationRule, then aggregation continues and completes successfully

• throwProvBeforeRuleException: During Provisioning, GetObject and Test Connection, if an exception is thrown from WebServiceBeforeOperationRule, then Provisioning would fail. Hence to dispose of the exception in the log file and proceed with provisioning, set the value of throwProvBeforeRuleException to false in the application debug page

• enableHasMore: If enableHasMore is set to true as follows then the termination of aggregation would depend on the value of hasMore attribute: – The hasMore attribute is the boolean attribute which is to be set in the transientValues map in the before/after operation rule. Unless the value of hasMore attribute is false aggregation would not be Terminated

• possibleHttpErrors, isGetObjectRequiredForPTA, objectNotFoundErrorMsg, authenticationFailedErrorMsg, expiredPasswordErrorMsg, oauth_headers, oauth_headers_to_exclude, oauth_request_parameters, oauth_body_attrs_to_exclude, oAuthJwtPayload

Strategy for Pagination :

1.Get the next page number to fetch

2.Create the termination logic when to stop fetching pages

3.Create the endpoint url of the next page to be fetched with the help of next Page number

Keywords :

• Response: denotes the response coming previous end point

• Application: Used to get other configuration attributes from the current application.

– "$application.accesstoken$",where the accesstoken is an application configuration attribute

• Plan: Used for configuring the provisioning operations

• getObject: Used while performing Aggregate Account (get a single account details).

• nativeIdentity: Signifies the AccountID (identity attribute) in the plan or during getobject operation.

– $getobject.nativeIdentity$

– $plan.nativeIdentity$

• Authenticate: To provide username and password in endpoint configuration user can use the following placeholders:

– $authenticate.username$

– $authenticate.password$

Some of the api used by the sailpoint :

First API used by the Sailpoint for pinging the Target System is ping :

http://iiqIP:iiqPort/identityiq/rest/ping -- > to know if the system is alive or not

POSTMAN TOOL ---> to test REST API

Below API to get the detail of particular user :

http://iiqIP:iiqPort/identityiq/rest/identities/ram -- > this will give the details of the user ram from identityiq

Below API to launch a particular workflow using a rest api:

http://iiqIP:iiqPort/identityiq/rest/workflows/Test/launch -- > this will launch the workflow test

Note:

Tool present in IIQ for any rest api testing or invocation called POSTMAN to detect or fire your REST APIs.
The most commonly used HTTP verbs POST, GET, PUT, DELETE

POST - to Create the resource
GET - to Read the resource
PUT - to Update the resource
DELETE - to Delete the resource

5. PATCH : Submits a partial modification to a resource. If you only need to update one field for the resource, use the PATCH method.

Example between put and patch :

PUT

If I had to change my first name then send PUT request for Update:

{ "first": "john", "last": "Marc" }

So, here in order to update the first name we need to send all the parameters of the data again.

PATCH

Patch request says that we would only send the data that we need to modify without modifying or effecting other parts of the data. Ex: if we need to update only the first name, we pass only the first name.

Pages

Webservice