The way that you authenticate to run REST commands depends
on how the server is set up and the tool that you are using to run
the commands.
Note: Using REST commands requires the same
permissions as using the web interface. For information about permissions,
see
Roles and permissions.
Authenticating with a user name and password
The
simplest way to authenticate for REST commands is to use a user name
and password. For example, if you are using the
curl program,
you can specify the user name and password in the command, as in the
following code:
curl -k -u jsmith:passw0rd
https://ucrelease.example.org:8080/initiatives/
-X GET -H "Accept: application/json"
Authenticating with a session key
For maximum
performance, clients that perform multiple REST API requests should
establish an HTTP session and reuse it for the duration of each batch
of requests. An HTTP session is established after each successful
request using HTTP Basic authentication and is identified by the JSESSIONID and UCR_SESSION_KEY cookies.
In addition, clients that wish to use an HTTP session must place
the UCR_SESSION_KEY into an HTTP request header for
each request, as described below.
To get a session key, the
client program first runs a command with a user name and password.
The response headers include the session key. The header with the
key typically has the name
Set-Cookie and a value
that is similar to the following example:
UCR_SESSION_KEY=6286eb44-b867-5243-875b-e61c5d8b4301;
Expires=Wed, 09-Sep-2082 16:51:45 GMT; Path=/; Secure
The
client program must extract the session key from this header. In the
previous example, the session key is
6286eb44-b867-5243-875b-e61c5d8b4301.
Then, for additional PUT, POST, and DELETE commands, include the following
header:
UCR_SESSION_KEY:sessionKey
Use
the session key for
sessionKey.
In
addition, to reuse the HTTP session, include the
JSESSIONID cookie
in the standard Cookie HTTP request header.
Authenticating in scripts and programs
Many
programming and scripting languages can call REST commands.
The
following example is a Python script that authenticates by adding
the password to the request header.
#!/usr/bin/env python
import urllib2
import json
import base64
import sys
if not len(sys.argv) == 3:
print 'usage: script <username> <password>'
exit(1)
username = sys.argv[1]
password = sys.argv[2]
epass = base64.b64encode(username + ':' + password)
print 'base64 encoded: ' + epass
baseUrl = 'ucrelease.example.org:8080'
url = 'http://' + baseUrl + '/applications/name'
opener = urllib2.build_opener(urllib2.HTTPHandler)
req = urllib2.Request(url)
req.add_header('Authorization', 'Basic '+epass)
req.get_method = lambda: 'GET'
resp = opener.open(req)
print resp.read()
Importing the server certificate
The
default server certificate is unsigned. Some tools do not connect
to servers with unsigned certificates by default. To access a server
with a self-signed certificate, you can instruct the tool to connect
insecurely, or you can import the certificate into your client. Follow
these steps to import the certificate into your client:
- Export the server certificate to a file:
- On the computer that hosts the IBM® UrbanCode Release server,
open the server.xml file in a text editor. By
default, this file is in the location /opt/IBM/UCRelease/server/tomcat/conf/server.xml.
- In the server.xml file, find the following
lines of code and note the values of the keystoreFile and keystorePass attributes:
sslProtocol="TLS"
keystoreFile="conf/tomcat.keystore"
keystorePass="changeit" />
- In a command-line window, run the following command:
keytool -v -list -keystore keyStoreFileName
The keytool application
is included in the Java™ developer
kit and is not part of IBM UrbanCode Release.
Use the name of the keystoreFile attribute from
the server.xml file for keyStoreFileName.
When the command prompts you for a password, specify the value of
the keystorePass attribute. The default value
is changeit.
- From the result of the command, find the alias of the server.
For example, the result of the command might look like the following
code:
Keystore type: JKS
Keystore provider: SUN
Your keystore contains 1 entry
Alias name: server
Creation date: Mar 19, 2014
Entry type: PrivateKeyEntry
In this code, the alias is server.
- Run the following command to export the certificate to a file
and specify the password again:
keytool -exportcert
-alias serverAlias
-keystore keyStoreFileName
-storetype jks
-file server.cert
Use the alias of the server for serverAlias.
- Copy the server.cert file to the client computer.
- Import the server.cert file into the keystore
of the client computer:
- In a command-line window on the client computer, run the following
command and specify the password for the keystore on the client. The
default is changeit.
jreLocation\jre\bin\keytool.exe -importcert
-alias serverAlias
-file tomcat.cert
-storetype jks
-keystore jreLocation\jre\lib\security\cacerts
Use
the location of the JRE or JDK for jreLocation.
Now, some tools that use this JRE or JDK accept the server certificate.
Other tools, such as
curl, might still not accept
the server certificate because it is unsigned. To resolve this problem,
set up a signed certificate for the server.