Troubleshooting UAA Service | Essentials

Troubleshooting UAA Command Line Interface (UAAC) Installation Issues

There are a number of ways you can install UAAC. The procedure lists recommended installation steps for Windows and Linux users.

Windows

Install Ruby from http://rubyinstaller.org/downloads.
Use the stable version of Ruby (version 2.1.x).
Note: The 64-bit versions of Ruby are relatively new and not all the packages have been updated to be compatible with it. To use the 64-bit version you will require compiler knowledge, and you will need to be prepared to solve dependency issues.
Install the Ruby development kit.
Follow the installation steps at https://github.com/oneclick/rubyinstaller/wiki/Development-Kit.
Download Gem for UAAC, cf-uaac*.gem, from https://rubygems.org/gems/cf-uaac.
Install the cf-uaac*.gem gem.
```
gem install cf-uaac*.gem
```
Test if the installation was successful.
```
uaac help
```

Linux

Installation of UAAC on Linux or Mac is easier if you use the bundler gem to install all the required dependencies for cf-uaac gem install.

Verify that the Ruby version of Ruby is a stable version (version 2.1.x).
```
ruby --version
```
Download Gem for Bundler, bundler.gem, from https://rubygems.org/gems/bundler.
Install the bundler gem.
```
gem install bundler
```
Generate a Gemfile with the default rubygems.org source.
```
bundle init
```
The Gemfile is created in the same location as the bundler gem.

Edit the new Gemfile to include the gems you want to include in the bundle.

# A sample Gemfile
source "https://rubygems.org"

# gem "rails"
gem 'nokogiri'
gem 'rack', '~>1.1'
gem 'rspec', :require => 'spec'
gem 'cf-uaac'

Install all of the required gems from your specified sources.
```
bundle install
```
Install the cf-uaac gem.
```
gem install cf-uaac
```
Test to see if the installation was successful.
```
uaac help
```

Troubleshooting Oauth2 Issues

Predix platform services use OAuth2 for authentication. Errors related to OAuth2 include the HTTP 401 Authorization error. To troubleshoot an OAuth2 issue, check the claims in a user or application token. For example, if you receive an HTTP 401 authorization error, you need to make sure that the token was issued from the correct UAA (iss claim) with the required scopes (scope).

CAUTION:

Using online tools to decode tokens comes with several risks. If a token is stolen, it can be used by anyone to access protected resources without any other credentials. Even after a token expires, its claims information exposes internal details about Predix applications and systems, which can be used to help in other attacks.

Use the following tools to decode tokens on your local machine:

UAAC

Use the following command to decode a token:

uaac token decode

Example:

uaac token decode 
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovLzEyMzQxMzQzMTI
0MTMubXktZG9tYWluLmNvbS9vYXV0aC90b2tlbiIsInNjb3BlIjoidGVzdCIsInN1YiI6Imp
vZUBleGFtcGxlLmNvbSJ9.KGzJ12fOqBF2sxi9F3oFG3FDWBmNES9TU2j7yc_XyP0

Note: no key given to validate token signature

iss: https://1234134312413.my-domain.com/oauth/token
scope: test
sub: joe@example.com

Note:

As indicated in the UAAC output message, you can provide a public key to validate the issuer of the token.

Base64

The JWT claims are Base64-encoded JSON. If you do not need to validate the JWT issuer, use a tool that can decode the token claims section.

A JWT token uses the following format:

base64encoded_header.base64encoded_claims.signature

Use the following command to list the claims:

echo | cut -f 2 -d . | base64 --decode

Example:

~/dev$
echo 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovLzEyMzQxM
zQzMTI0MTMubXktZG9tYWluLmNvbS9vYXV0aC90b2tlbiIsInNjb3BlIjoidGVzdCIsInN1Y
iI6ImpvZUBleGFtcGxlLmNvbSJ9.KGzJ12fOqBF2sxi9F3oFG3FDWBmNES9TU2j7yc_XyP0' 
| cut -f 2 -d . | base64 --decode
{"iss":"https://1234134312413.my-domain.com/oauth/token","scope":"test","sub":"joe@example.com"}

~/dev$

SSLException while targeting a UAA instance using UAAC

When targeting multiple UAA instances using UAAC, the client is able to authenticate some UAA instances successfully, but for others it generates an SSLException.

Cause

One probable cause of this issue is your proxy settings. Additionally the versions of UAAC, Ruby, and OpenSSL that you are using do not support a new GE certificate and you need to be able to accept TLS1.2 connections.

Solution

As a workaround, you can use the --skip-ssl-validation flag.

Use the following command to check the SSL certificate:

openssl ciphers -v | awk '{print $2}' | sort | uniq

Use the latest versions of UAAC, Ruby and OpenSSL.