Box
Use the OAuth authentication standard to connect to Box. You can authenticate with a user account or with a service account. A service account is required to grant organization-wide access scopes to the provider. The provider facilitates these authentication flows as described below.
1 Authenticate with a User Account
Note: Set the AuthScheme to OAuth to authenticate with this method.
Log in to your Box developers dashboard and click Create New App. Select your app type (e.g., Custom App).
Select the Standard OAuth 2.0 (User Authentication) authentication method and click View Your App. (After creating your app, you can click Configuration from the main menu to access your app settings.)
Set the Redirect URI to http://localhost:33333 or a different port number of your choice. When you connect you will need to set the CallbackURL connection property to this exact URL.
The OAuthClientId and OAuthClientSecret are also displayed in the same page.
Select the scope of user permissions your app will request.
2 Authenticate with a Service Account
Note: Set the AuthScheme to OAuthJWT to authenticate with this method.
Service accounts have silent authentication, without user authentication in the browser. You can also use a service account to delegate enterprise-wide access scopes to the provider.
Follow the steps below to create an OAuth application and generate a private key. You will then authorize the service account.
Log in to your Box developers dashboard and click Create New App. Select your app type (e.g., Custom App).
Select the OAuth 2.0 with JWT (Server Authentication) authentication method and click View Your App. (After creating your app, you can click Configuration from the main menu to access your app settings.)
Select the application access level and the scope of user permissions your app will request. The enterprise access level enables you to work with existing users in your enterprise. The application-level setting restricts access to App-type users, users that have only API access.
Generate your RSA keypair. First you need to generate your private key. You can do this by running the following OpenSSL command : "openssl genrsa -aes128 -out private_key.pem 2048" (you can install and use the Cygwin package to run the OpenSSL RSA keypair if you are using Windows).
Generate your public key by running the following OpenSSL command: "openssl rsa -pubout -in private_key.pem -out public_key.pem". Copy the contents of the generated public_key.pem file and then add it by using the Add and Manage Public Keys option in your app settings.
6. Authorize the application in the enterprise admin console: Click Apps -> Custom Applications -> Authorize New App and enter the Client Id in your app settings.
Note: If you change the JWT access scopes, you will need to reauthorize the application in the enterprise admin console: Click Apps in the main menu and then select the ellipsis button next to your JWT application name. Select Reauthorize App in the menu.
After setting the following connection properties, you are ready to connect:
InitiateOAuth: Set to GETANDREFRESH.
OAuthClientId: Set to the Client Id in your app settings.
OAuthClientSecret: Set to the Client Secret in your app settings.
OAuthJWTCertType: Set to "PEMKEY_FILE".
OAuthJWTCert: Set to the path to the .pem file you generated.
OAuthJWTCertPassword: Set to the password of the .pem file.
OAuthJWTCertSubject: Set to "*" to pick the first certificate in the certificate store.
OAuthJWTSubjectType: Set to "enterprise" or "user" depending on the Application Access Value you selected in your app settings. The default value of this connection property is "enterprise".
OAuthJWTSubject: Set to your enterprise Id if your subject type is set to "enterprise" or your app user Id if your subject type is set to "user".
OAuthJWTPublicKeyId: Set to the Id of your public key in your app settings.
When you connect the provider completes the OAuth flow for a service account.
Creates and signs the JWT with the claim set required by the provider.
Exchanges the JWT for the access token.
Saves OAuth values in OAuthSettingsLocation to be persisted across connections.
Submits the JWT for a new access token when the token expires.
The following are the connection properties for Box. Not all properties are required. Enter only property values pertaining to your installation. Several properties will be automatically initialized with the appRules defaults.
Property
|
Description
|
Authentication | |
AuthScheme | The type of authentication to use when connecting to Box. |
ImpersonateUserMode | Specify the type of the user impersonation. It should be whether the User mode or the Admin mode. |
OAuthJWTPublicKeyId | The Id of the public key for JWT. |
OAuthJWTSubjectType | The SubType for the JWT authentication. |
Caching | |
CacheTolerance | The tolerance for stale data in the cache specified in seconds when using AutoCache . |
Firewall | |
FirewallPassword | A password used to authenticate to a proxy-based firewall. |
FirewallPort | The TCP port for a proxy-based firewall. |
FirewallServer | The name or IP address of a proxy-based firewall. |
FirewallType | The protocol used by a proxy-based firewall. |
FirewallUser | The user name to use to authenticate with a proxy-based firewall. |
JWTOAuth | |
OAuthJWTCert | The JWT Certificate store. |
OAuthJWTCertPassword | The password for the OAuth JWT certificate. |
OAuthJWTCertSubject | The subject of the OAuth JWT certificate. |
OAuthJWTCertType | The type of key store containing the JWT Certificate. |
OAuthJWTIssuer | The issuer of the Java Web Token. |
OAuthJWTSubject | The user subject for which the application is requesting delegated access. |
Logging | |
Logfile | A filepath which designates the name and location of the log file. |
LogModules | Core modules to be included in the log file. |
MaxLogFileCount | A string specifying the maximum file count of log files. When the limit is hit, a new log is created in the same folder with the date and time appended to the end and the oldest log file will be deleted. |
MaxLogFileSize | A string specifying the maximum size in bytes for a log file (for example, 10 MB). When the limit is hit, a new log is created in the same folder with the date and time appended to the end. |
Verbosity | The verbosity level that determines the amount of detail included in the log file. |
Misc | |
ConnectionLifeTime | The maximum lifetime of a connection in seconds. Once the time has elapsed, the connection object is disposed. |
ConnectionString | *** |
DirectoryRetrievalDepth | Depth level of folder to query Folders and Files tables. |
IncludeCustomFields | Set to true if metadata templates should be exposed as custom columns of the table Files. |
MaxRows | Limits the number of rows returned rows when no aggregation or group by is used in the query. This helps avoid performance issues at design time. |
Other | These hidden properties are used only in specific use cases. |
PoolIdleTimeout | The allowed idle time for a connection before it is closed. |
PoolMaxSize | The maximum connections in the pool. |
PoolMinSize | The minimum number of connections in the pool. |
PoolWaitTime | The max seconds to wait for an available connection. |
PseudoColumns | This property indicates whether or not to include pseudo columns as columns to the table. |
Readonly | You can use this property to enforce read-only access to Box from the provider. |
SSLServerCert | The certificate to be accepted from the server when connecting using TLS/SSL. |
SupportEnhancedSQL | This property enhances SQL functionality beyond what can be supported through the API directly, by enabling in-memory client-side processing. |
Timeout | The value in seconds until the timeout error is thrown, canceling the operation. |
UseConnectionPooling | This property enables connection pooling. |
OAuth | |
CallbackURL | The OAuth callback URL to return to when authenticating. This value must match the callback URL you specify in your app settings. |
InitiateOAuth | Set this property to initiate the process to obtain or refresh the OAuth access token when you connect. |
OAuthAccessToken | The access token for connecting using OAuth. |
OAuthClientId | The client ID assigned when you register your application with an OAuth authorization server. |
OAuthClientSecret | The client secret assigned when you register your application with an OAuth authorization server. |
OAuthExpiresIn | The lifetime in seconds of the OAuth AccessToken. |
OAuthRefreshToken | The OAuth refresh token for the corresponding OAuth access token. |
OAuthSettingsLocation | The location of the settings file where OAuth values are saved when InitiateOAuth is set to GETANDREFRESH or REFRESH. Alternatively, this can be held in memory by specifying a value starting with memory://. |
OAuthTokenTimestamp | The Unix epoch timestamp in milliseconds when the current Access Token was created. |
OAuthVerifier | The verifier code returned from the OAuth authorization URL. |
Proxy | |
ProxyAuthScheme | The authentication type to use to authenticate to the ProxyServer proxy. |
ProxyAutoDetect | This indicates whether to use the system proxy settings or not. This takes precedence over other proxy settings, so you'll need to set ProxyAutoDetect to FALSE in order use custom proxy settings. |
ProxyExceptions | A semicolon separated list of destination hostnames or IPs that are exempt from connecting through the ProxyServer . |
ProxyPassword | A password to be used to authenticate to the ProxyServer proxy. |
ProxyPort | The TCP port the ProxyServer proxy is running on. |
ProxyServer | The hostname or IP address of a proxy to route HTTP traffic through. |
ProxySSLType | The SSL type to use when connecting to the ProxyServer proxy. |
ProxyUser | A user name to be used to authenticate to the ProxyServer proxy. |
Last updated