Authenticating for REST commands

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:passwd
  https://myserver.example.com:8443/cli/application/info
  ?application=JPetStore

Authenticating with a session key

To use a session key, you must log in to the server as usual. Then, you retrieve the session key from your session with the server and use that session key in other tools.

To retrieve a session key, log in to the server as usual. Then, in the web browser, find the value of the header that is named UCD_SESSION_KEY. You can look for the cookie with that name or look at the list of headers that are associated with the web page. The way that you view this information depends on what browser you are using. See the documentation for your web browser for more information.

Then, you can use that session key to authenticate for REST commands. For example, you might add the following header to the request:
UCD_SESSION_KEY:sessionKey
Use the value of the UCD_SESSION_KEY cookie as sessionKey.

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 = 'ucdeploy.example.org:8443'

url = 'https://' + baseUrl + '/cli/application/info' + '?application=JPetStore'

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()
The following example is a Groovy script that authenticates in a similar way.
import groovyx.net.http.RESTClient
  
client = new RESTClient( 'https://ucdeploy.example.org:8443/cli/application/info?application=JPetStore' )
client.headers['Authorization'] = 'Basic '+"jsmith:passwd".bytes.encodeBase64()
 
def resp = client.get( path : 'application' )
 
println "Status: "+resp.status
assert resp.status == 200
println "ContentType: "+ resp.contentType
println resp.data

Authenticating in a Java class

The following Java code is a simple example of authenticating with a user name and password. The code accepts all certificates, but you can modify the code to control what certificates are accepted.

This example requires the HttpComponents-Util.jar and uDeployRestClient.jar JAR files. The file HttpComponents-Util.jar is available in the opt folder on the server. The file uDeployRestClient.jar is available in many core plug-ins, such as the UrbanCode Deploy Applications plug-in.

import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStreamReader;
import java.net.URI;
import java.net.URISyntaxException;

import org.apache.http.HttpResponse;
import org.apache.http.client.methods.HttpGet;
import org.apache.http.impl.client.DefaultHttpClient;
import org.apache.log4j.Logger;

import com.urbancode.commons.httpcomponentsutil.HttpClientBuilder;

public class RESTExample {

  public static void main(String[] args) {

  // suppress log4j messages from UCD library
  Logger.getRootLogger().setLevel(org.apache.log4j.Level.OFF);

  HttpClientBuilder clientBuilder = new HttpClientBuilder();
  clientBuilder.setUsername("admin");
  clientBuilder.setPassword("admin");

  // for SSL enabled servers, accept all certificates
  clientBuilder.setTrustAllCerts(true); 
  DefaultHttpClient client = clientBuilder.buildClient();

  try {
    HttpGet request = new HttpGet(new URI(
      "https://ucdeploy.example.org:8443/cli/application/info?application=JPetStore"));

    try {
      HttpResponseresp = client.execute(request);
      BufferedReaderbr = new BufferedReader ( 
        new InputStreamReader(resp.getEntity().getContent()));

      String currentLine = new String();
      while ((currentLine = br.readLine()) != null){
        System.out.print(currentLine);
      }
    } catch (IOException e) {
      e.printStackTrace();
    }
  } catch (URISyntaxException e) {
    e.printStackTrace();
  }

  }

}

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:
  1. Export the server certificate to a file:
    1. On the computer that hosts the IBM® UrbanCode Deploy server, open the server.xml file in a text editor. By default, this file is in the location server_install/opt/tomcat/conf/server.xml. The default server installation directory is /opt/ibm-ucd/server on Linux and C:\Program Files\ibm-ucd\server on Windows.
    2. 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" />
    3. In a command-line window, run the following command:
      keytool -v -list -keystore keyStoreFileName
      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.
    4. 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.
    5. 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.
  2. Copy the server.cert file to the client computer.
  3. Import the server.cert file into the keystore of the client computer:
    1. 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.

Feedback