Provide data - OData settings

Integration module Provide data OData / Context menu - Settings

Connection address

The connection address defines who is allowed to access the OData service. If localhost is selected, the service can only be reached from the local computer. You may also select all (IPv4), all (IPv6), or manually enter a specific IP address. Select localhost if you only want to test your OData service locally.

Port

The port defines the TCP port at which the OData service can be reached. Ideally, you should use a port number between 49152 and 65535, one of the so-called private ports. These can be used variably, since they are not registered and do not belong to a specific application. Host and port together constitute the endpoint URL, at which your service will be reachable. The service can also simply integrated into your domain for public use.

Please make sure that you do not use the same port as is used by the portal server, and that the port is not already in use by any other application.

Context

You may specify a context here, which will be used as part of the service endpoint URL. This may be useful to run services behind a reverse proxy. The context name must conform to URL standards. The endpoint URL will be constructed as follows when a context is specified:

http://hostname:port/context/service.svc.

Host

A host name can be specified optionally here, when the host name of the public service URL is different from the host name of the server. This may be useful to run services behind a reverse proxy.

Use SSL

This option allows SSL encryption to be activated.

Keystore

A keystore is required for SSL connections, which stores the certificates. Specify the file name of the keystore here. The keystore file must be located in the portal directory \internal\cfg\odata\producer.

Keystore password

Specify the password for the keystore here.

Provider is active

Activates or deactivates the OData Provider. The Provider is deactivated in the default configuration. After activation, the services are started automatically.

SSL configuration

If Use SSL has been activated in the server settings, access to the OData services is only possible via the HTTPS protocol. To enable SSL, the server requires an X.509 certificate that is stored along with a certificate from the Certificate Authority in a keystore. In order to test SSL, it is possible to create what is known as a "self-signed" certificate. For productive use, a certificate should be used from a public certification authority, as otherwise warnings will appear in the browser and OData clients will decline the SSL connection. The following section describes how to generate a self-signed certificate for testing purposes and store it in a keystore. You can find additional information on this topic, including how to import trustworthy certificates, here.

Creating a keystore with SSL certificate

Open the command prompt in Windows or a shell in Linux, then switch to the bin directory of your Java JDK installation (such as \jre\windows\amd64\bin). Then run the following command: 
$ keytool -keystore /path/to/keystore.ks -alias odata -genkey -keyalg RSA
Enter keystore password:  password
What is your first and last name?   
[Unknown]: odata.intrexx.com 
What is the name of your organizational unit?   
[Unknown]: OData 
What is the name of your organization?   
[Unknown]: United Planet GmbH 
What is the name of your City or Locality?   
[Unknown]:  
What is the name of your State or Province?   
[Unknown]: 
What is the two-letter country code for this unit?   
[Unknown]: 
Is CN=odata.intrexx.com, OU=OData, O=United Planet GmbH, 
L=Unknown, ST=Unknown, C=Unknown correct?   
[no]:  yes

Enter key password for <odata>
The program now requests a password for the keystore and information about the server certificate. At the question regarding the first and last name, enter the same host name of the OData server as was defined in the service endpoint-URL.

Authentication methods

Authentication and permissions

To provide secure access to the data in a portal via OData services, user authentication takes place using the portal server login methods. The following section describes what kinds of authentication methods are supported and how they are configured. This can be done either by defining a global method for all services or by defining a specific method for each service. The Intrexx data group permissions for a user are checked by the Intrexx Portal Server for OData requests, just like in the portal. If a user does not possess sufficient rights to read or change data records, the OData service will either reply with an empty results set or with a permissions error.

Intrexx authentication

With Intrexx authentication, login is accomplished by using a user name and password, where the password is transferred in encrypted format using a challenge key provided by the server. This is the recommended method to use an Intrexx portal to access an OData service on another Intrexx portal.

Plain Text authentication

Plain text authentication corresponds to the HTTP basic authentication method. This can be used to log in to the service directly from the browser. However, the password will be transferred in unencrypted format, meaning that this method should only be implemented when SSL encryption is active at the same time.

Combined Intrexx and Plain Text authentication

Normally, OData services use a combination of Intrexx and plain text authentication. First, an attempt is made to log on the client using Intrexx authentication. If this fails, a plain text authentication is performed. If this also leads to an error, the client request is refused.

Windows Integrated Authentication

With Windows Integrated Authentication, the users are detected via the Active Directory / LDAP and logged on using the Kerberos protocol. This allows single sign-on to be realized in Windows environments. This method is only available with Microsoft Windows Servers and a domain environment. As soon as Windows Integrated Authentication is activated for a portal, OData users must log on with their Windows user name (domain\user) and password to an OData service. To authenticate OData requests directly with the logged on Windows user and thereby avoid an additional login, further steps are required.

First, a third-party library is required that is added to the lib directory of the Intrexx Portal Server. To do this, copy the file waffle-jna-1.6-with-dependencies.jar from the \adapter\odata\kerberos directory, which is a child directory of the Intrexx installation directory, to the \lib child directory. Restart the portal service afterwards. Next, the login method for the OData server must be changed to Integrated Authentication. To do this, open the file \internal\cfg\om.cfg, located in the portal directory, in a text editor. Within it, look for the line that starts with: 
<binding scope="odataservice" auth-type="IntegratedAuthClient"/>
Change the value in the auth-type attribute to IntegratedAuth: 
<binding scope="odataservice" auth-type="IntegratedAuth"/>
Repeat this step for all other OData service entries that need to be activated for Kerberos authentication. After saving the file, you must restart the portal server to make the changes active.

Trusted authentication

When using trusted authentication, a user can be logged on simply via the user's GUID. In doing so, it will be expected that the HTTP request sends the user GUID as the user name. This is the least secure method and should only be implemented in trusted environments.

Configuring the authentication methods

The global or service-specific authentication method is defined in the file om.cfg. By default, Intrexx defines the IntrexxAuth method for all OData services. To use another method or to overwrite the method for a specific service, open the \internal\cfg\om.cfg file in the portal directory with a text editor. 
<?xml version="1.0" encoding="UTF-8"?>
<configuration>
	<authentication anonymous="05CE8CE3035924F7D3088895F1D87DADD65CFAE4">
		<binding scope="web" auth-type="IntrexxAuth"/>
		<binding scope="client" auth-type="IntrexxAuth"/>
		…
		<binding scope="odataservice" auth-type="ODataAuth"/>
		…
	</authentication>
</configuration>
The entry scope=odataservice defines the global method for all OData services. The authentication method is saved in the auth-type attribute. The following methods can be chosen: To override the global method for a single service, copy the entry and change the scope attribute as follows: 
<binding scope="odataservice:MyService" auth-type="PlainTextAuth"/>
After the colon, specify the name of the OData services from the service configuration. After saving the configuration file and restarting the portal server, the service-specific configuration will be used.