BoxWorks Developer Training

Developer training workshop presented at BoxWorks 2019. Topics of the presentation include:
* Box platform use cases and setting up your first app
* Users, folders, service accounts, and rate limits
* Token and account management
* Metadata functionality
* UI Tools and services
* Reporting and monitoring
* Connecting Box to external systems (i.e. for identity or reporting services)

Transcript

1. Box Platform Developer Workshop Box Developer Advocacy Team Website: developer.box.com / box.dev Twitter: @BoxPlatform Email: devrel@box.com Simplify how you work
2. 2 Box Platform Developer Workshop What are we looking at today? 1.Box platform use cases and setting up your first app 2.Users, folders, service accounts, and rate limits 3.Token and account management 4.Metadata functionality 5.UI Tools and services 6.Reporting and monitoring 7.Connecting Box to external systems (i.e. for identity or reporting services)
3. 3 Box Platform Developer Workshop Box Platform Introduction Common Application Types
4. 4 Box Platform Developer Workshop Mortgage lending, insurance, banking § Example: Maxwell. § Multiple users that may be working with a single account. § Typically heavy metadata use on files to maintain state. Multiple users handling single account
5. 5 Box Platform Developer Workshop Digital Vaults and Document Submission § Example: LegalZoom, Robots and Pencils. § Sensitive storage of account records, medical data, or other PII. § Typically set up as a 1:1 interaction, where the app interacts with a single user. Secure storage of sensitive information
6. 6 Box Platform Developer Workshop Back Office Reporting and Monitoring § Automated account that runs on a regular interval. § Uses the Box event stream and/or webhooks to either monitor changes to the Box account or generate reports based on activity. § Doesn’t make requests on behalf of Box users. Automated reporting, sensitive information detection
7. 7 Box Platform Developer Workshop Box Platform Setting up your first application
8. 8 Box Platform Developer Workshop Live Example § Important aspects of the developer site. § Set up your first application. § Authorize your application through the admin console. § Set up first auth call Creating your first application on Box Platform
9. 9 Box Platform Developer Workshop // Generate 2048 bit private key encrypted with des3 cipher openssl genrsa -des3 -out private.pem 2048 // Generate public key from private key openssl rsa -in private.pem -outform PEM -pubout -out public.pem Generating public / private keys from the terminal
10. 10 Box Platform Developer Workshop Box Platform Application Scopes
11. 11 Box Platform Developer Workshop Application Scopes What your application will have permission to do on behalf of the application, enterprise, and users.
12. 12 Box Platform Developer Workshop Read / Write Files & Folders / Upload / View / Download files and folders, and update file versions. / Create / Read / Update / Delete collaborations, tags, tasks, comments, @mentions, task assignments, notifications, and collections. / View enterprise profile information.
13. 13 Box Platform Developer Workshop Manage Users / Create / Read / Update / Delete / Activate / Disable Users (app and managed). / Change primary login, reset password, change role for managed users and enterprise content.
14. 14 Box Platform Developer Workshop / Create / Read / Update / Delete groups and group memberships for users. Manage Groups
15. 15 Box Platform Developer Workshop / App can programmatically control webhooks (referred to as webhooks v2). / Create / Read / Update / Delete new or existing webhooks on files and folders. Manage Webhooks
16. 16 Box Platform Developer Workshop Manage Enterprise Properties / Read / Update enterprise attributes and reports. / Edit / Delete device pinners (what devices can use native Box applications).
17. 17 Box Platform Developer Workshop Manage Retention Policies / Create / Read / Update data retention policies. / Feature is tied to Box Governance service package.
18. 18 Box Platform Developer Workshop Enable Integrations / Enables the usage of Box Elements
19. 19 Box Platform Developer Workshop Box Platform User Types
20. 20 Box Platform Developer Workshop Managed User Service Account / App User External User Same as a managed user, but is not part of the same enterprise as the app. These are users that have been collaborated into content by a user in the enterprise. A regular Box user that is part of the same enterprise as the app. This user account can be accessed by the API or by logging in to box.com Programmatic accounts representing the app or a user. These accounts can only be accessed through API calls. Types of Users Defined within Box
21. 21 Box Platform Developer Workshop Box Platform Service Accounts
22. 22 Box Platform Developer Workshop What is a Service Account
23. 23 Box Platform Developer Workshop Service Account Details § A user account that represents your application in an enterprise. § Can only be accessed programmatically. § Has its own file storage. § Generated automatically with a new JWT application. § By default, a service account only has access to its own data store. § Access to app users / managed users has to be explicitly enabled and requested. Access Rights
24. 24 Box Platform Developer Workshop Users and Permissions
25. 25 Box Platform Developer Workshop App Users No User Access All Users Service account can access its own content, app user content, as well as content of any users in the enterprise Service account can access its own content and content for any app users it creates Service account can only access its own content User Access Levels for a Service Account
26. 26 Box Platform Developer Workshop Application Access § Application: Only access data and users within the JWT app. § Enterprise: Access data and users within the app as well as the entire enterprise that the app is a part of.
27. 27 Box Platform Developer Workshop Advanced Features § Perform actions as users: Use an As-User header with each request to act on behalf of a user. Access token passed is for service account. § Generate user access tokens: Create an access token scoped to a user account and use that token for each request.
28. 28 Box Platform Developer Workshop User Access Application Access Advanced Features No User Access Application None set App Users Only Application One or both set App and Managed Users Enterprise One or both set Setting User Access for the Service Account Settings to use to get the desired level of user access for a service account
29. 29 Best Practices for Application Development with Box Data ownership and making API requests to Box
30. 30 Best Practices for Application Development with Box Service Account User Account Maintain all user an application data within the service account. Users will be collaborated in on content. User specific data is maintained in the individual user account. All data access requests are made on behalf of the user. Where to Store User and Application Data
31. 31 Best Practices for Application Development with Box Storing Data in the Service Account (Overview) § Improved data security due to tight controls over data location and sharing § Data retention and migration improves following customer deletion, as the user collaboration is simply removed. Benefits § Architecture complexity increases as a separate user folder structure needs to be maintained in the service account. § Single point of failure. Concerns
32. 32 Best Practices for Application Development with Box Storing Data in the User Account (Overview) § Data is retained and owned by each user. § Simple repeatable architecture on each user account. Benefits § Data retention after customer deletion requires data migration or loss. § App has no control over data integrity. Concerns
33. 33 Best Practices for Application Development with Box Rate Limits
34. 34 Best Practices for Application Development with Box Understanding rate limits HTTP/1.1 429 Too Many Requests Retry-After: {retry time in seconds}
35. 35 Best Practices for Application Development with Box Rate Limits Limits imposed on API calls by Box Platform / Per user rate limits § 16.67 API calls per second per user (1000 / minute). § 4 uploads per second per user. § 6 searches per second per user, up to 60 searches per minute. / Per enterprise limits § 12 searches per second per enterprise.
36. 36 Box Platform Developer Workshop Causes and Solutions of Rate Limiting Check Retry-After header for amount of time until next call / Making requests to auth a user each time they visit. Access tokens should be stored for future use. / Polling the event stream too often. Cache results when possible. / Producing too many requests from a single user (e.g. a service account). Make calls on behalf of users or use a queuing / exponential backoff system. / Making too many simultaneous upload requests from a single user. Make calls on behalf of users or use a queuing / exponential backoff system. / Making too many search requests too quickly. Make calls on behalf of users or use a queuing / exponential backoff system.
37. 37 Box Platform Developer Workshop Exponential Backoff Benefits of exponential backoff and jitter when implementing retry logic / Specifies the retry cadence for your application once you hit a rate limit boundary. / Typical pattern is to double the previous time period until a successful response is achieved (i.e. 1 second, then 2 seconds, then 4 seconds, then 8 seconds) / Advanced patterns with many competing clients / calls introduce the concept of jitter, the introduction of randomness in the retry logic. § Take the typical pattern with the retry between 2-4 seconds. Next retry would happen exactly at 4 seconds. § The introduction of jitter (random value) makes the retry happen at a random time between 2-4 seconds.
38. 38 Best Practices for Application Development with Box Folder Architecture
39. 39 Box Platform Developer Workshop Duplicate Folders for each User Common Folder Models A folder model is created and duplicated for each user. Collaborators or groups are added at each level. App User 1 App User 2 Config User Data Personnel Operations Config User Data Personnel Operations
40. 40 Box Platform Developer Workshop Common Folder Models Business Level Ownership The Box enterprise admin, or appropriate leadership level, would maintain the root folder level. Each business level is maintained under that level, where major business units may have minor units located underneath. Enterprise Admin Marketing Sales Products Parts & Services Engineering
41. 41 Box Platform Developer Workshop Collaborations
42. 42 Box Platform Developer Workshop Collaboration System § Service accounts and users start by only being able to access content in their own accounts. § For those accounts to access content from other accounts they will need to be collaborated in on content. § Users can be collaborated via ID, email, or group ID.
43. 43 Box Platform Developer Workshop / co-owner: Full access / editor: Full access minus invites / settings / previewer: Basic view and edit / previewer uploader: Previewer + uploader / uploader: Upload, basic metadata, and view / viewer: Preview + download and send links / viewer uploader: Viewer + uploader Collaboration Types
44. 44 Box Platform Developer Workshop Audience Exercise Understanding users and folders
45. 45 Box Platform Developer Workshop Audience Exercise Users and Folders / Architecture Exercise: Open the first architecture exercise envelope on your table. You have an example scenario listed off. As a team create the user and folder model architecture for your application. / Code Exercise: Open the first coding exercise envelope on your table. There are a number of scenario requirements listed to help understand the correct folder / user architecture for the scenario.
46. 46 Box Platform Developer Workshop Audience Exercise Review Users and Folders / Architecture Exercises: § Review the use case that was provided. § Talk about how you would structure your users and folders. § Discuss any potential pitfalls or additional implementations with the architecture. § Participation Prizes!
47. 47 Box Platform Developer Workshop Token Management and Account Maintenance
48. 48 Box Platform Developer Workshop / Exposing fully scoped access tokens within unsecure environments can lead to data leakage. / User session level token management can help further restrict token availability. / Application / service account settings can help further restrict user level access. / Recycling inactive account can help improve compliance and security. Building off the least privilege principle
49. 49 Box Platform Developer Workshop Reducing auth calls by storing access tokens
50. 50 Box Platform Developer Workshop Access Token Best Practices / Access tokens are valid for 1 hour and should be stored / reused. / Official server-side SDKs (Node, Java, .Net, Python) automatically refresh tokens. If these SDKs aren’t used, tokens need to be maintained manually. / Expired tokens will return a 401: Unauthorized error. This error should be handled to refresh the token. / JWT applications do not return a refresh token, use your standard auth credentials.
51. 51 Box Platform Developer Workshop Downscoping Tokens
52. 52 Box Platform Developer Workshop Downscoped Token Access Token Client-Side Code Downscoped token is deployed to client-side code, mobile environment, or UI tool. New access token that is tightly restricted in access rights (read / write) for a file or folder. Standard OAuth2 access token that is fully scoped for an enterprise or user. Token Downscoping Process
53. 53 Box Platform Developer Workshop // Define resource/scopes String resource = null; List<String> scopes = new ArrayList<String>(); scopes.add("base_preview"); scopes.add("item_download"); // Perform token exchange to get downscoped token ScopedToken downscopedToken = client.getLowerScopedToken(scopes, resource); // Downscoped token available in downscopedToken.getAccessToken() Downscoping a Token (Java SDK)
54. 54 Box Platform Developer Workshop Revoking Tokens
55. 55 Box Platform Developer Workshop Token Revocation / Both fully scoped access tokens as well as downscoped tokens may be revoked. / Allows you to manage the lifespan of a token to reduce exposure when a user logs out, there is suspicious activity, or when you need to push new security enhancements.
56. 56 Box Platform Developer Workshop curl -X POST https://api.box.com/oauth2/revoke \ -H "Content-Type: application/x-www-form-urlencoded" \ -d '{ "client_id": "<CLIENT_ID>", "client_secret": "<CLIENT_SECRET>", "token": "<ACCESS_TOKEN>" }' Revoking a Token (cURL)
57. 57 Box Platform Developer Workshop // Node Token Revocation client.revokeTokens("<TOKEN>").then(() => { // Client access token have been revoked }); # Python Token Revocation oauth.revoke() Revoking a Token (Node / Python)
58. 58 Box Platform Developer Workshop Account Recycling
59. 59 Box Platform Developer Workshop Best practices for long term storage § Inactive accounts: When an account is deactivated or inactive for a period of time, it should be recycled. § Long term storage: The service account should be used for long term data storage for compliance, segmented by user ID. § Transferring data: Data may be transferred between accounts by using the move content endpoints or by changing the content owner to the service account by using the collaboration endpoints.
60. 60 Box Platform Developer Workshop Process for transferring data Transfer owned items endpoint: Moves all items from root (0) to another user. Requires admin privileges to transfer and may result in slow response depending on content size https://box.dev/en/reference/put-users-id-folders-id/ Collaboration endpoint: Uses the collaboration APIs to change ownership of a folder or file. Quick response but cannot be used with the root folder (0). The steps in the process to transfer files from an app user to a service account are: § Making call as the app user: Add the service account as a co-owner of the folder / file. § Making call as the service account: Fetch collaboration ID from the same file / folder as above. § Making call as the service account: Remove the app user as a collaborator. https://box.dev/en/reference/post-collaborations/
61. 61 Box Platform Developer Workshop Metadata
62. 62 Box Platform Developer Workshop Metadata Capabilities
63. 63 Box Platform Developer Workshop Metadata Capabilities and Functions § Metadata Templates: Enforce standard metadata required on a given file / folder when it is applied. § Metadata Cascade Policies: Uses a given metadata template to cascade the same template down to all files and folders below the indicated folder. § Apply Metadata: Endpoint for directly applying a metadata object to a file or folder. Metadata templates and cascade policies are not required to apply raw metadata. Metadata is stored as a JSON object.
64. 64 Box Platform Developer Workshop Metadata Driven Workflows
65. 65 Box Platform Developer Workshop Metadata Workflows • Available APIs: The metadata template and metadata data endpoints can allow you to apply metadata to any folder or file. • Configuration data: Workflows may be obtained by storing configuration or status information on a file or folder (i.e. a mortgage app may have up to 75 steps to an application that may need to be tracked).
66. 66 Box Platform Developer Workshop UI Tools and Services
67. 67 Box Platform Developer Workshop Box Embed Box View Box Elements Available UI and Embeddable Tools
68. 68 Box Platform Developer Workshop Box View § HTML5 based component to embed the native Box file preview capabilities. § Responsive design to work across different devices and environments. § Uses a separate application type on the developer console, App Token Auth § App Token Auth only allows access to the following API functions: Upload File, Download File, Delete File, and Get Embed Link. Embedding preview capabilities for Box files in your own site
71. 71 Box Platform Developer Workshop Box Embed § HTML5 based component to embed the entire box.com site, via an iframe, directly into your site or service. § Limited responsive capabilities with the iframe. § Uses a shared link for embedding content. Embed the entire box.com site into your own site or service
72. 72 Box Platform Developer Workshop Box Elements § UI components built with React Native (JavaScript library). § Authentication and token agnostic: Works with JWT and OAuth flows. § User type agnostic: Works with app, managed, and external user types. Embed and customize common functionality of box.com in your own site.
73. 73 Box Platform Developer Workshop Content Explorer Navigate Box files and folders within your app. Content Picker Select Box files and folders within your app Content Preview View docs, images, videos, 3D files, and more within your app Content Uploader Drag and drop files from a device into your app / Box. Open With Load Box content using G Suite, Adobe Sign, and more Sidebar See file attributes, statistics, and metadata.
74. 74 Best Practices for Application Development with Box CORS (Cross Origin Resource Sharing) Allows a web app running at one origin to access resources from another origin by using additional HTTP headers. https:/ /www.w3.org/TR/cors/ Enabling Box Elements API Communication
75. OPTIONS /cors HTTP/1.1 Origin: http://mysite.com Access-Control-Request-Method: POST Access-Control-Request-Headers: Authorization Host: api.service.com Accept-Language: en-US Connection: keep-alive User-Agent: Mozilla/5.0... Example CORS Preflight Request
76. Access-Control-Allow-Origin: http://mysite.com Access-Control-Allow-Methods: GET, POST, OPTIONS Access-Control-Allow-Headers: Authorization, Content-Type Content-Type: text/html; charset=utf-8 Example CORS Preflight Response
77. 77 Box Platform Developer Workshop Audience Exercise Understanding token management and account maintenance
78. 78 Box Platform Developer Workshop Audience Exercise Token Management and Account Maintenance / Architecture Exercise: Open the second architecture exercise envelope on your table. You have example scenarios listed off. As a team choose one and map out how tokens should be managed and how to handle long term account maintenance. / Code Exercise: Open the second coding exercise envelope on your table. There are a number of scenario requirements listed to help understand the correct way of working with token management and account decommissioning.
79. 79 Box Platform Developer Workshop Audience Exercise Review Users and Folders / Architecture Exercises: § Review the use case that was provided. § Talk about how you would structure your token and user architectures. § Discuss any potential pitfalls or additional implementations with the architecture. § Participation Prizes!
80. 80 Box Platform Developer Workshop Reporting and Monitoring
81. 81 Box Platform Developer Workshop Available Mechanisms for Reporting and Logging § Admin Reports: Limited reports on API activity, shared links and collaborators, user activity, etc. Requires admin access. § Event APIs: Historical and realtime user and enterprise level event information on actions taken. § Webhooks: Push level notifications that are sent for any triggers that the app wishes to listen to.
82. 82 Box Platform Developer Workshop Admin Reports
83. 83 Box Platform Developer Workshop / Manually created through the app dashboard: https://app.box.com/developers/console / Cannot be adjusted programmatically / Produces webhook events for all actions in an app and cannot be bound to a file / folder. Admin Reports
84. 84 Box Platform Developer Workshop Events
85. 85 Box Platform Developer Workshop Types of Event Streams Users and Folders / Direct request to the event stream § Search for specific events within a given time period as a singular API request. § Search for enterprise or user events. / Long polling § Keep connection open listening for all events. § New events come in and processed, then the stream is restarted at the previous position.
86. 86 Box Platform Developer Workshop Webhooks V1
87. 87 Box Platform Developer Workshop / Manually created through the app dashboard: https://app.box.com/developers/console / Cannot be adjusted programmatically / Produces webhook events for all actions in an app and cannot be bound to a file / folder. Webhooks V1 Details
88. 88 Box Platform Developer Workshop Webhooks V2
89. 89 Box Platform Developer Workshop / Programmatically created and maintained through the Webhooks APIs. / Create, Read, Update, and Delete endpoints. / Can be bound to a single file or folder. Webhooks V2 Details
90. 90 Box Platform Developer Workshop Skills
91. 91 Box Platform Developer Workshop Custom Skills § Allows for the enhancement of file metadata automatically through machine learning services. § Provides multiple card types for displaying data (timeline, transcript, keyword). § Uses tightly scoped read / write downscoped tokens.
92. 92 Box Platform Developer Workshop Example Skills Metadata Enhancement (Audio Data)
93. 93 Box Platform Developer Workshop Middleware File Upload Machine Learning The machine learning system will take in the contents of a Box file, run analysis of the data, and respond with the enhanced metadata to the middleware layer. The middleware layer works as an intermediary between the Box file and ML system. It sends the file info the the ML system and updates the Box file metadata with its response. The skills process is triggered when a new or updated file is uploaded to Box. An event is sent to a specified endpoint with file access information. Skills Workflow Event Metadata Execute Callback
94. 94 Box Platform Developer Workshop { "type": "skill_invocation", "skill": { ... }, "token": { "write": { ... }, "read": { ... } }, "status": { ... }, "id": "fd1d2e53-35f5-41fb-9c25-4ba326daf2f9_341016304", "enterprise": { ... }, "source": { ... }, "event": { ... }, "parameters": { ... } } Skills Event Payload
95. 95 Box Platform Developer Workshop Connecting Box to External Services
96. 96 Box Platform Developer Workshop Existing Connectors
97. 97 Box Platform Developer Workshop Popular Service Connectors for Box + Platform § Okta: SAML connector for Box to use Okta as your identity provider for Box core (https://saml-doc.okta.com/SAML_Docs/How-to-Configure-SAML-2.0-for- Box.net.html). No direct integration within Box Platform applications. § Salesforce: SDK for connecting Box to Salesforce (https://github.com/box/box- salesforce-sdk). Has generic getter / setter methods for any non-supported direct API requests to Salesforce. § Additional: All additional connectors are listed on https://developer.box.com/docs/api-connectors
98. 98 Box Platform Developer Workshop Connecting Identity Systems
99. 99 Box Platform Developer Workshop Authentication Services, specifications, or processes that are used to identify a user or an application. Authorization Processes that are used to grant an application permission to make requests on behalf of the user or application. Authentication versus authorization
100. 100 Box Platform Developer Workshop OAuth 2 OAuth 2 is the open authorization system that may be used to make authenticated requests to the API service. JWT JSON Web Tokens provides a mechanism for including an existing identify system to bypass the OAuth 3rd leg. Components of Box Application Auth
101. 101 Box Platform Developer Workshop Client Application OAuth Service / Resource Owner 1. Client app redirects user to log in / authorization 2. OAuth Service validates client app and responds with access token in query string 3. Client makes requests for privileged resources Which part of the flow does JWT target
102. 102 Box Platform Developer Workshop § X (Header): Token type and hashing algorithm § Y (Payload): User / verification content § Z (Signature): Header, payload, and secret XXXXXXXX.YYYYYYYY.ZZZZZZZZ What are the components of a JWT request?
103. 103 Box Platform Developer Workshop § alg: The hashing algorithm to be used (RSA / HMAC). § typ: The token type, always JWT. The components of a JWT header
104. 104 Box Platform Developer Workshop § iss (issuer): The person that issued the token. § sub (subject): The subject of the token. § aud (audience): Audience the token is intended for. § exp (expiration time): Expiration time of the token. § nbf (not before): Starting time token is available. § iat (issued at): When the token was issued. § jti (JWT ID): Unique identifier for the token. The components of a JWT payload
105. 105 Box Platform Developer Workshop § Encoded Data: Base64 encoded header + payload. § Secret: A private key. The components of a JWT Signature
106. const header = { alg: 'HMAC', typ: 'JWT' }; const payload = { sub: '4355676', exp: '1481160294', jti: '841112' }; HMACSHA256( base64UrlEncode(header) + '.' + base64UrlEncode(payload), secret); Sample JWT Request Segments
107. 107 Box Platform Developer Workshop Connecting Reporting Systems
108. 108 Box Platform Developer Workshop Using the Event and Webhook Systems Coverage levels for different event services in Box Event Service Event Types Applied To Webhooks v1 Limited user events Entire enterprise Webhooks v2 Enterprise and user events Folder or file Events API Enterprise and user events Entire enterprise Long Polling User events Entire enterprise Skills Events Upload only Folder or entire enterprise
109. 109 Box Platform Developer Workshop Recap
110. 110 Box Platform Developer Workshop What have we looked at today 1.Box platform use cases and setting up your first app 2.Users, folders, service accounts, and rate limits 3.Token and account management 4.Metadata functionality 5.UI Tools and services 6.Reporting and monitoring 7.Connecting Box to external systems (i.e. for identity or reporting services)
111. 111 Box Platform Developer Workshop Presentation https:/ /speakerdeck.com/jcleblanc/boxworks-developer-training Code Samples https:/ /github.com/jcleblanc/box-workshops https:/ /github.com/jcleblanc/box-examples Developer Site https:/ /developer.box.com https:/ /box.dev Community Forum https:/ /community.box.com/t5/Platform-and-Development-Forum/bd- p/DeveloperForum Resources
112. Thank you! Questions? Box Developer Advocacy Team Website: developer.box.com / box.dev Twitter: @BoxPlatform Email: devrel@box.com Simplify how you work