Troubleshooting Security Problems
This topic provides information to help you identify causes of SOAP security problems in InterSystems IRIS.
For information on problems unrelated to security, see Troubleshooting SOAP Problems in InterSystems IRIS.
Information Needed for Troubleshooting
To troubleshoot SOAP problems, you typically need the following information:
-
The WSDL and all external documents to which it refers.
-
(In the case of message-related problems) Some form of message logging or tracing. You have the following options:
Option Usable with SSL/TLS? Shows HTTP headers? Comments InterSystems IRIS SOAP log Yes No For security errors, this log shows more detail than is contained in the SOAP fault. Web Gateway trace Yes Yes For problems with SOAP messages that use MTOM (MIME attachment), it is crucial to see HTTP headers. Third-party tracing tools No Depends on the tool Some tracing tools also show lower-level details such as the actual packets being sent, which can be critical when you are troubleshooting. These options are discussed in Troubleshooting SOAP Problems in InterSystems IRIS.
-
In the rare case that your SOAP client is using HTTP authentication, note that you can enable logging for the authentication; see Providing Login Credentials.
It is also extremely useful to handle faults correctly so that you receive the best possible information. See SOAP Fault Handling.
Possible Errors
This section discusses possible security-related errors in InterSystems IRIS web services and web clients:
-
If you have just generated the InterSystems IRIS web service or client, it might not yet be configured to recognize WS-Security headers. In this case, you receive a generic error like the following when you try to execute a web method:
<ZSOAP>zInvokeClient+269^%SOAP.WebClient.1
Add the following to the web service or client and recompile it:
Parameter SECURITYIN="REQUIRE";
This generic error can also be caused by calling the web method incorrectly (for example, referring to a return value when the web method does not have one).
This item does not apply if you are using WS-Policy.
-
In other cases, you might receive the following security error when you try to execute a web method:
ERROR #6454: No supported policy alternative in configuration Policy.Client.Demo1SoapConfig:service
-
The inbound message might have failed validation. If so, the SOAP log indicates this. For example:
08/05/2011 14:40:11 ********************* Input to Web client with SOAP action = http://www.myapp.org/XMLEncr.DivideWS.Divide <?xml version='1.0' encoding='UTF-8' standalone='no' ?> <SOAP-ENV:Envelope xmlns:SOAP-ENV='http://schemas.xmlsoap.org/soap/envelope/' xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance' xmlns:s='http://www.w3.org/2001/XMLSchema' xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" > <SOAP-ENV:Body> <SOAP-ENV:Fault> <faultcode>wsse:FailedAuthentication</faultcode> <faultstring>The security token could not be authenticated or authorized</faultstring> <detail></detail> </SOAP-ENV:Fault> </SOAP-ENV:Body> </SOAP-ENV:Envelope>
Items to Check in the Event of Security Errors
If the inbound message failed validation or if InterSystems IRIS issues the no supported policy alternative error, it is useful to check the following items:
-
When you retrieve a stored InterSystems IRIS credential set, make sure that you type its name correctly.
-
After retrieving an InterSystems IRIS credential set, check the type of the object to ensure that it is %SYS.X509CredentialsOpens in a new tab.
-
Make sure that you are using the appropriate certificate.
If you are using it for encryption, you use the certificate of the entity to whom you are sending the message. Encryption uses the public key of this certificate.
If you are using it for signing, you use your own certificate, and you sign with the associated private key. In this case, make sure that you have loaded the private key and that you have correctly specified the password for the private key file.
-
Make sure that the certificates are signed by a certificate authority that is trusted by InterSystems IRIS.
-
If you are using WS-Policy, be sure to edit the generated configuration class to specify the InterSystems IRIS credential set to use. See Editing the Generated Policy.
-
If the web service requires a <UsernameToken>, make sure that InterSystems IRIS web client is sending this, and that it contains correct information. InterSystems IRIS cannot automatically specify the <UsernameToken> to send; this must be done at runtime. See Adding Timestamps and Username Tokens.
Make sure that at least one of the security policies required by web service or client is supported in InterSystems IRIS. See SOAP Security Standards.
-
In the case of an authentication failure, identify the user in the <UsernameToken>, and examine the roles to which that user belongs.