box.com api OAuth authentication

Question

Either I'm dense, or the docs assume I already know what they're telling me, but I need some clarification on doing authentication for a box.com app. I really don't understand whate's going on. As I read it:

1. the app running on the user's machine sends a request to Box, including all the little secrets (Which aren't all that secret any more if the user knows how to read the code).
2. The user is directed to the Box login page, which then sends the user to my server (with no page specified) attaching an authentication code.
3. The app somehow magically gets that code back from my server and sends a request to Box for the access token.
4. Box sends the access token to my server?
5. The app again magically gets the access token from my server and sends its APT requests.

Obviously I got lost somewhere.

And, why do I have to have a server involved in the process? The article on making a JavaScript app refers to a direct request for a token. Is there documentation on that somewhere?

Answer 1

1. You register your application on Box
2. After registration you receive clientId and clientSecret once on Box website
3. You hardcode your credentials somewhere in your application
4. First time your application needs to access Box API it should redirect user to https://www.box.com/api/oauth2/authorize, specifying your clientId, clientSecret and redirectURI as parameters. About redirectURI see below.
5. The box.com website opens. User enters his own credentials in the web form on box.com
6. User allows your application to access his files via API on the box.com website
7. Box redirects user back to you application using redirectURI specified before. One of the parameters to this request is "code". This is a very short-lived (30 seconds) access code that is only aligable for obtaining real access token.
8. During next 30 seconds your application should make another call to Box API to next URL: https://www.box.com/api/oauth2/token, specifying the previously obtained code. If everything was correct, your application receives an access_token, a refresh_token and "expires" values.
9. Now your application can make requests to Box API, specifying access_token every time
10. access_token expires in number of seconds, specified in "expires" field. It should be about 3600 seconds or 1 hour. Each time your application sees that access_token has expired, it should make another request to Box with the refresh_token and obtain a fresh access_token for another 1 hour.
11. refresh_token itself expires in 14 days

Note: if you develop a desktop application, then you should open browser for user on the step 4, redirectURI should be something like http://127.0.0.1:8080/Callback and you should run a small webserver just to catch the redirect with the code as in step 7.

Answer 2

Box requires that you specify a redirect_uri in your application's profile, and it must be an HTTPS URL.

As a result, it is not possible to use box with what google's oauth2 documentation calls "Client Side" or "Installed" applications, only "Web Server Applications" are allowed. Web Server applications do not have the secret leaking problem, because only the server knows the secret. You can pass the access token from your server to javascript on the client after the oauth transaction is complete, if you want the client to make api requests directly.