com.dropbox.core

Class DbxWebAuth.Request.Builder

java.lang.Object

com.dropbox.core.DbxWebAuth.Request.Builder

Enclosing class:

DbxWebAuth.Request

public static final class DbxWebAuth.Request.Builder
extends java.lang.Object

Builder for OAuth2 requests. Use this builder to configure the OAuth authorization flow.

Method Summary

Modifier and Type	Method and Description
DbxWebAuth.Request	build() Returns a new OAuth DbxWebAuth.Request that can be used in DbxWebAuth.DbxWebAuth(DbxRequestConfig,DbxAppInfo) to authorize a user.
DbxWebAuth.Request.Builder	withDisableSignup(java.lang.Boolean disableSignup) Whether or not to allow non-users to sign up for a Dropbox account via the authorization page.
DbxWebAuth.Request.Builder	withForceReapprove(java.lang.Boolean forceReapprove) Whether or not to force the user to approve the app again if they've already done so.
DbxWebAuth.Request.Builder	withIncludeGrantedScopes(IncludeGrantedScopes includeGrantedScopes)
DbxWebAuth.Request.Builder	withNoRedirect() Do not redirect the user after authorization has completed (default).
DbxWebAuth.Request.Builder	withRedirectUri(java.lang.String redirectUri, DbxSessionStore sessionStore) Where to redirect the user after authorization has completed.
DbxWebAuth.Request.Builder	withRequireRole(java.lang.String requireRole) Request the user authorize with the particular type of Dropbox account.
DbxWebAuth.Request.Builder	withScope(java.util.Collection<java.lang.String> scope)
DbxWebAuth.Request.Builder	withState(java.lang.String state) Up to 476 bytes of arbitrary data that will be passed back to your redirect URI.
DbxWebAuth.Request.Builder	withTokenAccessType(TokenAccessType tokenAccessType) Whether or not to include refresh token in DbxAuthFinish For TokenAccessType.ONLINE, auth result only contains short live token.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

withNoRedirect

public DbxWebAuth.Request.Builder withNoRedirect()

Do not redirect the user after authorization has completed (default).

After a user authorizes the app using the authorization URL, a code will be displayed that they must copy and paste into your app. If you want users to be redirected after authorization back to your app, use withRedirectUri(java.lang.String, com.dropbox.core.DbxSessionStore) instead. Websites should always provide a redirect URI.

Returns:

this builder

withRedirectUri

public DbxWebAuth.Request.Builder withRedirectUri(java.lang.String redirectUri,
                                                  DbxSessionStore sessionStore)

Where to redirect the user after authorization has completed.

This must be the exact URI registered in the App Console; even "localhost" must be listed if it is used for testing. All redirect URIs must be HTTPS except for localhost URIs. If the redirect URI is omitted, the code will be presented directly to the user and they will be invited to enter the information in your app.

The given session store will be used for storing the Cross-Site Request Forgery (CSRF) nonce generated during the authorization flow. To prevent CSRF attacks, DbxWebAuth appends a nonce to each authorization request. When the authorization flow is complete, the returned nonce is compared with the one in the store to ensure the response is valid. A session store must be specified if a redirect URI is set.

Parameters:

redirectUri - URI to redirect authorization response, never null.

sessionStore - Session store to use for storing CSRF nonces across requests, never null.

Returns:

this builder

Throws:

java.lang.NullPointerException - if either redirectUri or sessionStore is null

withState

public DbxWebAuth.Request.Builder withState(java.lang.String state)

Up to 476 bytes of arbitrary data that will be passed back to your redirect URI.

Note that DbxWebAuth will always automatically append a nonce to the state to protect against cross-site request forgery. This is true even if no state is provided.

State should only be provided if a redirect URI is provided as well, otherwise build() will throw an IllegalStateException.

Parameters:

state - additional state to pass back to the redirect URI, or null to pass back no additional state.

Returns:

this builder

Throws:

java.lang.IllegalArgumentException - if state is greater than 476 bytes

withRequireRole

public DbxWebAuth.Request.Builder withRequireRole(java.lang.String requireRole)

Request the user authorize with the particular type of Dropbox account. If specified, the user will be asked to authorize with a particular type of Dropbox account (e.g. a team account or personal account).

Parameters:

requireRole - which role should authorize this app, or null for any role.

Returns:

this builder

See Also:

DbxWebAuth.ROLE_WORK, DbxWebAuth.ROLE_PERSONAL

withForceReapprove

public DbxWebAuth.Request.Builder withForceReapprove(java.lang.Boolean forceReapprove)

Whether or not to force the user to approve the app again if they've already done so.

If false (default), a user who has already approved the application may be automatically redirected to the URI specified by withRedirectUri(java.lang.String, com.dropbox.core.DbxSessionStore). If true, the user will not be automatically redirected and will have to approve the app again.

Parameters:

forceReapprove - whether to force a user to re-approve this app, or null for default behavior

Returns:

this builder

withDisableSignup

public DbxWebAuth.Request.Builder withDisableSignup(java.lang.Boolean disableSignup)

Whether or not to allow non-users to sign up for a Dropbox account via the authorization page.

When true (default is false) users will not be able to sign up for a Dropbox account via the authorization page. Instead, the authorization page will show a link to install Dropbox (typically through a mobile app store). This is only intended for use when necessary for compliance with App Store policies.

Parameters:

disableSignup - whether or not to allow users to sign up in the authorization flow, or null for default behavior

Returns:

this builder

withTokenAccessType

public DbxWebAuth.Request.Builder withTokenAccessType(TokenAccessType tokenAccessType)

Whether or not to include refresh token in DbxAuthFinish For TokenAccessType.ONLINE, auth result only contains short live token. For TokenAccessType.OFFLINE, auth result includes both short live token and refresh token. For null, auth result is either legacy long live token or short live token only, depending on the app setting.

Parameters:

tokenAccessType - Whether or not to include refresh token in DbxAuthFinish

Returns:

this builder

withScope

public DbxWebAuth.Request.Builder withScope(java.util.Collection<java.lang.String> scope)

Parameters:

scope - Space-delimited scope string. Each scope corresponds to a group of API endpoints. To call one API endpoint you have to obtains the scope first otherwise you will get HTTP 401. Example: "account_info.read files.content.read"

withIncludeGrantedScopes

public DbxWebAuth.Request.Builder withIncludeGrantedScopes(IncludeGrantedScopes includeGrantedScopes)

Parameters:

includeGrantedScopes - This field is optional. If not presented, Dropbox will give you the scopes in withScope(Collection). Otherwise Dropbox server will return a token with all scopes user previously granted your app together with the new scopes.

build

public DbxWebAuth.Request build()

Returns a new OAuth DbxWebAuth.Request that can be used in DbxWebAuth.DbxWebAuth(DbxRequestConfig,DbxAppInfo) to authorize a user.

Returns:

new OAuth DbxWebAuth.Request configuration.

Throws:

java.lang.IllegalStateException - if withState(java.lang.String) was called with a non-null value, but no redirect URI was specified.