Using the Web Service/Client Configuration Wizard
InterSystems® Studio has been deprecatedOpens in a new tab. Beginning with version 2024.2, it is no longer included with installations of InterSystems IRIS®, and it is no longer receiving maintenance updates. An upgrade to InterSystems IRIS 2024.2 or later will remove any Studio installation which is associated with the instance.
The version of InterSystems Studio which was included with InterSystems IRIS 2024.1 is available as a stand-alone component from the WRC Downloads page (https://wrc.intersystems.com/wrc/coDistGen.cspOpens in a new tab). To show only the Studio downloads, type studio in the Name column. Neither upgrades nor new installations of InterSystems IRIS will affect a stand-alone Studio installation.
InterSystems provides the following documentation about Studio 2024.1 for legacy support only. InterSystems recommends that all users develop ObjectScript code using the InterSystems ObjectScript Extension Pack for Visual Studio Code. See Migrate from Studio.
Studio provides a wizard that you can use to create and attach policies (WS-Policy) that apply to InterSystems IRIS web services or web clients.
Using the Wizard
To use the Web Service/Client Configuration Wizard:
-
Click File > New....
-
On the General tab, click Web Service/Client Configuration.
-
Click OK.
Studio then displays a dialog box.
-
Select the web service or a web client to which the policies will apply. The wizard lists only the services and clients that are compiled.
To do so, click either the Service or the Client drop-down menu as appropriate and then click the web service class or web client class.
-
Click Next.
Studio then displays another dialog box.
-
Optionally edit the configuration class name, which is shown in the second field on this dialog box.
Note:If this class already exists, this wizard ignores its existing contents and overwrites it. The new class is not created until you reach the end of the wizard.
The default configuration class name is the web service or client class name, with Config appended to it.
-
For details on the rest of this page, see Security Policy Descriptions and Policy Option Reference.
-
Click Finish.
The wizard creates and saves the class.
-
Review the generated configuration class, which also includes a policy expression that adds timestamps to outbound messages:
<sp:IncludeTimestamp/> -
Optionally edit the configuration class and re-save it.
You would do this, for example, to add policy alternatives or to fine-tune the policy created by the wizard.
The class is not automatically compiled and the policy is not in effect until the class is compiled.
If you compile the configuration class and then want to disable it, comment out the XData block and recompile it.
Security Policy Descriptions
The primary purpose of the wizard is to provide configurable security policies. The choices for Security Policy are as follows:
-
No Security Policy
The following section lists all the policy options.
SSL/TLS Connection Security
This policy requires use of HTTP over SSL/TLS (HTTPS) between the web client and the web service. It provides confidentiality and integrity of the data stream, authentication of the server, and optional authentication of the client.
Username Authentication over SSL/TLS
This policy requires the client to send a <UsernameToken> (with username and password). This policy also requires HTTP over SSL/TLS (HTTPS), which provides confidentiality and integrity of the data stream, authentication of the server, and optional authentication of the client.
At runtime, the web client must create and add the username token with the default password type. See Securing Web ServicesOpens in a new tab.
X.509 Certificate Authentication over SSL/TLS
This policy requires the client to send messages with signed body and timestamp and the X.509 certificate that can verify the signature. WS-Addressing headers, if included, are also signed. This policy also requires HTTP over SSL/TLS (HTTPS), which provides confidentiality and integrity of the data stream, authentication of the server, and optional authentication of the client.
Authentication with Symmetric Keys
This policy requires a single, shared secret key that is used to both sign and encrypt the message. This symmetric key is generated at runtime and is encrypted using the public key of the service’s certificate.
The service can optionally require an encrypted username and password with the default password type for authentication; if you choose this option, the client must add the <UsernameToken> at runtime, as described in Securing Web ServicesOpens in a new tab. It is not necessary to manually encrypt the <UsernameToken>; InterSystems IRIS automatically encrypts it.
Symmetric Keys with Endorsing Certificate
This policy requires a single, shared secret key that is used to both sign and encrypt the message. This symmetric key is generated at runtime and is encrypted using the public key of the service’s certificate.
The service can optionally require an encrypted username and password with the default password type for authentication; if you choose this option, the client must add the <UsernameToken> at runtime, as described in Securing Web ServicesOpens in a new tab. It is not necessary to manually encrypt the <UsernameToken>; InterSystems IRIS automatically encrypts it.
This mechanism uses an endorsing client certificate to augment the token associated with the message signature.
Mutual X.509 Certificates Security
This policy requires all peers to sign the message body and timestamp, as well as WS-Addressing headers, if included. It also optionally encrypts the message body with the public key of the peer's certificate.
The service can optionally require an encrypted username and password with the default password type for authentication; if you choose this option, the client must add the <UsernameToken> at runtime, as described in Securing Web ServicesOpens in a new tab. It is not necessary to manually encrypt the <UsernameToken>; InterSystems IRIS automatically encrypts it.
SAML Authorization over SSL/TLS
This policy requires the client to send a SAML token that contains an X.509 certificate or a public key. The corresponding private key signs the message body and timestamp, as well as WS-Addressing headers, if included. This policy also requires HTTP over SSL/TLS (HTTPS), which provides confidentiality and integrity of the data stream, authentication of the server, and optional authentication of the client.
SAML with X.509 Certificates
This policy requires the client to send a SAML token. This policy also signs the message body and timestamp, as well as WS-Addressing headers, if included. It also optionally encrypts the message body with the public key of the peer's certificate.
Policy Option Reference
The predefined policies have many of the same options. The following list provides details on all the options, following the order they are shown in the wizard.
Where applicable: All security policies.
If you select this option, the web service and web client establish and use a shared, secret security context. Then both parties can generate the same symmetric key and use it for signing, encryption, signature validation, and decryption.
Where applicable: All security policies.
This option is applicable only if the previous option is also selected. If you select Require Derived Keys, then a derived key is used in the messages, rather than the original session key.
Where applicable: All security policies.
This option specifies that the WS-ReliableMessaging protocol must be used when sending messages. This protocol allows SOAP messages to be reliably delivered even in the presence of software component, system, or network failures.
You can specify parameters in an InterSystems IRIS web service to fine-tune its behavior with WS-ReliableMessaging. See Securing Web ServicesOpens in a new tab.
Where applicable: All policies that use SSL/TLS. Applies only to the client.
SSL/TLS configuration for the client to use.
In all applicable policies, you can either choose an SSL/TLS configuration within the wizard (hardcoding that selection), or you can programmatically select and add one in the web service or client; see Securing Web ServicesOpens in a new tab.
Where applicable: All policies that use SSL/TLS.
Optionally select this option if the SSL/TLS connection requires the client to authenticate itself. See the comments for SSL Configuration.
Where applicable: All policies that do not use SSL/TLS.
Optionally select this to encrypt the SOAP body with the public key of the peer’s certificate.
Where applicable: All policies that do not use SSL/TLS.
Optionally select this to require that the messages are encrypted before being signed. If this option is not selected, the messages are signed and then encrypted.
Where applicable: All policies that do not use SSL/TLS.
Optionally select this to require that the message signature is applied to the binary security token that carries the certificate whose associated private key signs the message.
Where applicable: X.509 Certificate Authentication over SSL/TLS. Applies only to the client.
InterSystems IRIS credential set for the client to use when signing messages. The signature uses the private key in the associated certificate. See the subsection Credential Sets.
Where applicable: Several policies.
Optionally select this to require the client to send an encrypted element that contains a <UsernameToken>.
If you choose this option, you must add the <UsernameToken> at runtime as described in Securing Web ServicesOpens in a new tab. It is not necessary to manually encrypt the <UsernameToken>; InterSystems IRIS automatically encrypts it.
Where applicable: Policies that use symmetric keys. Applies only to the client.
InterSystems IRIS credential set for the client to use to generate the symmetric key; this should be the certificate of the service. The symmetric key is generated with the public key of the certificate. See Securing Web ServicesOpens in a new tab.
Where applicable: Symmetric Keys with Endorsing Certificate. Applies only to the client.
InterSystems IRIS credential set for the client to use to endorse the protection token. This should be the certificate of the client. See the subsection Credential Sets.
Where applicable: Mutual X.509 Certificates Security and SAML with X.509 Certificates. Applies only to the client.
InterSystems IRIS credential set for the web client to use. The client uses the associated private key for message signing and sends the initiator token to the service to enable the service to verify signatures and encrypt the response. See the subsection Credential Sets.
Where applicable: Mutual X.509 Certificates Security and SAML with X.509 Certificates.
InterSystems IRIS credential set for the web service to use. The client uses the public key in the certificate in the recipient token to encrypt the outbound message body. The service uses the associated private key for message signing. See the subsection Credential Sets.
Where applicable: All security policies.
Algorithm suite for the web server and client to use. For details, see section 6.1 in the WS-SecurityPolicy specificationOpens in a new tab.
Where applicable: All security policies.
Optionally select this option to enforce a strict layout of security header elements.
Where applicable: All policies.
If you select this option, the web service or web client includes WS-Addressing header elements in outbound messages and expects them in inbound messages.
If you use Enable WS-Addressing, InterSystems IRIS uses a default set of WS-Addressing header elements.
Even when you select Enable WS-Addressing, you can manually create WS-Addressing header elements and attach them as described in Securing Web ServicesOpens in a new tab; if you do so, the web service or client uses those header elements instead of the default ones.
Where applicable: All policies.
If you select this option, the web service or web client uses MTOM packaging in outbound messages and expects MTOM packaging in inbound messages.
Credential Sets
In many of the policies, you can select an InterSystems IRIS credential set as follows:
-
Select a credential set from the X.509 Credentials drop-down list.
-
Select a credential set by specifying the value of a field in the certificate. To do so, select a field from the Field drop-down list and then enter a value in the type-in box.
The available fields are as follows:
-
Alias
-
SubjectKeyIdentifier
-
Thumbprint
-
SerialNumber
-
IssuerDN
-
IssuerName — Acts as search string for the IssuerDN field. The system selects the first credential set whose IssuerDN field contains the given string. (In contrast, if you use IssuerDN, the match must be exact.)
-
SubjectDN
-
SubjectName — Acts as search string for the SubjectDN field. The system selects the first credential set whose SubjectDN field contains the given string. (In contrast, if you use SubjectDN, the match must be exact.)
-
Or you can programmatically select a credential set. In this case, you also need to package the certificate in a binary security token and add it to the outbound messages.
