Yarnman (YM-PH) Interfaces

Below lists the various interfaces that can be configured for Wrangler_ , test_mate, yarn_gate on the common Yarnman Photon Platform.

Webex API

Webex API uses OAuth2 to provide Access and Permissions to Webex API calls. An integration is created via the Webex developer portal that list the permissions and features (known as scopes in OAuth2). As part of the OAuth2 Process, a Webex User Authorises the integration with their Credentials which create the Tokens, No User/Pass are stored. The integration itself is just a list of permissions and doesn’t have access to Tokens. For more information visit https://developer.webex.com/docs/integrations for an overview.

All Organisations (eg customers) The Webex user has access too will be granted with the Integration. This is a more likely Scenario when using Partner Hub, where the “Partner full admin” or “Partner admin” can have access to multiple customers.

Add Interface

Login and Navigate to Interfaces > Add Interface

Select Webex API (OAuth2 - Cloud) as the Type

Select Permissions for Interface

test_mate_CV

This is a predefined list of Webex permissions that is used for Cloud Video testing, with wWebex and CVI (Cloud Video Interop) for further details https://yarnlab.atlassian.net/wiki/spaces/YSP/pages/2794225709

test_mate_WxC

This is predefined list of Webex permissions that is used with Webex Multi Tennant cloud calling, and requires the use of XSI to control phone endpoints registered to Webex. for further details https://yarnlab.atlassian.net/wiki/spaces/YSP/pages/2873851905

Wrangler_

This is predefined list of Webex permissions that is used with Webex Multi Tennant to read/write changes to an organisation.

The same interface can be used for Wrangler_ and test_mate, but each requires different Scope permissions, its recommended to use an interface for wrangler_ and another for test_mate.

This example will show setting up Wrangler_ for Webex Scopes.

Toggle the wrangler_WxC permission and Press Submit

Proxy is optional; Internet access is required to access https://webexapis.com/ from Yarnman.

The check Internet Access will verify the Proxy settings can reach webexapis.com, as well as the local browser can reach webex.com for the oAuth authentication flow.

in this context Client is your Web Browser connecting to webex , Server is Yarnman connecting to webexapis.com

View Permissions required to be set up in Webex integration

When the page saves, press Show Scopes

These are the required roles to be configured on your Webex integration

Create Webex Integration

Open a new Tab/Browser to Create a new Webex integration: https://developer.webex.com/my-apps

Service integration with static auth_token is not supported at this time

Set Webex permissions

Complete the required fields (we will come back to the redirect URI), select or upload a logo, and scroll down to choose the scopes to match the ones shown from Yarnman.

Find Redirect URL from yarnman

Switch back to Yarnman and select the Arm Bindings tab

Select the Yarnman node in the dropdown, followed by pressing Bind to Arm

Save redirect URL in Webex integration.

Copy the URL that is shown as Redirect URL and switch back to Webex

Paste in the URL to the URL field, and make sure to remove any leading Spaces or Tabs that may come through

Save Integration and obtain a Client ID and Secret

Press Add in Webex

Make note of the Client ID, Client Secret ( NOTE: this won't be shown again however it can be regenerated if lost)

Start oAuth flow with Set Credentials

Switch back to Yarnman

Press Update / Set Credentials

Populate

Application with either the same as you called it in Webex or something meaningful.

Client ID as string provided by Webex

Redirect URI as the one supplied by yarnman and press submit

The popup will refresh with an Authorise button with the confirmed details; Press Authorise to obtain the OAuth Token

The web browser will require Internet Access and Access to Yarnman, The Test . Please make sure your Jumpbox or Proxy settings in the browser allow for this configuration. If you have a proxy in your browser, you may need to bypass Yarnman's IP address.

The Webex authentication screen will be presented. Depending on your environment, this could be handled by Webex or your SSO provider, Such as Microsoft.

Webex will prompt you to allow or deny the permissions associated with your account.

Press accept and log back into yarnman when it redirects

Paste in the Client secret

Token details will be stored.

Test Connection can be pressed to verify that Yarnman can access Webex API by requesting a simple about me API.

Enable Auto Access Token Refresh

From Version 2.6.10 there is a new feature toggle to enable the Access and Refresh token to be auto refreshed every 6days. Toggle this on the settings page of the interface and press Submit

Troubleshooting Scopes

Yarnman can help validate the scopes configured in your Webex app

Copy the whole URL from Webex

Press Validate Scopes in Yarnman

Paste the URL in the popup from Yarnman.

Press validate, and Yarnman will advise the roles that need to be checked on the Webex app

XSI Permission not found

The XSI is a special permission that may not be available on your Webex org, Yarnlab has an integration available for this to provide this function, see the following page for further information about the permissions for test_mate for Webex calling. https://yarnlab.atlassian.net/wiki/spaces/YSP/pages/2873851905

Yarnlab do NOT need to know the webex credentials

Contact Yarnlab support to get an integration created https://support.yarnlab.io/ or support@yarnlab.io

Provide Yarnlab with the redirect URL provided on the interface page as per below, This will be unique per interface added and if multiple organisations/interfaces are being tested multiple redirect URLs will need to be provided

Troubleshooting Webex login

Where possible, it's best to use a Private/Incognito session to perform the oAuth flow. There could be issues with cached logins with SSO or the wrong SSO ID being prompted, causing the oAuth to fail with a change of UserID midsession.

Troubleshooting Connectivity

For the Oauth Flow to Work Correctly, the Web browser you use needs to be able to access Webex (the Internet) and Yarnman.

DNS

Below shows the yarnman server is not able to resolve the DNS

yarnman@ym-ph4-wxc-glen [ ~ ]$  curl "https://webexapis.com" -I
curl: (6) Could not resolve host: webexapis.com
yarnman@ym-ph4-wxc-glen [ ~ ]$

Check DNS servers used by the yarnman server (do not edit this file)

yarnman@ym-ph4-wxc-glen [ ~ ]$ cat /run/systemd/resolve/resolv.conf 
# This is /run/systemd/resolve/resolv.conf managed by man:systemd-resolved(8).
# Do not edit.
#
# This file might be symlinked as /etc/resolv.conf. If you're looking at
# /etc/resolv.conf and seeing this text, you have followed the symlink.
#
# This is a dynamic resolv.conf file for connecting local clients directly to
# all known uplink DNS servers. This file lists all configured search domains.
#
# Third party programs should typically not access this file directly, but only
# through the symlink at /etc/resolv.conf. To manage man:resolv.conf(5) in a
# different way, replace this symlink by a static file or a different symlink.
#
# See man:systemd-resolved.service(8) for details about the supported modes of
# operation for /etc/resolv.conf.

nameserver 10.0.0.1
search lab.yarnlab.io

to change the DNS servers, in this example, we are replacing the single DNS server with multiple DNS servers

You must first log in as the root user to modify system settings using su. exit out from the root when you are done

yarnman@ym-ph4-wxc-glen [ ~ ]$ su
Password: 
root@ym-ph4-wxc-glen [ /var/home/yarnman ]#  netmgr dns_servers --set --mode static --servers 8.8.8.8,8.8.4.4
root@ym-ph4-wxc-glen [ /var/home/yarnman ]# exit

yarnman@ym-ph4-wxc-glen [ ~ ]$ cat /run/systemd/resolve/resolv.conf 
# This is /run/systemd/resolve/resolv.conf managed by man:systemd-resolved(8).
# Do not edit.
#
# This file might be symlinked as /etc/resolv.conf. If you're looking at
# /etc/resolv.conf and seeing this text, you have followed the symlink.
#
# This is a dynamic resolv.conf file for connecting local clients directly to
# all known uplink DNS servers. This file lists all configured search domains.
#
# Third party programs should typically not access this file directly, but only
# through the symlink at /etc/resolv.conf. To manage man:resolv.conf(5) in a
# different way, replace this symlink by a static file or a different symlink.
#
# See man:systemd-resolved.service(8) for details about the supported modes of
# operation for /etc/resolv.conf.

nameserver 8.8.8.8
nameserver 8.8.4.4
search lab.yarnlab.io

Test to validate yarnman can reach webexapis.com, note 401 error as we are trying to browse without any credentials

Test Direct Access

yarnman@ym-ph4-wxc-glen [ ~ ]$ curl "https://webexapis.com" -I
HTTP/1.1 401 Unauthorized
x-content-type-options: nosniff
trackingid: ROUTERGW_5fdd5b92-b77f-40af-9f46-ceae729d74ba
vary: accept-encoding
content-type: application/json
date: Wed, 13 Mar 2024 03:22:59 GMT
server: istio-envoy
x-envoy-upstream-service-time: 1
transfer-encoding: chunked

Proxy

Depending on your environment, yarnman may also need to be able to resolve the proxy if a FQDN is required to the proxy server

You can verify yarnman can reach the proxy using curl, the http1.1 200 connection established shows the connection to the proxy was successful

Proxy without Auth

yarnman@ym-ph4-wxc-glen [ ~ ]$ curl --proxy "http://10.101.10.87:3130" "https://webexapis.com/" -I
HTTP/1.1 200 Connection established

HTTP/1.1 401 Unauthorized
x-content-type-options: nosniff
trackingid: ROUTERGW_2c5c1133-6586-42d2-a9cd-afaca8842baa
vary: accept-encoding
content-type: application/json
date: Wed, 13 Mar 2024 03:25:18 GMT
server: istio-envoy
x-envoy-upstream-service-time: 2
transfer-encoding: chunked

Proxy showing user/pass is required

Proxy server requires a user/pass to connect, with the 407 error

yarnman@ym-ph4-wxc-glen [ ~ ]$ curl --proxy "http://10.101.10.87:3129" "https://webexapis.com/" -I
HTTP/1.1 407 Proxy Authentication Required
Server: squid/4.13
Mime-Version: 1.0
Date: Wed, 13 Mar 2024 03:26:32 GMT
Content-Type: text/html;charset=utf-8
Content-Length: 3519
X-Squid-Error: ERR_CACHE_ACCESS_DENIED 0
Vary: Accept-Language
Content-Language: en
Proxy-Authenticate: Basic realm="Squid"
X-Cache: MISS from 18a6e4fa9a26
X-Cache-Lookup: NONE from 18a6e4fa9a26:3129
Via: 1.1 18a6e4fa9a26 (squid/4.13)
Connection: keep-alive

curl: (56) CONNECT tunnel failed, response 407

Proxy showing user/pass to the proxy

the first 407 tells curl to try again with user:pass, 200 connect is successful to the proxy followed by the 401 to webex as expected.

yarnman@ym-ph4-wxc-glen [ ~ ]$  curl --proxy-anyauth -x http://basicuser:basicuser123@10.101.10.87:3129 -4 "https://webexapis.com/" -I
HTTP/1.1 407 Proxy Authentication Required
Server: squid/4.13
Mime-Version: 1.0
Date: Wed, 13 Mar 2024 03:38:10 GMT
Content-Type: text/html;charset=utf-8
Content-Length: 3519
X-Squid-Error: ERR_CACHE_ACCESS_DENIED 0
Vary: Accept-Language
Content-Language: en
Proxy-Authenticate: Basic realm="Squid"
X-Cache: MISS from 18a6e4fa9a26
X-Cache-Lookup: NONE from 18a6e4fa9a26:3129
Via: 1.1 18a6e4fa9a26 (squid/4.13)
Connection: keep-alive

HTTP/1.1 200 Connection established

HTTP/1.1 401 Unauthorized
x-content-type-options: nosniff
trackingid: ROUTERGW_cc737ef5-1e1d-4e2f-8a1e-840dd944250f
vary: accept-encoding
content-type: application/json
date: Wed, 13 Mar 2024 03:38:11 GMT
server: istio-envoy
x-envoy-upstream-service-time: 3
transfer-encoding: chunked

Cisco Unified Communications Manager

This interface is used by Wrangler_ and test_mate to communicate with multiple services provided by the publisher or subscriber(s).

The following CUCM permissions are required for wrangler_

Standard CCM End Users
Standard Admin Users
Standard CCM Server Monitoring
Standard AXL API Access

Standard AXL API Access Role may need to be added to a custom Access Control Group, an alternative approach is to use

Standard CCM Super Users

The following CUCM permissions are required for wrangler_ WxC-DI migrations

Before starting the migration, the source and target CUCM, and if required CUC, interfaces must be defined. The minimum Required access roles in the CUCM Application User for the AXL interface are

Source CUCM

Standard AXL API Access
Standard CCM Admin Users
Standard SERVICEABILITY Read Only

Standard AXL Read Only API Access

To enable Read-Only access select the ‘Standard AXL API Users’ and ‘Standard AXL Read Only API Access’ roles refer to https://developer.cisco.com/docs/axl/#!authentication/using-basic-authentication as both roles are arequired for RO access

Standard AXL API Access Role may need to be added to a custom Access Control Group, an alternative approach is to use Standard CCM Super Users

WxC-DI (Target) interface

As provided by Cisco with the following proviso if creating/ migrating Custom Access Control Groups in WxC-DI

If migrating to WxC-DI, unless specifically requested, Cisco will assign an account with Rank 3 and no capability to read/ create Access Control Groups in WxC-DI target. So if Custom ACG’s need to be created, an account with these rights (Rank1) need to be requested from Cisco

CUC Access

Role

System Administrator

The following Permissions are required for test_mate

Standard CCM End Users
Standard Admin Users
Standard CTI Enabled
Standard CCM Server Monitoring
Standard CTI Allow Control of Phones supporting Rollover Mode
Standard CTI Allow Control of Phones supporting Connected Xfer and conf
Standard AXL API Access

Standard AXL API Access Role may need to be added to a custom Access Control Group, an alternative approach is to use

Standard CCM Super Users

Create a new interface in yarnman

name the interface and press submit
Bind the interface to the required arm(s)
Press update/set Credentials
Type in the ip address of the publisher (this will automatically fill in the details to all the other services)
Type in the user and password, press use for all interfaces.
Press submit followed by test connection.

the default cucm administrator account can not control jtapi devices

Jade-Berlin

Whilst not technically an interface, this service provide jtapi control and uses the cucm interface within yarnman applications, mainly test_mate.

The jtapi.jar must be downloaded from the cucm.

This is done by navigating to Nodes > clicking on the node name > Pressing (re)download jtapi.jar

Provide the ip address of the publisher, once jtapi.jar has downloaded press restart Jade-Berlin

Not all jtapi.jar versions are backwards compatible with different versions of cucms.

Common error messages from jtapi

Unable to create provider -- User connected on an invalid port

Most likely Secure CTI permission applied to the application user in cucm, remove secure CTI and only have standard cti

Unable to create provider -- connect timed out

This could be related to firewall or network connectivity between yarnman and cucm, CTI Manager not running on the target node

Unable to create provider -- bad login or password

Most likely wrong username/password/permission on the application user

Unable to create provider -- Incompatible Protocol version

The version of jtapi.jar cached in jade-berlin is not compatible with the target cucm, Download jtapi.jar from target cucm and restart jade-berlin

Unable to create provider -- directory login timeout

Can related to LDAP/AD timeout, high database load on cucm or jtapi not responding

MSGraph

This is used to access o365 calendaring information for test_mate Cloud Video. This also uses OAuthv2, but more in a API key method

a ClientID and ClientSecret are required, which are provisioned in Microsoft Entra ID (formerly Azure Active Directory) with the required permissions and access. The API key will expire after a period of time, usually 180days (this depends on the customers security policy)

Microsoft Graph	Type
Calendars.Read	Application
Calendars.ReadWrite	Application
OnlineMeetingArtifact.Read.All	Application
OnlineMeetings.Read.All	Application
OnlineMeetings.ReadWrite.All	Application
User.Read.All	Application
CallRecords.Read.All	Application

The API Key created should be limited to only the meeting room mailboxes/resources https://learn.microsoft.com/en-us/graph/auth-limit-mailbox-access

Select the Microsoft Graph API as the interface type, Configure a Proxy if required in the environment. Bind the Arm to the yarnman server.

Press Update/Set credentials enter in the AppID, AppKey and default microsoft TenantID

Pressing Test connection will return a list of users if successful

PRTG

Currently used with yarn_gate to allow a HTTP push to Paessler PRTG for scheduled tasks results.

Select PRTG as the interface type, provide a description and the HTTP/S PRTG Sensor Address.

This interface supports both HTTP and HTTPS for the server address, depending on the PRTG sensor setup.

Click on Arm bindings to bind this to a yarnman server(s)