Socconx12 integrating ibm connections docs 2 and box

presentation about integration of IBM Docs and BOX

1. Vienna, October 16-17 2017
IntegratingIBM Connections Docs 2.0
with Box
Roberto Boccadoro
@robboc59
blog http://robertoboccadoro.com/
[email protected]

2. Vienna, October 16-17 2017
PLATINUM SPONSORS
GOLD SPONSORS
SILVER SPONSORS
BRONZE SPONSORS

3. Vienna, October 16-17 2017
The recipe
•What we want to configure, at very high level, is the following:
•Create an UI extension on BOX to allow the user to invoke IBM DOCs via the BOX User Interface
•The extension should clearly define the IBM DOCs endpoint that needs to be reached
•We do not want to exchange username/passwords. So we need to have BOX generate the OAuthkeys
that will be used by IBM DOCs when it will need to talk with BOX.
At the same time, we need to tell BOX which instance of IBM DOCs it will need to work with
•After the user will use the BOX UI extension, we expect that IBM DOCs would need to invoke BOX to get
the document to be edited, to get information about the user editing it, to send the modified document
back to BOX.
Thus we need to tell IBM DOCs which are the BOX APIs to call and how to authenticate at BOX. This
authentication needs to be the most transparent as possible as we do not want to perform multiple
logins
•As IBM DOCs is a WebSphere Application Server application, we also need to define the security
artefacts that would allow the J2EE engine to interact with BOX

4. Vienna, October 16-17 2017
How isitdone?
Thereare a fewstepsneeded
1.Create an app in Box
2.Editthe Docsconfigurationfile
3.Set up Oauthcredentialfor Box
4.Addbox.com certificatesin WAS trust store

5. Vienna, October 16-17 2017
1) Create a Box application
•Log in to the Box developer console at https://developers.box.com/
•On the right side of the page click on “Create a Box Application”
•Choose a name for the application and click “Create Application”

6. Vienna, October 16-17 2017
•In the next page in the section General Information make sureContent
API Access Onlyis selected

7. Vienna, October 16-17 2017
•In the section OAuth2 Parameters take note of client_idand
client_secretfor the Box application. You need to import the OAuth
credentials to the IBM Docs system.
•The redirect_uriin the OAuth2 Parameters section should be the
same used in docs_call_back_urlof the IBM Docs non-IBM product
integration, such as
"https://<docs_server>:<port>/docs/driverscallback".
•Set the user type to Standard Box users.

8. Vienna, October 16-17 2017

9. Vienna, October 16-17 2017
•Go to the Web App Integrations section and click Create a
New Web App Integration.

10. Vienna, October 16-17 2017
In the General Information section:
•Choose a name for the web application, and fill in the description
for the application.
•Add supported extensions for Docs:.docx, .pptx, .xlsx, .doc, .xls,
.ppt, .ods, .odt, .odp, .csv, .txt.
•UnderPermissions requirement, select Full permissions are
required.
•In the Scoped tofield, select The parent folder of the file/folder
from which this integration is invoked.
•Set the category to Editing.
•Set the file type category to Documents.
•Set the integration status to Online .

11. Vienna, October 16-17 2017

12. Vienna, October 16-17 2017
In the Callback Configuration section:
•Make the integration open a popup in a new tab.
•Use REST method.
•Leave the Preliminary Callback URL field empty.
•The client callback URL should be the callback URL of the IBM Docs
non-IBM product integration and must use the https protocol, such as
"https://docs_server/docs/driverscallback".

13. Vienna, October 16-17 2017
In the Callback Parameters section click on “add callback parameter”
Add the file_idparameter
Add the repository parameter
Add codeparameter

14. Vienna, October 16-17 2017
•Leave the other fields as default.
•Save the Web App Integration
•Save the Box Application

15. Vienna, October 16-17 2017
2) EditDocsconfigurationfile
Go in <WAS install root>/profiles/Dmgr01/config/cells/<cell
name>/IBMDocs-config/ and edit concord.config.json
Tip: use Notepad++ or another«smart» editor, thiswillhelp youa lotwith the correct syntax
At the beginningof the file addthe followingcode
"x-frame- options": {
"allow_option":"ALLOW- FROM",
"allow_uri":
https://app.box.com
}
Don’tgetmadtryingto copy the text from the slides. Grabthe documentwewroteand you’llfindallthe neededcode in there
https://www.ibm.com/developerworks/community/files/form/anonymous/api/library/98a7ab0c-9742-463d-bf96-
1c4ff2a65138/document/8f2d3c09-7874-4566-b6d4-
cb410bbba54d/media/Integrate%20IBM%20Connections%20Docs%202.0%20with%20BOX.docx

16. Vienna, October 16-17 2017
•Search the JSON code related to the class
"com.ibm.docs.repository.external.rest.ExternalRestRepository" for the id
“external.rest” as shown here:

17. Vienna, October 16-17 2017
•Addthe followingcode
"s2s_method" : "oauth2"
"customer_id" : "box.com"
"oauth2_endpoint" : https://app.box.com/api/oauth2/token
"media_meta_url" : https://api.box.com/2.0/files/{ID}
"media_get_url" : https://api.box.com/2.0/files/{ID}/content
"media_set_url" : https://upload.box.com/api/2.0/files/{ID}/content
"docs_callback_endpoint" : https://<docs_servername>:<port>/docs/driverscallback
"repository_home" : https://app.box.com
This will make the JSON fragment look like the one here below:

18. Vienna, October 16-17 2017
•Search the JSON code related to the class
"com.ibm.docs.authentication.filters.ExternalAuth" for the id
“external.rest” as shown here:
•Addthe followingcode
s2s_method : “oauth2”
This will make the JSON fragment look like the one here below:

19. Vienna, October 16-17 2017
•Search the JSON code related to the class
"com.ibm.docs.directory.external.ExternalDirectory" for the id
“external.rest” as shown here:

20. Vienna, October 16-17 2017
•Addthe followingcode
“s2s_method” : “oauth2”
"profiles_url": https://api.box.com/2.0/users/{ID}
"current_user_profiles_url": https://api.box.com/2.0/users/me
"bypass_sso":"true" "docs_callback_endpoint": https://<docs_server name>:<port>/docs/
driverscallback
"oauth2_endpoint": https://app.box.com/api/oauth2/token
"customer_id": "box.com"
"keys": "org_id_key": "org_id "
"keys":"photo_url_key": "avatar_url"
"keys":"url_query_key": "ID"
"keys":"display_name_key": "name"
"keys":"name_key": "name"
"keys":"id_key": "id"
"keys":"email_key": "login"
This will make the JSON fragment look like the one here:

21. Vienna, October 16-17 2017
•Searchthe " socialConfig"item
•Modify the following parameter as
follows :
"url": https://api.box.com/2.0/users/{ID}”

22. Vienna, October 16-17 2017
•Syncthe nodes
•and then from the WebSphere console, restart the application servers
where the Editor Application is installed.

23. Vienna, October 16-17 2017
3) Set up Oauthcredentialfor Box
•On the IBM Docs server, go to the folder ${WAS_INSTALL_ROOT}/profiles/AppSrv1/bin and run the following command:
•wsadmin.bat -langjython-username xx -password xx -f ${PATH}/customer_credential_mgr.py -action add - customer customer_id-key
key-value value"
where:
•customer_credential_mgr.py is located in the IBM Docs installation package, ${PATH} is the location of the file, for example,
CN30NML.zip\IBMConnectionsDocsrepo\native\DocsApp_2.0.0.zip\ installer\docs\tasks\(extract the necessary files before using)
•customer_idis the value specified in customer_id in ${WAS_INSTALL_ROOT}/profiles/AppSrv1/config/cells/{cell}/IBMDocs-
config/concord-config.json.
•key could be oauth2_client_id or oauth2_client_secret and value should be the one that the repository server assigned to the IBM Docs
application. You can get the value when you create the IBM Docs app

24. Vienna, October 16-17 2017
For example:
wsadmin.bat -langjython-user xx -password xx -f customer_credential_mgr.py -action
add -customer abc.com -key oauth2_client_id -value
"l7xxf61984f99f404575a781d47c6bfebdca"
wsadmin.bat -langjython-user xx -password xx -f customer_credential_mgr.py -action
add -customer abc.com -key oauth2_client_secret -value
"cc692ce34451418e86d9b231ee34af65"

25. Vienna, October 16-17 2017
4) Add box.com https certificates into the WebSphere local trust store
•Log into the WebSphere Application Server Administrative Console.
•Expand Securityand click SSL certificate and key management.
•Under Configuration settings, click Manage endpoint security configurations.

26. Vienna, October 16-17 2017
•Select the appropriate outbound
configuration to get to the (cell)
management scope.

27. Vienna, October 16-17 2017
•Under Related Items, click Key stores and certificates.
•Click the CellDefaultTrustStorekey store

28. Vienna, October 16-17 2017
•Under Additional Properties, click Signer certificates > Retrieve From Port
•In the Hostfield, enter api.box.com, the port_number value 443 in the Port
field, and the api.box.com in the Alias field.
•Click Retrieve Signer Information.

29. Vienna, October 16-17 2017
•Verify that the certificate information is for a certificate that you can trust
•Click Apply and Save
•Restart Deployment Manager, all nodes and app servers.

30. Vienna, October 16-17 2017
Test the integration

31. Vienna, October 16-17 2017

32. Vienna, October 16-17 2017
•Log into your BOX account

33. Vienna, October 16-17 2017
•Select the document you want to edit and navigate to the “Edit with IBM DOCs” extension that was previously created

34. Vienna, October 16-17 2017
•Click on the “Edit with IBM DOCs” and then click “Okay”

35. Vienna, October 16-17 2017
•You do not need to be logged in IBM DOCs / IBM Connections.
IBM DOCs will open the document to be edited under the name of the BOX user :
NOTE: IBM
DOCs was also
able to get the
user’s picture
from BOX.

36. Vienna, October 16-17 2017
•Comments are also included under the name of the BOX user as shown below:

37. Vienna, October 16-17 2017
Once finished, you can force the “Save to Repository” which actually creates a new version of the document inside BOX:

38. Vienna, October 16-17 2017

39. Vienna, October 16-17 2017
Nothing changes to the behavior described above if am logged into
IBM Connections or IBM DOCs.

40. Vienna, October 16-17 2017
Runtime flow of information between IBM DOCs and BOX.
1. A BOX user asks BOX to give IBM DOCs permission to access one of her files.
This step maps the action of the BOX user clicking on the new menu item “Edit in IBM DOCs” from the
BOX’s file contextual menu
2. BOX retrieves the id of the currently logged-in BOX user and the BOX Application’s id (the API Key)
One of the information that BOX generates when the “Edit in IBM DOCs” BOX application is created is
the API Key (you find it just at the bottom of the Application page as shown here):

41. Vienna, October 16-17 2017
3.BOX generates the “auth_code”.
This auth_codewill be generated based on some schema to ensure its uniqueness; then it will be internally managed
by BOX together with the “Box user id” and the “API Key”.
4.The Browser will be redirected to the IBM DOCs “redirect_uri” with the auth_code, the file_idand the string
“rest” in the query string
5.IBM DOCs exchanges the “auth_code” and the OAUTH2 keys (stored in WebSphere) against the BOX OAUTH2
Token by invoking the BOX API specified by the “oauth2_endpoint” parameter in the concord-config.json
parameter.
In this way, BOX will be able to retrieve the information about the BOX user and the Application that is invoked
(via the auth_code), thus replacing the need for the first leg of the OAUTH2 dance (which cannot happen because
this conversation happens from the IBM DOCs server to the BOX runtime)
Runtime flow of information between IBM DOCs and BOX.

42. Vienna, October 16-17 2017
6.Now, IBM DOCs has the OAUTH2 token to perform all the other calls to BOX (the media_meta_url, media_get_url
and media_set_urlparameters previously specified in concord- config.json)
7.IBM DOCs invokes the media_meta_urlto get, from BOX, the metadata about the file to be edited.
Metadata include the “mime type”, the “user” and the “timestamp for the last version”.
8.If IBM DOCs did not cache an older version of the document on respect to the one specified by the timestamp, it
invokes the media_get_urlto ask BOX to retrieve the content of the file.
In case IBM DOCs cached the last version, the media_get_url apiis not invoked but the cached content is used.
9.Once the user on IBM DOCs decides to save a modified version of the file, the media_set_url of BOX is invoked to
push the content of the modified version
Runtime flow of information between IBM DOCs and BOX.

43. Vienna, October 16-17 2017
Thankyou

44. Vienna, October 16-17 2017

45. Vienna, October 16-17 2017
PLATINUM SPONSORS
GOLD SPONSORS
SILVER SPONSORS
BRONZE SPONSORS