Omnis Technical Notes - Web Service Authentication

Omnis Technical Note TNWS0004 December 2014

Web Service Authentication

For Omnis Studio 6.1 or above
by Omnis Engineering

This tech note describes how you can configure your web server to support authentication for your REST based Web Services introduced in Omnis Studio 6.1.

You must be responsible for setting up authentication in your Omnis library. When using a real Web Server (rather than the built-in Tomcat server), you can configure the URL for the web service to support basic or digest authentication. There is also the option of using https, and also client certificates to further secure connections.

In the following sections, we have included some notes about how to configure Tomcat, Apache Web Server and IIS to support Basic and/or Digest authentication. If you do this, then the Web Server authenticates the client, and will only pass the request to Omnis if the client has been successfully authenticated; in this case, the HTTP headers include the Authorization header, which includes details of the authentication.

Omnis Studio 6.1 has a new function, parsehttpauth(auth) which parses the HTTP Authorization header value auth and returns a row variable containing the extracted information. Column 1 of the returned row (named scheme) is the scheme (e.g. basic). Other columns are scheme dependent. Examples for various auth header values:

Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

Returned row has three columns:
- scheme: basic
- username: Aladdin
- password: open sesame

Digest username="Mufasa",realm="testrealm@host.com",nonce="dcd98b7102dd2f0e8b11d0f600bfb0c093",
uri="/dir/index.html",qop=auth,nc=00000001,cnonce="0a4f113b",
response="6629fae49393a05397450978507c4ef1",opaque="5ccc069c403ebaf9f0171e9517f40e41"

Returned row has 10 columns:
- scheme: digest
- username: Mufasa
- realm: testrealm@host.com
- nonce: dcd98b7102dd2f0e8b11d0f600bfb0c093
- uri: /dir/index.html
- qop: auth
- nc: 00000001
- cnonce: 0a4f113b
- response: 6629fae49393a05397450978507c4ef1
- opaque: 5ccc069c403ebaf9f0171e9517f40e41

OAuth realm="Example",oauth_consumer_key="0685bd9184jfhq22",oauth_token="ad180jjd733klru7",
oauth_signature_method="HMAC-SHA1",oauth_signature="wOJIO9A2W5mFwDgiDvZbTSMK%2FPY%3D",
oauth_timestamp="137131200",oauth_nonce="4572616e48616d6d65724c61686176",oauth_version="1.0"

Returned row has 9 columns:
- scheme: oauth
- realm: Example
- oauth_consumer_key: 0685bd9184jfhq22
- oauth_token: ad180jjd733klru7
- oauth_signature_method: HMAC-SHA1
- oauth_signature: wOJIO9A2W5mFwDgiDvZbTSMK%2FPY%3D
- oauth_timestamp: 137131200
- oauth_nonce: 4572616e48616d6d65724c61686176
- oauth_version: 1.0

Bearer 0b79bab50daca910b000d4f1a2b675d604257e42

Returned row has 2 columns:
- scheme: bearer
- token: 0b79bab50daca910b000d4f1a2b675d604257e42

Any other scheme:

Returned row has 2 columns:
- scheme: scheme name in lower case
- data: the rest of the header data

Tomcat

This was tested with Tomcat 7.0.42 running on Windows 8.1. Restart Tomcat after changing the configuration files.

Basic Authentication

Configure users: edit conf/tomcat-users.xml:

Add role(s) and user(s) inside the <tomcat-users> element e.g.
<role rolename="omnisrest"/>
<user username="bobm" password="bobm" roles="omnisrest"/>

Edit web.xml in the omnisrestservlet webapp (in the WEB-INF folder);

Add the following after the servlet-mapping element:
<security-constraint>
<web-resource-collection>
<web-resource-name>All resources</web-resource-name>
<url-pattern>/*</url-pattern>
</web-resource-collection>
<auth-constraint>
<role-name>omnisrest</role-name>
</auth-constraint>
<user-data-constraint>

<transport-guarantee>NONE</transport-guarantee>
</user-data-constraint>
</security-constraint>
<login-config>
<auth-method>BASIC</auth-method>
<realm-name>omnisrest</realm-name>
</login-config>

Digest Authentication

Identical to the above, except auth-method is DIGEST.

SSL For Local Testing

In conf/server.xml:

Uncomment the SSL connector, and modify it, to result in something like:

<Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true"
maxThreads="150" scheme="https" secure="true"
clientAuth="false" sslProtocol="TLS" keystoreFile="C:\apache-tomcat-7.0.42\mykeystore" keystorePass="xxxxxx"/>

Create self-signed server certificate in the tomcat keystore:

Note: Response to first and last name question needs to be localhost (to enable local testing with OWEB as a client)
"C:\Program Files (x86)\Java\jdk1.6.0_37\bin\keytool" -genkeypair -alias mycert -keyalg RSA -validity 10000 -keystore c:\apache-tomcat-7.0.42\mykeystore

To use with the Omnis OWEB client for testing:

Extract certificate:

"C:\Program Files (x86)\Java\jdk1.6.0_37\bin\keytool" -exportcert -alias mycert -keystore c:\apache-tomcat-7.0.42\mykeystore -file my_root_cert

Import certificate into omnisTrustStore:

cd <omnis path>\secure\cacerts
"C:\Program Files (x86)\Java\jdk1.6.0_37\bin\keytool" -importcert -alias my_tomcat -keystore omnisTrustStore -file c:\apache-tomcat-7.0.42\my_root_cert

You can now use URLs like https://localhost:8443/omnisrestservlet/ws/5988/api/phase2/myapi/first with Tomcat

Note: to delete an old copy of a certificate:

"C:\Program Files (x86)\Java\jdk1.6.0_37\bin\keytool" -delete -alias my_tomcat -keystore omnisTrustStore

Apache Web Server

Basic Authentication

Create a user name and password:

c:\apache24\bin\htpasswd -c c:\apache24\test_passwords test
Note: -c is optional - required the first time to create the passwords file

Edit httpd.conf, so the omnisrest entry looks like

<Location /omnisrest>
</Location>

Require can have the form Require user..., Require valid-user, Require group... See the online Apache docs.

Digest Authentication

Create a user name and password:

c:\apache24\bin\htdigest -c c:\apache24\test_digest_passwords omnisrest test
Note: -c is optional - required the first time to create the passwords file

Edit httpd.conf, so the omnisrest entry looks like

<Location /omnisrest>

SetHandler omnisrest
AuthType Digest
AuthName "omnisrest"
AuthDigestDomain /omnisrest/
AuthDigestProvider file
AuthUserFile c:\apache24\test_digest_passwords
Require valid-user

</Location>

Uncomment LoadModule auth_digest_module modules/mod_auth_digest.so in httpd.conf

Require can have the form Require user..., Require valid-user, Require group... See the online Apache docs.

IIS

Basic Authentication

IIS is quite difficult to configure (or at least IIS Express is which we tested). You need to enable basic authentication, and disable anonymous authentication in the file AppServer\applicationhost.config in the IIS Express install directory. Search for authentication and change relevant strings.

Add the following at the end of applicationhost.config, just after the main location element:

<location path="Default Web Site/cgi-bin/omnisrestisapi.dll">

<system.webServer>
<security>
<authentication>
<basicAuthentication enabled="true" />
</authentication>
</security>
</system.webServer>

</location>

You can then use the username and password from a user account to use the protected URLs – we had to create a new standard user account to get this to work.