Web Services Summary
This topic provides a summary of the RA Web services and covers the following:
cara
This topic provides a summary of the RA Web services and covers the following:
2
Managing Web Services Security
RA Web services are protected from rogue requests through authentication and authorization of all Web service requests. Authentication ensures that the incoming request to the Web service has valid credentials to access the Web service, while authorization ensures that the authenticated request has appropriate privileges to access the Web service. To enable the authentication and authorization feature, you must ensure that your calling application includes the required details in the incoming call header.
The Web services authentication and authorization works as follows:
- The calling application authenticates to the RA Web services by including the required credentials in the call header.
- The RA Web services authenticate these credentials and, if valid, provide your calling application with an authentication token.
- The calling application includes the authentication token and the authorization elements in the header of the subsequent calls.
The Authentication and Authorization header elements in the following tables are not applicable to the Case Management Web services.
Authentication Header Elements
The following table lists the elements that have to be included in the call header for authentication.
Element
| Mandatory
| Description
|
userID | Yes | The unique identifier of the user whose account has to be authenticated. |
orgName | Yes | The organization name to which the authenticating user belongs. |
credential | Yes | The credential of the user that is to be used for authentication. |
Authorization Header Elements
The following table lists the elements that you must pass in the call header for authorization.
Element
| Mandatory
| Description
|
authToken | Yes | The authentication token that is returned after successful user verification. This token indicates that the user is already authenticated, and thereby eliminates the need for user credentials for successive authentication attempts. By default, the authentication token is valid for one day, after which you need to authenticate again. |
Note: You can set any one of the following elements. | ||
targetorg | No | The organization to which your calling application must authorize before performing any operation. Note: If you want to enable authorization for more than one organization, then repeat this entry for every organization. |
targetAllOrgs | No | Indicates whether authorization is required before operations on all organizations can be performed. Set the value of this element to TRUE to enable authorization for all organizations. |
globalEntity | No | Indicates whether authorization is required for performing global configurations. Set this value to TRUE if you want to enable authorization for the global configuration operations, such as fetching Arcot attributes for users and fetching UDS attributes. |
Soap Header Namespace
The authentication and authorization header elements must use the namespace, as mentioned in the following table.
Web Service
| Namespace
|
User Data Service Web Services
| |
User Management User Registry Management Configuration Registry | http://ws.arcot.com/UDSTransaction/1.0
|
RA Web Services
| |
Risk Evaluation | http://ws.arcot.com/RiskFortEvaluateRiskAPI/2.0/wsdl
|
Administration | http://ws.arcot.com/ArcotRiskFortAdminSvc/1.0/wsdl
|
CM Web Services
| |
Case Management | http://ws.arcot.com/RiskAnalyticsCaseMgmtAPI/4.0/wsdl |
Authentication and Authorization
Risk Analytics Core Platform Stack provides a way to secure Web Services. Authentication and Authorization has been enabled by default for the CM Web services APIs. This requires credentials (either password or token) to be sent in the header as a part of the Request. The credentials are validated, privileges are authorized, and the Web services request is processed. This is specified, as follows.
<soap:Header> <INFO> <USERID>globaladmin</USERID> <ORGNAME>defaultorg</ORGNAME> <CREDENTIAL>Hello123!</CREDENTIAL> </INFO> </soap:Header>
(OR)
<soap:Header> <INFO> <USERID>globaladmin</USERID> <ORGNAME>defaultorg</ORGNAME> <TOKEN>b0c1a864-4912-4f52-847d-56f3b760e71e</TOKEN> </INFO> </soap:Header>
Disabling Authentication and Authorization for Case Management Web Services
Configuring Authentication and Authorization for the Web services API is optional. An administrator can use the Administration Console and disable Authentication and Authorization for the list of Web services APIs. If Authentication and Authorization is disabled for these APIs, the <soap:Header> must pass information for AdminName and AdminOrg of the administrator who is performing the operation . This can be specified, as follows.
<soap:Header> <wsdl:AdminInfo> <wsdl:userId>globaladmin</wsdl:userId> <!--Optional:--> <wsdl:orgName>defaultorg</wsdl:orgName> </wsdl:AdminInfo> </soap:Header>
No Credential is required in this case because Authentication and Authorization is disabled.
Managing Organizations
In RA, an organization can either map to a complete enterprise (or a company) or a specific division, department, or other entities within the enterprise. The organization structure provided by RA is flat. In other words, organizational hierarchy (in the form of parent and child organizations) is not supported, and all organizations are created at the same level as the Default Organization.
The
ArcotOrganizationManagementSvc.wsdl
file provides the following Web service operations to create and manage organizations:- Creating Organizations (createOrg)
- Updating Organizations (updateOrg)
- Updating Organization Status (updateOrgStatus)
- Refreshing the Organization Cache (refreshCache)
- Fetching Default Organization Details (retrieveDefaultOrg)
- Fetching Organization Details (retrieveOrg)
- Searching Organizations (listOrgs)
- Fetching Directory Service Attributes (listRepositoryAttributes)
- Fetching Arcot Database Attributes (listArcotAttributes)
- Deleting Organizations (deleteOrg)
Managing Users and Accounts
For RA to authenticate users, users have to be created in the database, which is a one-time process. The user can either be created in the Arcot database or RA can be configured to connect to LDAP for user information.
The
ArcotUserManagementSvc.wsdl
file contains the following Web service operations that are used to create and manage users, create and manager user accounts, and authenticate LDAP users:- Performing User Operations (createUser,updateUser,updateUserStatus,retrieveUser,listUsers,searchUsers,getUserStatus,updateUserStatus,deleterUser)
- Performing User Account Operations (addUserAccount,updateUserAccount,listUserAccounts,retrieveUserAccount,listUsersForAccount,deleteUserAccount)
- Setting the Personal Assurance Message (setPAM)
- Fetching the Personal Assurance Message (getPAM)
- Setting Custom User Attributes (setCustomAttributes)
- Authenticating LDAP Users (authenticateUser,getQnAAttributes)
Managing Additional User Configurations
The
ArcotConfigManagementSvc.wsdl
file provides the following Web service operations that are used to manage account types, fetch the email and telephone types configured for the users, and fetch the user attributes that are configured for encryption:- Managing Account Types (createAccountType,updateAccountType,listAccountTypes,deleteAccountType)
- Fetching Email and Telephone Types (listEmailTypes,listTelephoneTypes)
- Fetching User Attributes Configured for Encryption (listConfiguredAttributesForEncryption)
Performing Risk Evaluation
The Risk Evaluation Web service (
evaluateRisk
in ArcotRiskFortEvaluateRiskService.wsdl
) is the interface to Transaction Server. This Web service provides the logic for evaluating the risk associated with a transaction and returning an appropriate advice. When a user accesses your online application, the application forwards the request to RA for risk analysis. RA evaluates the risk for all users, irrespective of whether they are first-time users (and therefore not "known" to RA) or they are already enrolled with the RA system. Based on various factors collected from the user’s system and the result of configured rules that are triggered, this Web service returns a score and a corresponding advice, in addition to other related details.If RA recommends additional authentication (which must be performed by your application), the Post Evaluation Web service (
postEvaluate
in ArcotRiskFortEvaluateRiskService.wsdl
) returns a final advice based on the feedback of this secondary authentication received from your application.During risk evaluation, a DeviceID is passed to the Web service, which is then used by Transaction Server to form a user-device association in the database. Based on the end-user’s preferences, this DeviceID is then stored at the client-end either as a browser cookie or an HTML5 localStorage.
This
association
(or device binding) helps identify the risk for transactions originating from the user’s system for a transaction. Users who are not bound are more likely to be challenged before they are authenticated. You can list and delete these associations by using the listAssociations
and deleteAssociation
Web services (in ArcotRiskFortEvaluateRiskService.wsdl
), respectively.Users can be bound to more than one device (for example, someone using a work and home computer) and a single device can be bound to more than one user (for example, a family sharing a computer).
The
ArcotRiskFortEvaluateRiskService.wsdl
file provides the Web service operations to perform risk evaluation, post-evaluation, and association management:- Evaluating Risk (evaluateRisk)
- Performing Post Evaluation (postEvaluate)
- Listing Associations (listAssociations)
- Deleting Associations (deleteAssociation)
Managing Cases
The Case Management Web service (ArcotRiskAnalyticsCaseMgmtService.wsdl) allows an external system to connect to the RA Case Management system to Manage Cases that are generated as a part of transactions flagged by the RA Transaction Server. This interface leverages an External Case Management system's capability to pull cases for the operators using an RA Case Management Multi-Case Queue framework. RA supports the external system-defined logic to decide on the cases to assign to CSRs.
The
ArcotRiskAnalyticsCaseMgmtService
.wsdl
file describes the following Web service operations to fetch cases and acquire and update cases and transactions:- Acquiring Case Details for a Specified User (acquireCase)
- Acquiring Next Case (acquireNextCase)
- Listing the Next Case (listNextCase)
- Fetching Open Transactions for a Case (getTxns)
- Fetching Transaction Details (getTxnDetails)
- Fetching Case Details (getCaseDetails)
- Updating Cases (updateCase)