Skip to content

Commit c7d50d5

Browse files
box-sdk-buildbox-sdk-build
authored
feat: Add generated SDK (box/box-codegen#838) (#1438)
1 parent 2551e5a commit c7d50d5

File tree

2,127 files changed

+236053
-53512
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

2,127 files changed

+236053
-53512
lines changed

‎.codegen.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
{ "engineHash": "6674fe3", "specHash": "1ed059a", "version": "0.1.0" }

‎docs/sdkgen/Authentication.md‎

Lines changed: 365 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,365 @@
1+
# Authentication
2+
3+
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
4+
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
5+
6+
- [Authentication](#authentication)
7+
- [Authentication methods](#authentication-methods)
8+
- [Developer Token](#developer-token)
9+
- [JWT Auth](#jwt-auth)
10+
- [Authenticate Enterprise](#authenticate-enterprise)
11+
- [Authenticate user](#authenticate-user)
12+
- [Client Credentials Grant](#client-credentials-grant)
13+
- [Obtaining Service Account token](#obtaining-service-account-token)
14+
- [Obtaining User token](#obtaining-user-token)
15+
- [Switching between Service Account and User](#switching-between-service-account-and-user)
16+
- [OAuth 2.0 Auth](#oauth-20-auth)
17+
- [Authentication with OAuth2](#authentication-with-oauth2)
18+
- [Injecting existing token into BoxOAuth](#injecting-existing-token-into-boxoauth)
19+
- [Retrieve current access token](#retrieve-current-access-token)
20+
- [Refresh access token](#refresh-access-token)
21+
- [Revoke token](#revoke-token)
22+
- [Downscope token](#downscope-token)
23+
- [Token storage](#token-storage)
24+
- [In-memory token storage](#in-memory-token-storage)
25+
- [Custom storage](#custom-storage)
26+
27+
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
28+
29+
# Authentication methods
30+
31+
## Developer Token
32+
33+
The fastest way to get started using the API is with developer token. A
34+
developer token is simply a short-lived access token that cannot be refreshed
35+
and can only be used with your own account. Therefore, they're only useful for
36+
testing an app and aren't suitable for production. You can obtain a developer
37+
token from your application's [developer console][dev_console] page.
38+
39+
To create a `BoxClient` with a developer token, construct an `BoxDeveloperTokenAuth`
40+
object with the `token` set to the developer token and construct the client with that.
41+
42+
<!-- sample x_auth init_with_dev_token -->
43+
44+
```java
45+
BoxDeveloperTokenAuth auth = new BoxDeveloperTokenAuth("YOUR-DEVELOPER-TOKEN");
46+
BoxClient client = new BoxClient(auth);
47+
```
48+
49+
[dev_console]: https://app.box.com/developers/console
50+
51+
## JWT Auth
52+
53+
Before using JWT Auth make sure you set up correctly your Box platform app.
54+
The guide with all required steps can be found here: [Setup with JWT][jwt_guide]
55+
56+
### Authenticate Enterprise
57+
58+
JWT auth allows your application to authenticate itself with the Box API
59+
for a given enterprise. By default, your application has a [Service Account][service_account]
60+
that represents it and can perform API calls. The Service Account is separate
61+
from the Box accounts of the application developer and the enterprise admin of
62+
any enterprise that has authorized the app — files stored in that account are
63+
not accessible in any other account by default, and vice versa.
64+
65+
If you generated your public and private keys automatically through the
66+
[Box Developer Console][dev_console], you can use the JSON file created there
67+
to configure your SDK instance and create a client to make calls as the
68+
Service Account. Call one of static `BoxJwtAuth` method:
69+
`JWTConfig.fromConfigFile("PATH_TO_CONFIG_FILE")` and pass JSON file local path
70+
or `JWTConfig.fromConfigJsonString(CONFIG_JSON_STRING)` and pass JSON config file content as string.
71+
72+
```java
73+
JWTConfig config = JWTConfig.fromConfigFile("src/example/config/config.json");
74+
BoxJWTAuth auth = new BoxJWTAuth(config);
75+
BoxClient client = new BoxClient(auth);
76+
```
77+
78+
Otherwise, you'll need to provide the necessary configuration fields directly to the `JWTConfig` constructor:
79+
80+
```java
81+
JWTConfig config = new JWTConfig.Builder("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET", "JWT_KEY_ID", "PRIVATE_KEY", "PRIVATE_KEY_PASSWORD")
82+
.enterpriseId("123456")
83+
.build();
84+
BoxJWTAuth auth = new BoxJWTAuth(config);
85+
BoxClient client = new BoxClient(auth);
86+
```
87+
88+
### Authenticate user
89+
90+
App auth applications also often have associated [App Users][app_user], which are
91+
created and managed directly by the application — they do not have normal login credentials,
92+
and can only be accessed through the Box API by the application that created them.
93+
You may authenticate as the Service Account to provision and manage users, or as an individual app user to
94+
make calls as that user. See the [API documentation](https://developer.box.com/)
95+
for detailed instructions on how to use app auth.
96+
97+
Clients for making calls as an App User can be created with the same JSON JWT config file generated through the
98+
[Box Developer Console][dev_console]. Calling `jwtAuth.withUserSubject('USER_ID')` method will return a new auth object,
99+
which is authenticated as the user with provided id, leaving the original object unchanged.
100+
101+
```java
102+
JWTConfig config = JWTConfig.fromConfigFile("src/example/config/config.json");
103+
BoxJWTAuth auth = new BoxJWTAuth(config);
104+
BoxJWTAuth userAuth = auth.withUserSubject("USER_ID");
105+
BoxClient userClient = new BoxClient(userAuth);
106+
```
107+
108+
Alternatively, clients for making calls as an App User can be created with the same `JWTConfig`
109+
constructor as in the above examples, similarly to creating a Service Account client. Simply pass the
110+
`userId` instead of `enterpriseId` when constructing the auth config instance:
111+
112+
```java
113+
JWTConfig config = new JWTConfig.Builder("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET", "JWT_KEY_ID", "PRIVATE_KEY", "PRIVATE_KEY_PASSWORD")
114+
.userId("123456")
115+
.build();
116+
BoxJWTAuth auth = new BoxJWTAuth(config);
117+
BoxClient client = new BoxClient(auth);
118+
```
119+
120+
[jwt_guide]: https://developer.box.com/guides/authentication/jwt/jwt-setup/
121+
[service_account]: https://developer.box.com/guides/getting-started/user-types/service-account/
122+
[app_user]: https://developer.box.com/guides/getting-started/user-types/app-users/
123+
124+
## Client Credentials Grant
125+
126+
Before using Client Credentials Grant Auth make sure you set up correctly your Box platform app.
127+
The guide with all required steps can be found here: [Setup with Client Credentials Grant][ccg_guide]
128+
129+
Client Credentials Grant Auth method allows you to obtain an access token by having client credentials
130+
and secret with enterprise or user ID, which allows you to work using service or user account.
131+
132+
You can use `CCGAuth` to initialize a client object the same way as for other authentication types:
133+
134+
```java
135+
CCGConfig config = new CCGConfig.Builder("YOUR_CLIENT", "YOUR_CLIENT_SECRET")
136+
.userId("USER_ID")
137+
.build();
138+
BoxCCGAuth auth = new BoxCCGAuth(config);
139+
BoxClient client = new BoxClient(auth);
140+
141+
UserFull user = client.users.getUserMe();
142+
System.out.println(user.getName());
143+
```
144+
145+
Obtained token is valid for specified amount of time, it will be refreshed automatically by default.
146+
147+
### Obtaining Service Account token
148+
149+
The [Service Account](https://developer.box.com/guides/getting-started/user-types/service-account//)
150+
is separate from the Box accounts of the application developer and the
151+
enterprise admin of any enterprise that has authorized the app — files stored in that account
152+
are not accessible in any other account by default, and vice versa.
153+
To obtain service account you will have to provide enterprise ID with client id and secret:
154+
155+
```java
156+
CCGConfig config = new CCGConfig.Builder("YOUR_CLIENT", "YOUR_CLIENT_SECRET")
157+
.enterpriseId("ENTERPRISE_ID")
158+
.build();
159+
BoxCCGAuth auth = new BoxCCGAuth(config);
160+
BoxClient client = new BoxClient(auth);
161+
```
162+
163+
### Obtaining User token
164+
165+
In order to enable obtaining user token you have to go to your application configuration that can be found
166+
[here][dev_console]. In `Configuration` tab, in section `Advanced Features`
167+
select `Generate user access tokens`. Do not forget to re-authorize application if it was already authorized.
168+
169+
To obtain user account you will have to provide user ID with client id and secret.
170+
171+
```java
172+
CCGConfig config = new CCGConfig.Builder("YOUR_CLIENT", "YOUR_CLIENT_SECRET")
173+
.userId("USER_ID")
174+
.build();
175+
BoxCCGAuth auth = new BoxCCGAuth(config);
176+
BoxClient client = new BoxClient(auth);
177+
```
178+
179+
### Switching between Service Account and User
180+
181+
You can easily switch to be authenticated as a Service Account or as a User.
182+
To create a new auth object authenticated as Service Account you can call:
183+
184+
```java
185+
BoxCCGAuth enterpriseAuth = auth.withEnterpriseSubject("ENTERPRISE_ID");
186+
BoxClient enterpriseClient = new BoxClient(enterpriseAuth);
187+
```
188+
189+
To authenticate with user subject call:
190+
191+
```java
192+
BoxCCGAuth userAuth = auth.withUserSubject("USER_ID");
193+
BoxClient userClient = new BoxClient(userAuth);
194+
```
195+
196+
The new token will be automatically fetched with a next API call.
197+
198+
[ccg_guide]: https://developer.box.com/guides/authentication/client-credentials/client-credentials-setup/
199+
200+
## OAuth 2.0 Auth
201+
202+
### Authentication with OAuth2
203+
204+
If your application needs to integrate with existing Box users who will provide
205+
their login credentials to grant your application access to their account, you
206+
will need to go through the standard OAuth2 login flow. A detailed guide for
207+
this process is available in the
208+
[Authentication with OAuth API documentation](https://developer.box.com/en/guides/authentication/oauth2/).
209+
210+
Using an auth code is the most common way of authenticating with the Box API for
211+
existing Box users, to integrate with their accounts.
212+
Your application must provide a way for the user to login to Box (usually with a
213+
browser or web view) in order to obtain an auth code.
214+
215+
<!-- sample get_authorize -->
216+
217+
```java
218+
BoxOAuth oauth = new OAuthConfig("CLIENT_ID", "CLIENT_SECRET");
219+
String authorizationUrl = auoauthth.getAuthorizeUrl();
220+
```
221+
222+
After a user logs in and grants your application access to their Box account,
223+
they will be redirected to your application's `redirect_uri` which will contain
224+
an auth code. This auth code can then be used along with your client ID and
225+
client secret to establish an API connection.
226+
You need to provide the auth code to the SDK to obtain an access token.
227+
Calling `oauth.getTokensAuthorizationCodeGrant('code')` will exchange the auth code for an access token
228+
and save it in the `BoxOAuth` token storage. The SDK will automatically refresh the token when needed.
229+
All you need to do is create a client object with the `BoxOAuth` object and start making API calls.
230+
231+
<!-- sample post_oauth2_token --->
232+
233+
```java
234+
auth.getTokensAuthorizationCodeGrant("AUTHORIZATION_CODE");
235+
BoxClient client = new BoxClient(auth);
236+
```
237+
238+
### Injecting existing token into BoxOAuth
239+
240+
If you already have an access token and refresh token, you can inject them into the `BoxOAuth` token storage
241+
to avoid repeating the authentication process. This can be useful when you want to reuse the token
242+
between runs of your application.
243+
244+
```java
245+
AccessToken accessToken = new AccessToken.Builder()
246+
.accessToken("ACCESS_TOKEN")
247+
.refreshToken("REFRESH_TOKEN")
248+
.build();
249+
auth.getTokenStorage().store(accessToken);
250+
BoxClient client = new BoxClient(auth);
251+
```
252+
253+
Alternatively, you can create a custom implementation of `TokenStorage` interface and pass it to the `BoxOAuth` object.
254+
See the [Custom storage](#custom-storage) section for more information.
255+
256+
# Retrieve current access token
257+
258+
After initializing the authentication object, the SDK will be able to retrieve the access token.
259+
To retrieve the current access token you can use the following code:
260+
261+
<!-- sample post_oauth2_token -->
262+
263+
```java
264+
auth.retrieveToken();
265+
```
266+
267+
# Refresh access token
268+
269+
Access tokens are short-lived and need to be refreshed periodically. The SDK will automatically refresh the token when needed.
270+
If you want to manually refresh the token, you can use the following code:
271+
272+
<!-- sample post_oauth2_token refresh -->
273+
274+
```java
275+
auth.refreshToken();
276+
```
277+
278+
# Revoke token
279+
280+
Access tokens for a client can be revoked when needed. This call invalidates old token.
281+
For BoxCcgAuth and BoxJwtAuth you can still reuse the `auth` object to retrieve a new token.
282+
If you make any new call after revoking the token, a new token will be automatically retrieved.
283+
For BoxOAuth it would be necessary to manually go through the authentication process again.
284+
For BoxDeveloperTokenAuth, it is necessary to provide a DeveloperTokenConfig during initialization,
285+
containing the client ID and client secret.
286+
287+
To revoke current client's tokens in the storage use the following code:
288+
289+
<!-- sample post_oauth2_revoke -->
290+
291+
```java
292+
auth.revokeToken();
293+
// client's tokens have been revoked
294+
```
295+
296+
# Downscope token
297+
298+
You can exchange a client's access token for one with a lower scope, in order
299+
to restrict the permissions for a child client or to pass to a less secure
300+
location (e.g. a browser-based app).
301+
302+
A downscoped token does not include a refresh token.
303+
In such a scenario, to obtain a new downscoped token, refresh the original token
304+
and utilize the newly acquired token to obtain the downscoped token.
305+
306+
More information about downscoping tokens can be found [here](https://developer.box.com/guides/authentication/tokens/downscope/).
307+
If you want to learn more about available scopes please go [here](https://developer.box.com/guides/api-calls/permissions-and-errors/scopes/#scopes-for-downscoping).
308+
309+
For example to get a new token with only `item_preview` scope, restricted to a single file, suitable for the
310+
[Content Preview UI Element](https://developer.box.com/en/guides/embed/ui-elements/preview/) you can use the following code.
311+
You can also initialize `BoxDeveloperTokenAuth` with the retrieved access token and use it to create a new Client.
312+
313+
<!-- sample post_oauth2_token downscope_token -->
314+
315+
```java
316+
String resource = "https://api.box.com/2.0/files/123456789";
317+
List<String> scopes = List.of("item_preview");
318+
AccessToken downscopedToken = auth.downscopeToken(scopes, resource, null, null);
319+
BoxDeveloperTokenAuth downscopedAuth = new BoxDeveloperTokenAuth(downscopedToken.getAccessToken());
320+
BoxClient downscopedClient = new BoxClient(downscopedAuth);
321+
```
322+
323+
# Token storage
324+
325+
## In-memory token storage
326+
327+
By default, the SDK stores the access token in volatile memory. When rerunning your application,
328+
the access token won't be reused from the previous run; a new token has to be obtained again.
329+
To use in-memory token storage, you don't need to do anything more than
330+
create an Auth class using AuthConfig, for example, for OAuth:
331+
332+
```java
333+
OAuthConfig config = new OAuthConfig("CLIENT_ID", "CLIENT_SECRET");
334+
BoxOAuth auth = new BoxOAuth(config);
335+
```
336+
337+
## Custom storage
338+
339+
You can also provide a custom token storage class. All you need to do is create a class that implements `TokenStorage`
340+
interface and pass an instance of your class to the AuthConfig constructor.
341+
342+
```java
343+
TokenStorage customTokenStorage = new TokenStorage() {
344+
@Override
345+
public void store(AccessToken accessToken) {
346+
// Store the access token
347+
}
348+
349+
@Override
350+
public AccessToken get() {
351+
// Retrieve the access token
352+
return null;
353+
}
354+
355+
@Override
356+
public void clear() {
357+
// Clear the access token
358+
}
359+
};
360+
361+
OAuthConfig config = new OAuthConfig.Builder("CLIENT_ID", "CLIENT_SECRET")
362+
.tokenStorage(customTokenStorage)
363+
.build();
364+
BoxOAuth auth = new BoxOAuth(config);
365+
```

0 commit comments

Comments
 (0)