Ruby/Sinatra script to test App Framework v2 signed URL feature

disable_mixed_content_protection_chrome.png

disable_mixed_content_protection_firefox.png

manifest.json

{
  "name": "Remote Server App",
  "author": {
    "name": "John",
    "email": "john@omegacorp.com",
    "url": ""
  },
  "defaultLocale": "en",
  "private": true,
  "location": {
    "support": {
      "ticket_sidebar": {
        "url":"http://localhost:44000/"
      },
      "top_bar": {
        "url":"http://localhost:44000/",
        "signed":false
      }
    }
  },
  "version": "1.0",
  "signedUrls":true,
  "frameworkVersion": "2.0"
}

signed_url_test_server.rb

# This is a Ruby command line script that spins up a Sinatra server used 
# to test Zendesk Apps Signed URL feature.
#
# TODO - There's four TODO items in the code below that you need to do.
#
# Requirements:
#    Ruby: https://help.zendesk.com/hc/en-us/articles/229489288-Installing-and-using-the-Zendesk-apps-tools#topic_cxd_wqm_1l
#    Gems: gem install <gem name>
#
# After having Ruby and necessary gems installed, run: ruby signed_url_test_server.rb
#
# See also:
# https://developer.zendesk.com/apps/docs/apps-v2/using_sdk#authenticating-zendesk-in-your-server-side-app
#
# 
# TODO - 'gem install' each of the below
require 'jwt'
require 'sinatra'
require 'zendesk_api'

# See http://www.sinatrarb.com/configuration.html
set :port, 44000

# TODO - set your Zendesk subdomain
# Set up authenticated connection to given Zendesk instance.
client = ZendeskAPI::Client.new do |config|
  config.url = 'https://YOUR_ZENDESK_SUBDOMAIN.zendesk.com/api/v2'

  # TODO - Set your credentials. Example - run in terminal command window:
  #   export ZENDESK_USERNAME=john@zendesk.com 
  config.username = ENV['ZENDESK_USERNAME']
  config.password = ENV['ZENDESK_PASSWORD']
end

# TODO - Set app_id to *your* app's unqiue ID
# Use https://YOUR_ZENDESK_SUBDOMAIN.zendesk.com/api/v2/apps/installations.json to get Apps and their IDs
app_id = 222222 # Set this to your App ID (*not* installation ID)
rsa_public_pem = client.connection.get("apps/#{app_id}/public_key.pem").body
puts "Validating against App ID #{app_id} with public key:"
puts rsa_public_pem
rsa_public = OpenSSL::PKey::RSA.new(rsa_public_pem)
post_call_count = 0
get_call_count = 0

set :protection, except: :frame_options

post '/' do
  decoded_token = JWT.decode params[:token], rsa_public, true, algorithm: 'RS256'
  jwt_claims = decoded_token.first

  # This is where you can pull the user information from the JWT object
  # example sub value: "https://YOUR_ZENDESK_SUBDOMAIN.zendesk.com/api/v2/users/1234567890.json"
  puts jwt_claims
  user_info = client.connection.get(jwt_claims["sub"]).body
  user_name = user_info["user"]["name"]
  account_url = jwt_claims["iss"]
  post_call_count += 1
  "POST: Welcome #{user_name} from #{account_url}!<br/>call count: #{post_call_count}"  
end

get '/' do
  get_call_count += 1
  "GET: Welcome<br/>call count: #{get_call_count}"
end

Steps_demo_signed_urls.md

Summary

The manifest above in conjunction with the .rb script demonstrates the 'signed URL' feature.

The manifest has two locations for the app. The top_bar location has 'signed' turned off explicitly, so it will not pass a JWT/token to the remote server. The page will be loaded with a HTTP GET.

The ticket_sidebar has 'signed' turned on via the global 'signedUrls' manifest setting, so it will pass a JWT/token to the remote server. The page will be loaded with a HTTP POST.

The remote server's response text will display 'GET' or 'POST' depending upon which way the page load was done.

Create App Framework v2 server side app

1. Make sure you have Zendesk App Tools (ZAT) installed
2. In a terminal window, navigate to your code directory and run zat new and enter 'signed_url_test_app` for name
   • cd signed_url_test_app
3. Copy manifest from this gist
   • Note that app has two locations -- one 'signed' and one not signed
4. zat validate
5. Upload app (or run zat update, if you've already uploaded it to your instance)
6. Get App's ID -- put this value into myApp.rb (see below under Create Sinatra server)
   • Run yourdomain.zendesk.com/api/v2/apps/installations.json and get app ID

Create Sinatra server

1. Install needed gems
   • gem install {each gem at top of script}
2. create myApp.rb from above gist and paste in sample code
3. Update unique info (e.g. App ID, domain) and save
4. Create environment variables
   • export ZENDESK_USERNAME=john@zendesk.com
   • export ZENDESK_PASSWORD=YourPwd
5. Run: ruby myApp.rb

Run

1. Inside browser
   • Go to your zendesk domain and pick a ticket
   • Because your server is running locally, you need to disable protection to avoid 'Mixed content' errors
     • Avoids getting 'Blocked loading mixed active content' on Firefox or 'requested an insecure form action' on Chrome
   • Hard refresh (just to be sure)
   • Enable dev tools to watch console calls -- filter on '44000'. Make sure 'Security' console output is turned on.
2. Inside Zendesk
   • Append ?app_ids=<your app's ID> to ticket URL

See also

https://developer.zendesk.com/apps/docs/apps-v2/using_sdk#using-the-apps-framework https://developer.zendesk.com/apps/docs/apps-v2/manifest