June 12, 2016

WSO2 Admin Services

WSO2 Admin Services

All WSO2 Products internally perform all of it's operations via admin services. From the management console, these admin services are called to facilitate the features.

You can find more information on this at : https://docs.wso2.com/display/Carbon420/Calling+Admin+Services+from+Apps

By default, admin services WSDLs are not exposed in a product. Therefore need to do the following to access the WSDLs.

  • Set the <HideAdminServiceWSDLs> element to false in <PRODUCT_HOME>/repository/conf/carbon.xml file and restart the server.
  • Additionally to access the OSGI console, start the server as <PRODUCT_HOME>/bin/wso2server.sh -DosgiConsole. By hitting enter on the console it will start the OSGI shell
  • osgi> listAdminServices will list all the admin services available in the product.


Invoking Admin Services

There are a few ways to invoke admin services.
  1. Invoke with SOAP UI using the WSDLs of the admin services
  2. Invoke via CURL
  3. Invoke programmatically via the service stubs.

Using SOAP UI to Invoke Admin Services

We can create a new SOAP UI project by using the WSDL. We can get the sample requests and fill up the necessary data to invoke the service operations.

Even if we are using CURL to invoke the admin services, we need to get the request format which is easiest to be done by importing the WSDL as a SOAP project to SOAP UI first.

Using CURL to Invoke Admin Services

As mentioned above, best approach is to get the request format from SOAPUI. Once you have the request format, we can invoke admin services as below.

1. First we need to authenticate. Therefore, invoke the AuthenticationAdmin service.

Request (auth.xml):

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://org.apache.synapse/xsd">
 <soapenv:Header/>
 <soapenv:Body>
      <aut:login xmlns:aut="http://authentication.services.core.carbon.wso2.org">
         <aut:username>admin</aut:username>
         <aut:password>admin</aut:password>
         <aut:remoteAddress>localhost</aut:remoteAddress>
      </aut:login>
   </soapenv:Body>
</soapenv:Envelope>

CURL command :

curl -k -v -H "SOAPAction: urn:login" -H "Content-Type: text/xml" -d @auth.xml https://localhost:9443/services/AuthenticationAdmin

Response :
*   Trying ::1...
* connect to ::1 port 9443 failed: Connection refused
*   Trying 127.0.0.1...
* Connected to localhost (127.0.0.1) port 9443 (#0)
* TLS 1.2 connection using TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
* Server certificate: localhost
> POST /services/AuthenticationAdmin HTTP/1.1
> Host: localhost:9443
> User-Agent: curl/7.43.0
> Accept: */*
> SOAPAction: urn:login
> Content-Type: text/xml
> Content-Length: 467
* upload completely sent off: 467 out of 467 bytes
< HTTP/1.1 200 OK
< Set-Cookie: JSESSIONID=E74FD5AB56A283CD261E26A77B9854FB; Path=/; Secure; HttpOnly
< Content-Type: text/xml;charset=UTF-8
< Transfer-Encoding: chunked
< Date: Sun, 12 Jun 2016 03:20:09 GMT
< Server: WSO2 Carbon Server
* Connection #0 to host localhost left intact

<?xml version='1.0' encoding='UTF-8'?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
   <soapenv:Body>
      <ns:loginResponse xmlns:ns="http://authentication.services.core.carbon.wso2.org">
         <ns:return>true</ns:return>
      </ns:loginResponse>
   </soapenv:Body>
</soapenv:Envelope>

At this time you should also be able to see the following command in the ESB terminal (or the relevant product's terminal)

[2016-06-12 08:52:25,931]  INFO - CarbonAuthenticationUtil 'admin@carbon.super [-1234]' logged in at [2016-06-12 08:52:25,931+0530]

2. From the response, get the JSessionID. This will be used for later requests to authenticate.

JSESSIONID=E74FD5AB56A283CD261E26A77B9854FB

3. If you are trying this with ESB, we can try invoking TemplateAdminService as below.

Request (template.xml):
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://org.apache.synapse/xsd">
   <soapenv:Header/>
   <soapenv:Body>
      <xsd:getTemplates>
         <!--Optional:-->
         <xsd:pageNumber>0</xsd:pageNumber>
         <!--Optional:-->
         <xsd:templatePerPage>200</xsd:templatePerPage>
      </xsd:getTemplates>
   </soapenv:Body>
</soapenv:Envelope>


CURL Command

curl -k -v -H "Cookie: JSESSIONID=7D8798EB0A39E18194E778461F7E3E6D" -H "SOAPAction: urn:getTemplates" -H "Content-Type: text/xml" -d @template.xml https://localhost:9443/services/TemplateAdminService

Response :
*   Trying ::1...
* connect to ::1 port 9443 failed: Connection refused
*   Trying 127.0.0.1...
* Connected to localhost (127.0.0.1) port 9443 (#0)
* TLS 1.2 connection using TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
* Server certificate: localhost
> POST /services/TemplateAdminService HTTP/1.1
> Host: localhost:9443
> User-Agent: curl/7.43.0
> Accept: */*
> Cookie: JSESSIONID=7D8798EB0A39E18194E778461F7E3E6D
> SOAPAction: urn:getTemplates
> Content-Type: text/xml
> Content-Length: 389
* upload completely sent off: 389 out of 389 bytes
< HTTP/1.1 200 OK
< Content-Type: text/xml;charset=UTF-8
< Transfer-Encoding: chunked
< Date: Sun, 12 Jun 2016 03:33:22 GMT
< Server: WSO2 Carbon Server
* Connection #0 to host localhost left intact

<?xml version='1.0' encoding='UTF-8'?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
   <soapenv:Body>
      <ns:getTemplatesResponse xmlns:ax2246="http://common.templates.mediation.carbon.wso2.org/xsd" xmlns:ns="http://org.apache.synapse/xsd">
         <ns:return xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ax2246:TemplateInfo">
            <ax2246:artifactContainerName xsi:nil="true"/>
            <ax2246:description xsi:nil="true"/>
            <ax2246:enableStatistics>false</ax2246:enableStatistics>
            <ax2246:enableTracing>false</ax2246:enableTracing>
            <ax2246:isEdited>false</ax2246:isEdited>
            <ax2246:name>getUserID</ax2246:name>
         </ns:return>
      </ns:getTemplatesResponse>
   </soapenv:Body>
</soapenv:Envelope>

Note : 

For all the requests, make sure to use the SOAP 1.1 which is xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" and not xmlns:soap="http://www.w3.org/2003/05/soap-envelope", since this will result in an error invoking the admin services with CURL as  : 

<?xml version='1.0' encoding='UTF-8'?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
   <soapenv:Header xmlns:wsa="http://www.w3.org/2005/08/addressing">
      <wsa:Action>http://www.w3.org/2005/08/addressing/soap/fault</wsa:Action>
   </soapenv:Header>
   <soapenv:Body>
      <soapenv:Fault>
         <faultcode>soapenv:VersionMismatch</faultcode>
         <faultstring>Transport level information does not match with SOAP Message namespace URI</faultstring>
         <detail/>
      </soapenv:Fault>
   </soapenv:Body>
</soapenv:Envelope>

Using Service Stubs to Invoke Admin Services

Following is the code segment to invoke to get the templates from ESB server by using the TemplateAdminService stub. 

First step is to authenticate : 

TemplateAdminServiceStub templateAdminServiceStub = new TemplateAdminServiceStub("https://localhost:9443/services/TemplateAdminService");
ServiceClient client = templateAdminServiceStub._getServiceClient();
Options client_options = client.getOptions();
HttpTransportProperties.Authenticator authenticator = new HttpTransportProperties.Authenticator();
authenticator.setUsername("admin");
authenticator.setPassword("admin");
authenticator.setPreemptiveAuthentication(true);
client_options.setProperty(org.apache.axis2.transport.http.HTTPConstants.AUTHENTICATE, authenticator);
client.setOptions(client_options);

Next we can invoke the service operation : 

OMElement templateOMElement = templateAdminServiceStub.getTemplate();

Invoking Admin Services in Tenant Mode

To invoke admin services in tenant mode, we only need to change the admin service URL with tenant URL and the username and password to the tenant.

E.g. :
Admin Service URL :  https://localhost:9443/services/t/maheeka.com/TemplateAdminService
Username : admin@maheeka.com
Password : admin123

Troubleshooting

1. Error when invoking admin service

[2016-05-25 16:41:36,054] ERROR - Class System failure.null
java.lang.NullPointerException
at org.wso2.carbon.server.admin.module.handler.AuthorizationHandler.doAuthorization(AuthorizationHandler.java:104)
at org.wso2.carbon.server.admin.module.handler.AuthorizationHandler.invoke(AuthorizationHandler.java:87)
at org.apache.axis2.engine.Phase.invokeHandler(Phase.java:340)
at org.apache.axis2.engine.Phase.invoke(Phase.java:313)
at org.apache.axis2.engine.AxisEngine.invoke(AxisEngine.java:261)
at org.apache.axis2.engine.AxisEngine.receive(AxisEngine.java:167)
at org.apache.synapse.transport.passthru.ServerWorker.processEntityEnclosingRequest(ServerWorker.java:398)
at org.apache.synapse.transport.passthru.ServerWorker.run(ServerWorker.java:145)
at org.apache.axis2.transport.base.threads.NativeWorkerPool$1.run(NativeWorkerPool.java:172)
at java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1145)
at java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:615)
at java.lang.Thread.run(Thread.java:745)
[2016-05-25 16:41:36,055] ERROR - AxisEngine System failure.
org.apache.axis2.AxisFault: System failure.
at org.wso2.carbon.server.admin.module.handler.AuthorizationHandler.invoke(AuthorizationHandler.java:93)
at org.apache.axis2.engine.Phase.invokeHandler(Phase.java:340)
at org.apache.axis2.engine.Phase.invoke(Phase.java:313)
at org.apache.axis2.engine.AxisEngine.invoke(AxisEngine.java:261)
at org.apache.axis2.engine.AxisEngine.receive(AxisEngine.java:167)
at org.apache.synapse.transport.passthru.ServerWorker.processEntityEnclosingRequest(ServerWorker.java:398)
at org.apache.synapse.transport.passthru.ServerWorker.run(ServerWorker.java:145)
at org.apache.axis2.transport.base.threads.NativeWorkerPool$1.run(NativeWorkerPool.java:172)
at java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1145)
at java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:615)
at java.lang.Thread.run(Thread.java:745)
[2016-05-25 16:41:36,057] ERROR - ServerWorker Error processing POST request for : /services/CarbonAppUploader
org.apache.axis2.AxisFault: System failure.
at org.wso2.carbon.server.admin.module.handler.AuthorizationHandler.invoke(AuthorizationHandler.java:93)
at org.apache.axis2.engine.Phase.invokeHandler(Phase.java:340)
at org.apache.axis2.engine.Phase.invoke(Phase.java:313)
at org.apache.axis2.engine.AxisEngine.invoke(AxisEngine.java:261)
at org.apache.axis2.engine.AxisEngine.receive(AxisEngine.java:167)
at org.apache.synapse.transport.passthru.ServerWorker.processEntityEnclosingRequest(ServerWorker.java:398)
at org.apache.synapse.transport.passthru.ServerWorker.run(ServerWorker.java:145)
at org.apache.axis2.transport.base.threads.NativeWorkerPool$1.run(NativeWorkerPool.java:172)
at java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1145)
at java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:615)

at java.lang.Thread.run(Thread.java:745)

Solution : 
ESB or APIM has two types of transports - servlet and passthrough. The admin services are exposed through servlet transport. Therefore, we need to invoke admin services through transport port. E.g. : https://localhost:9443/services/AuthenticationAdmin. The common reason for this error is that the admin service WSDLs are exposed on passthrough port (8243).


No comments:

Post a Comment