com.salesforce.androidsdk.auth

Class OAuth2

java.lang.Object

com.salesforce.androidsdk.auth.OAuth2

public class OAuth2
extends java.lang.Object

Helper methods for common OAuth2 requests. The typical OAuth2 flow is:

1. The authorization flow is started by presenting the web-based authorization screen to the user. This will prompt him/her to login and to authorize our application. The result will be a callback with an authorization code, or an error.
2. Use the authorization code from (a) with the token end point, to get access and refresh tokens, as well as other metadata.
3. Use the access token from (b) to call the identity service, which will let us find out the user's username.
4. Store the username, and refresh and access tokens somewhere safe (like the AccountManager).
5. If the access token becomes invalid, use the refresh token to get another access token.
6. If the refresh token becomes invalid, go back to the beginning.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	OAuth2.IdServiceResponse Helper class to parse an identity service response.
static class	OAuth2.LogoutReason
static class	OAuth2.OAuthFailedException Exception thrown when the refresh flow fails.
static class	OAuth2.TokenEndpointResponse Helper class to parse a token refresh response.
static class	OAuth2.TokenErrorResponse Helper class to parse a token refresh error response.

Field Summary

Fields

Modifier and Type	Field and Description
protected static java.lang.String	AUTHORIZATION
protected static java.lang.String	AUTHORIZATION_CODE
protected static java.lang.String	CLIENT_ID
protected static java.lang.String	CODE
protected static java.lang.String	CODE_CHALLENGE
protected static java.lang.String	CODE_VERIFIER
protected static java.lang.String	GRANT_TYPE
protected static java.lang.String	HYBRID_AUTH_CODE
protected static java.lang.String	OAUTH_AUTH_PATH
protected static java.lang.String	OAUTH_ENDPOINT_HEADLESS_FORGOT_PASSWORD Endpoint path for Salesforce Identity API headless forgot password flow
protected static java.lang.String	OAUTH_ENDPOINT_HEADLESS_INIT_PASSWORDLESS_LOGIN Endpoint path for Salesforce Identity API initialize headless, password-less login flow
protected static java.lang.String	OAUTH_ENDPOINT_HEADLESS_INIT_REGISTRATION Endpoint path for Salesforce Identity API initialize headless registration flow
protected static java.lang.String	OAUTH_TOKEN_PATH
protected static java.lang.String	REDIRECT_URI
protected static java.lang.String	RESPONSE_TYPE
protected static java.lang.String	SFDC_COMMUNITY_URL
static java.text.DateFormat	TIMESTAMP_FORMAT

Constructor Summary

Constructors

Constructor and Description
OAuth2()

Method Summary

Modifier and Type	Method and Description
static Request.Builder	addAuthorizationHeader(Request.Builder builder, java.lang.String authToken) Adds the authorization header to request builder.
static OAuth2.IdServiceResponse	callIdentityService(HttpAccess httpAccessor, java.lang.String identityServiceIdUrl, java.lang.String authToken) Calls the identity service to determine the username of the user and the mobile policy, given their identity service ID and an access token.
static java.lang.String	computeScopeParameter(java.lang.String[] scopes) Computes the scope parameter from an array of scopes.
static OAuth2.TokenEndpointResponse	exchangeCode(HttpAccess httpAccessor, java.net.URI loginServer, java.lang.String clientId, java.lang.String code, java.lang.String codeVerifier, java.lang.String callbackUrl) Exchange code for credentials.
static java.net.URI	getAuthorizationUrl(boolean useWebServerAuthentication, boolean useHybridAuthentication, java.net.URI loginServer, java.lang.String clientId, java.lang.String callbackUrl, java.lang.String[] scopes, java.lang.String displayType, java.lang.String codeChallenge, java.util.Map<java.lang.String,java.lang.String> addlParams) Builds the URL to the authorization web page for this login server.
static java.net.URI	getFrontdoorUrl(java.net.URI url, java.lang.String accessToken, java.lang.String instanceURL, java.util.Map<java.lang.String,java.lang.String> addlParams) Deprecated. Use RestRequest.getRequestForSingleAccess(String) instead
static java.lang.String	getOpenIDToken(java.lang.String loginServer, java.lang.String clientId, java.lang.String refreshToken) Fetches an OpenID token from the Salesforce backend.
static OAuth2.TokenEndpointResponse	refreshAuthToken(HttpAccess httpAccessor, java.net.URI loginServer, java.lang.String clientId, java.lang.String refreshToken, java.util.Map<java.lang.String,java.lang.String> addlParams) Gets a new auth token using the refresh token.
static void	revokeRefreshToken(HttpAccess httpAccessor, java.net.URI loginServer, java.lang.String refreshToken) Deprecated. Will be removed in 13.0. Use revokeRefreshToken(HttpAccess, URI, String, LogoutReason) instead.
static void	revokeRefreshToken(HttpAccess httpAccessor, java.net.URI loginServer, java.lang.String refreshToken, OAuth2.LogoutReason reason) Revokes the existing refresh token.
static OAuth2.TokenEndpointResponse	swapJWTForTokens(HttpAccess httpAccessor, java.net.URI loginServerUrl, java.lang.String jwt) Swaps a JWT for regular OAuth tokens.

Methods inherited from class java.lang.Object

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

Field Detail

CLIENT_ID

protected static final java.lang.String CLIENT_ID

See Also:

Constant Field Values

GRANT_TYPE

protected static final java.lang.String GRANT_TYPE

See Also:

Constant Field Values

RESPONSE_TYPE

protected static final java.lang.String RESPONSE_TYPE

See Also:

Constant Field Values

REDIRECT_URI

protected static final java.lang.String REDIRECT_URI

See Also:

Constant Field Values

AUTHORIZATION_CODE

protected static final java.lang.String AUTHORIZATION_CODE

See Also:

Constant Field Values

HYBRID_AUTH_CODE

protected static final java.lang.String HYBRID_AUTH_CODE

See Also:

Constant Field Values

CODE

protected static final java.lang.String CODE

See Also:

Constant Field Values

CODE_CHALLENGE

protected static final java.lang.String CODE_CHALLENGE

See Also:

Constant Field Values

CODE_VERIFIER

protected static final java.lang.String CODE_VERIFIER

See Also:

Constant Field Values

SFDC_COMMUNITY_URL

protected static final java.lang.String SFDC_COMMUNITY_URL

See Also:

Constant Field Values

AUTHORIZATION

protected static final java.lang.String AUTHORIZATION

See Also:

Constant Field Values

OAUTH_AUTH_PATH

protected static final java.lang.String OAUTH_AUTH_PATH

See Also:

Constant Field Values

OAUTH_ENDPOINT_HEADLESS_INIT_PASSWORDLESS_LOGIN

protected static java.lang.String OAUTH_ENDPOINT_HEADLESS_INIT_PASSWORDLESS_LOGIN

Endpoint path for Salesforce Identity API initialize headless, password-less login flow

OAUTH_ENDPOINT_HEADLESS_INIT_REGISTRATION

protected static java.lang.String OAUTH_ENDPOINT_HEADLESS_INIT_REGISTRATION

Endpoint path for Salesforce Identity API initialize headless registration flow

OAUTH_ENDPOINT_HEADLESS_FORGOT_PASSWORD

protected static java.lang.String OAUTH_ENDPOINT_HEADLESS_FORGOT_PASSWORD

Endpoint path for Salesforce Identity API headless forgot password flow

OAUTH_TOKEN_PATH

protected static final java.lang.String OAUTH_TOKEN_PATH

See Also:

Constant Field Values

TIMESTAMP_FORMAT

public static final java.text.DateFormat TIMESTAMP_FORMAT

Constructor Detail

OAuth2

public OAuth2()

Method Detail

getAuthorizationUrl

public static java.net.URI getAuthorizationUrl(boolean useWebServerAuthentication,
                                               boolean useHybridAuthentication,
                                               java.net.URI loginServer,
                                               java.lang.String clientId,
                                               java.lang.String callbackUrl,
                                               java.lang.String[] scopes,
                                               java.lang.String displayType,
                                               java.lang.String codeChallenge,
                                               java.util.Map<java.lang.String,java.lang.String> addlParams)

Builds the URL to the authorization web page for this login server. You need not provide the 'refresh_token' scope, as it is provided automatically.

Parameters:

useWebServerAuthentication - True to use web server flow, False to use user agent flow

useHybridAuthentication - True to use "hybrid" flow

loginServer - Base protocol and server to use (e.g. https://login.salesforce.com).

clientId - OAuth client ID.

callbackUrl - OAuth callback URL or redirect URL.

scopes - A list of OAuth scopes to request (e.g. {"visualforce", "api"}). If null, the default OAuth scope is provided.

displayType - OAuth display type. If null, the default of 'touch' is used.

codeChallenge - Code challenge to use when using web server flow

addlParams - Any additional parameters that may be added to the request.

Returns:

A URL to start the OAuth flow in a web browser/view.

See Also:

RemoteAccess OAuth Scopes

getFrontdoorUrl

@Deprecated
public static java.net.URI getFrontdoorUrl(java.net.URI url,
                                                       java.lang.String accessToken,
                                                       java.lang.String instanceURL,
                                                       java.util.Map<java.lang.String,java.lang.String> addlParams)

Deprecated. Use RestRequest.getRequestForSingleAccess(String) instead

Returns a 'frontdoor'ed URL Front door will authenticate client navigating to that URL using given access token

Parameters:

url - the URL to "frontdoor"

accessToken - access token to use as sid

instanceURL - instance url for the sid

addlParams - additional paramaters

Returns:

'frontdoor'ed URL (or the original url if access token or instance url are null)

computeScopeParameter

public static java.lang.String computeScopeParameter(java.lang.String[] scopes)

Computes the scope parameter from an array of scopes. Also adds the 'refresh_token' scope if it hasn't already been added.

Parameters:

scopes - Array of scopes.

Returns:

Scope parameter.

exchangeCode

public static OAuth2.TokenEndpointResponse exchangeCode(HttpAccess httpAccessor,
                                                        java.net.URI loginServer,
                                                        java.lang.String clientId,
                                                        java.lang.String code,
                                                        java.lang.String codeVerifier,
                                                        java.lang.String callbackUrl)
                                                 throws OAuth2.OAuthFailedException,
                                                        java.io.IOException

Exchange code for credentials.

Parameters:

httpAccessor - HTTPAccess instance.

loginServer - Login server.

clientId - Client ID.

code - Code returned from the IDP.

codeVerifier - Code verifier used to generate 'code_challenge'.

callbackUrl - Callback URL.

Returns:

Full set of credentials.

Throws:

OAuth2.OAuthFailedException - See OAuth2.OAuthFailedException.

java.io.IOException - See IOException.

refreshAuthToken

public static OAuth2.TokenEndpointResponse refreshAuthToken(HttpAccess httpAccessor,
                                                            java.net.URI loginServer,
                                                            java.lang.String clientId,
                                                            java.lang.String refreshToken,
                                                            java.util.Map<java.lang.String,java.lang.String> addlParams)
                                                     throws OAuth2.OAuthFailedException,
                                                            java.io.IOException

Gets a new auth token using the refresh token.

Parameters:

httpAccessor - HttpAccess instance.

loginServer - Login server.

clientId - Client ID.

refreshToken - Refresh token.

addlParams - Additional parameters.

Returns:

Token response.

Throws:

OAuth2.OAuthFailedException - See OAuth2.OAuthFailedException.

java.io.IOException - See IOException.

revokeRefreshToken

public static void revokeRefreshToken(HttpAccess httpAccessor,
                                      java.net.URI loginServer,
                                      java.lang.String refreshToken)

Deprecated. Will be removed in 13.0. Use revokeRefreshToken(HttpAccess, URI, String, LogoutReason) instead.

Revokes the existing refresh token.

Parameters:

httpAccessor - HttpAccess instance.

loginServer - Login server.

refreshToken - Refresh token.

revokeRefreshToken

public static void revokeRefreshToken(HttpAccess httpAccessor,
                                      java.net.URI loginServer,
                                      java.lang.String refreshToken,
                                      OAuth2.LogoutReason reason)

Revokes the existing refresh token.

Parameters:

httpAccessor - HttpAccess instance.

loginServer - Login server.

refreshToken - Refresh token.

reason - The reason the refresh token is being revoked.

swapJWTForTokens

public static OAuth2.TokenEndpointResponse swapJWTForTokens(HttpAccess httpAccessor,
                                                            java.net.URI loginServerUrl,
                                                            java.lang.String jwt)
                                                     throws java.io.IOException,
                                                            OAuth2.OAuthFailedException

Swaps a JWT for regular OAuth tokens. This is typically the first step after receiving a JWT from a link. In addition, this will also call the identity service to populate the username field.

Parameters:

httpAccessor - HttpAccess instance.

loginServerUrl - The server (e.g. https://login.salesforce.com) that the auth code was generated from.

jwt - JWT issued by the OAuth authorization flow.

Throws:

java.io.IOException - See IOException.

OAuth2.OAuthFailedException - See OAuth2.OAuthFailedException.

callIdentityService

public static final OAuth2.IdServiceResponse callIdentityService(HttpAccess httpAccessor,
                                                                 java.lang.String identityServiceIdUrl,
                                                                 java.lang.String authToken)
                                                          throws java.io.IOException

Calls the identity service to determine the username of the user and the mobile policy, given their identity service ID and an access token.

Parameters:

httpAccessor - HttpAccessor instance.

identityServiceIdUrl - Identity service URL.

authToken - Access token.

Returns:

IdServiceResponse instance.

Throws:

java.io.IOException - See IOException.

addAuthorizationHeader

public static final Request.Builder addAuthorizationHeader(Request.Builder builder,
                                                           java.lang.String authToken)

Adds the authorization header to request builder.

Parameters:

builder - Builder instance.

authToken - Access token.

getOpenIDToken

public static java.lang.String getOpenIDToken(java.lang.String loginServer,
                                              java.lang.String clientId,
                                              java.lang.String refreshToken)

Fetches an OpenID token from the Salesforce backend. This requires an OpenID token to be configured on the Salesforce connected app in the backend. It also requires the "openid" scope to be added on the client side through bootconfig and on the connected app.

Parameters:

loginServer - Login server.

clientId - Client ID.

refreshToken - Refresh token.

Returns:

OpenID token.