In this example, you will see how to provide appointments from the
Personal calendar
in Intrexx for external accesses via an OData service. The appointment data
in the calendar can then be accessed from another portal by using the
Connector for OData or another OData client of your choice.
A new OData service can be configured in the
Integration module
via the OData menu / New service.
In this dialog,
the data fields, which the OData service should access, are selected:
ID
UserID
Date from
Date to
Headline
Body
In the next dialog,
none of the settings are changed. After clicking on "Finish", the new service will
be shown.
2. OData server configuration
Before the service can be used, the OData Provider must be activated
via the OData menu / Settings.
OData services are connected to and provided by Intrexx to a
defined TCP/IP address and port. Before you can connect to an OData
service, the OData server must be accordingly configured and
activated.
In this dialog,
the following settings are defined:
Link address: The server should be accessible at this address
Port: A free port which is being used by another service and not
blocked by a firewall
Provider is active
The OData server is started automatically started and activated after clicking
on "Finish". To test the service, enter the address
"http://servername:port/Appointments.svc"
in your browser. Replace
"servername" and "port"
with the hostname of the computer where the Intrexx portal server is running.
The OData XML document, which is now shown, displays the
"Appointment" data group.
Alternatively, you can view the OData XML document, which lists the service
meta data via the
OData menu / Show meta data.
In the next step, the OData service can be
consumed.
3. Relationships
Relationships and references between Intrexx data groups are represented in
OData as Associations and Navigation Properties. Both 1:1 and 1:n relations
can be defined. Relationships with m:n cardinality can be represented with
an m:n data group. Associations in OData define the relationships and their
cardinality between Entity Types. Navigation Properties, on the other hand,
add properties to the Entity Types, which can be used to navigate from a data
record to a referenced data record without explicitly needing to add the
foreign key or reference data fields to the Entity Type. The required settings
for this are selected in the
Relationships
dialog. After the data groups that will be available to the service have been
selected, the relationships between them can be defined.
4. Files
In order to enable access from an OData service to files from file fields in
data groups, the service must have the corresponding file field added to it
as described previously. Since Intrexx provides additional metadata fields
for file fields, a field with the complex data type "IxFile" is automatically
added to the Entity Type for each file field. In addition to the file, this
also contains metadata, such as the file name, type, and size. Furthermore,
three functions are available to access files and manage them. There are two
possibilities to access files, which are described in the following.
Embedding files in OData feeds
The first possibility is to directly embed a file's contents as a base-64
encoded binary sting in an OData feed or entry. This is the simplest method
to access a file, by providing it directly with the result of an OData
request. The Connector for OData is able to extract the file's contents and
save it locally as a file, and/or transfer it to another file field in a
target file group and show the file in the browser using the Intrexx file
control. It is also possible to save or update individual files using the file
control. The disadvantage of this approach is that only one file can be
provided for each file field. In the case of multiple file fields, this is
always the first file, though a new file will always be added when saving.
Also, the performance of the service will be significantly negatively
impacted, since the file must first be completely loaded into the RAM in order
to encode or decode it. For this reason, this method should only be used for
smaller files.
OData functions for files
A significantly more flexible and resource-saving possibility to access files
using OData is by using the "upFile" functions, which are automatically
available in every Intrexx OData service. They can be used to save and request
files, and they provide full support for multiple file fields in Intrexx. The
single disadvantage of the functions is that the file controls in Intrexx do
not support this approach, which means that uploading and downloading files in
Intrexx web applications will need to be realized on a project-specific basis
with JavaScript or Groovy. The Intrexx OData service offers the following
functions to manage files:
upFileList
This function returns a list of all files in a file field.
The following parameters are expected:
recId: The primary key of the data record with the file field.
fieldGuid: The field GUID of the file field.
upFileAction
This function allows operations to be performed on multiple file fields.
The following parameters are expected:
recId: The primary key of the data record with the file field.
fileId: The ID of the file.
fieldGuid: The field GUID of the file field.
Operation: The file operation to be performed (either delete, moveUp, moveDown, moveTop, refreshMetadata, or refreshOrder).
upFileDownload
Returns the contents of a file as a base-64 encoded string.
The following parameters are expected:
recId: The primary key of the data record with the file field.
fileId: The ID of the file.
fieldGuid: The field GUID of the file field.
upFileResource upload
Enables the stream-based upload of a file. This is the fastest and most
resource-saving method to transfer files to the service. The
"uploadFile" method expects the following parameters:
recId: The primary key of the data record with the file field.
fieldGuid: The field GUID of the file field.
fileName: The file name.
contentType: The content type of the file.
upFileResource - download
Enables the stream-based download of a file. This is the fastest and most
resource-saving method to access files. The "downloadFile" method expects
the following parameters:
recId: The primary key of the data record with the file field.
fileId: The ID of the file.
fieldGuid: The field GUID of the file field.
disposition (optional): The content disposition header type (either inline or attachment).
5. SSL configuration
If "Use SSL" has been activated in the
OData provider 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.
A certificate from a Certificate Authority should be
used for a live system 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 a command window 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. When asked for the first and last name,
enter the same host name of the OData server as was defined in the service
endpoint URL.
6. 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 data group permissions
for a user are checked by the Intrexx portal server for OData requests.
If a user does not possess sufficient permission 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
Usually, a combination of Intrexx and Plain text authentication is used for OData
services. The client tries to log in using Intrexx authentication first and
if this is unsuccessful, a Plain text authentication is performed.
If this is unsuccessful as well, the request of the client will be denied.
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
installation directory \lib.
To do this, copy the file waffle-jna-1.6-with-dependencies.jar from the
installation directory \adapter\odata\kerberos,
Restart the portal server service afterwards.
Furthermore, the login method for the OData server must be changed to Windows
Integrated Authentication. To do this, open the file om.cfg in the
portal directory \internal\cfg
in a text editor. Within it, find the line that starts with
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.
Configuration of the authentication method
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 file om.cfg in the
portal directory \internal\cfg
in a text editor.
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 are available:
ODataAuth
IntrexxAuth
PlainTextAuth
IntegratedAuth
IntegratedAuthClient
TrustedAuth
To override the global method for a single service, copy the entry and
change the scope attribute as follows:
After the colon, specify the name of the OData services from the service
configuration. After saving the configuration file and
restarting the portal service,
the service-specific configuration will be used.