TokenParameters Subclasses Migration

In an effort to increase usability and consistency throughout the MSAL API, we're prioritizing method overrides that use TokenParameters Subclasses as the only parameter. We've deprecated other overrides that use individual parameters for SCOPE, PROMPT, account, and other fields. Below is a guide to using the TokenParameters Subclasses as well as the SignInParameters class for SignIn() in SingleAccountPublicAccountApplication.

Parameter Class Builder Examples

SignInParameters

The builder() class for the new SignInParameters allows user to add 5 parameters to be used for signIn flow: activity, loginHint, scope, prompt, and callback. Note that scopes can be supplied either individually as String objects through withScope(), or all at once as a List object through withScopes().

Non-null: Scopes, Activity, Callback

Nullable: Login Hint, Prompt

final SignInParameters signInParameters = SignInParameters.builder()
        .withScope(SCOPE)
        .withScopes(SCOPES)
        .withActivity(ACTIVITY)
        .withLoginHint(LOGINHINT)
        .withPrompt(PROMPT)
        .withCallback(new AuthenticationCallback() {
            @Override
            public void onCancel() {
                // Handle the signIn flow being cancelled
            }
            @Override
            public void onSuccess(IAuthenticationResult authenticationResult) {
                // Handle successful signIn flow with authenticationResult returned
            }
            @Override
            public void onError(MsalException exception) {
                // Handle an exception being thrown during the signIn flow
            }
        }).build();

AcquireTokenParameters

Non-null: Scopes, Activity, Callback

Nullable: Account, Authority, Authentication Scheme, Claims Request, Correlation Id, Fragment, Login Hint, Prompt, OtherScopesToAuthorize

final AcquireTokenParameters parameters = new AcquireTokenParameters.Builder()
        .withScopes(SCOPES)
        .startAuthorizationFromActivity(ACTIVITY)
        .forAccount(ACCOUNT)
        .fromAuthority(AUTHORITY)
        .withAuthenticationScheme(SCHEME)
        .withClaims(CLAIMS)
        .withCorrelationId(CORRELATION_ID)
        .withFragment(FRAGMENT)
        .withLoginHint(LOGINHINT)
        .withPrompt(PROMPT)
        .withOtherScopesToAuthorize(OTHER_SCOPES)
        .withCallback(new AuthenticationCallback() {
            @Override
            public void onCancel() {
                // Handle the acquireToken flow being cancelled
            }
            @Override
            public void onSuccess(IAuthenticationResult authenticationResult) {
                // Handle successful acquireToken flow with authenticationResult returned
            }
            @Override
            public void onError(MsalException exception) {
                // Handle an exception being thrown during the acquireToken flow
            }
        }).build();

AcquireTokenSilentParameters

Non-null: Scopes, Callback, Account

Nullable: Authority, Authentication Scheme, Claims Request, Correlation Id, Force Refresh

final AcquireTokenSilentParameters silentParameters = new AcquireTokenSilentParameters.Builder()
        .withScopes(SCOPES)
        .forAccount(ACCOUNT)
        .fromAuthority(AUTHORITY)
        .withAuthenticationScheme(SCHEME)
        .withClaims(CLAIMS)
        .withCorrelationId(CORRELATION_ID)
        .forceRefresh(false)
        .withCallback(new SilentAuthenticationCallback() {
            @Override
            public void onSuccess(IAuthenticationResult authenticationResult) {
                // Handle successful acquireTokenSilent flow with authenticationResult returned
            }

            @Override
            public void onError(MsalException exception) {
                // Handle an exception being thrown during the acquireTokenSilent flow
            }
        }).build();

Preferred Overrides in PublicClientApplication classes

Below are the preferred PublicClientApplication method overrides moving forward, notice that other overrides of the same methods have been marked as deprecated.

ISingleAccountPublicClientApplication

/**
 * Acquire token interactively, will pop-up webUI. Interactive flow will skip the cache lookup.
 * Default value for {@link Prompt} is {@link Prompt#SELECT_ACCOUNT}.
 * <p>
 * Convey parameters via the AcquireTokenParameters object
 *
 * @param acquireTokenParameters {@link AcquireTokenParameters} instance containing the necessary fields. Activity, scopes, and callback must be non-null.
 */
 void acquireToken(@NonNull final AcquireTokenParameters acquireTokenParameters);

/**
 * Perform acquire token silent call. If there is a valid access token in the cache, the sdk will return the access token; If
 * no valid access token exists, the sdk will try to find a refresh token and use the refresh token to get a new access token. If refresh token does not exist
 * or it fails the refresh, exception will be sent back via callback.
 *
 * @param acquireTokenSilentParameters the {@link AcquireTokenSilentParameters} containing the needed parameters for acquireTokenSilent flow. Scopes and authority must be non-null.
 */
IAuthenticationResult acquireTokenSilent(@NonNull final AcquireTokenSilentParameters acquireTokenSilentParameters) throws InterruptedException, MsalException;

/**
 * Perform acquire token silent call. If there is a valid access token in the cache, the sdk will return the access token; If
 * no valid access token exists, the sdk will try to find a refresh token and use the refresh token to get a new access token. If refresh token does not exist
 * or it fails the refresh, exception will be sent back via callback.
 *
 * @param acquireTokenSilentParameters the {@link AcquireTokenSilentParameters} containing the needed fields for acquireTokenSilent flow. Scopes, authority, and callback must be non-null.
 */
void acquireTokenSilentAsync(@NonNull final AcquireTokenSilentParameters acquireTokenSilentParameters);

/**
 * Allows a user to sign in to your application with one of their accounts. This method may only
 * be called once: once a user is signed in, they must first be signed out before another user
 * may sign in. If you wish to prompt the existing user for credentials use
 * {@link #signInAgain(SignInParameters)} or
 * {@link #acquireToken(AcquireTokenParameters)}.
 * <p>
 * Note: The authority used to make the sign in request will be either the MSAL default: https://login.microsoftonline.com/common
 * or the default authority specified by you in your configuration.
 *
 * @param signInParameters the {@link SignInParameters} containing the needed fields for signIn flow. Activity, scopes, and callback must be non-null. loginHint and prompt are nullable
 */
void signIn(@NonNull final SignInParameters signInParameters);

/**
 * Reauthorizes the current account according to the supplied scopes and prompt behavior.
 * <p>
 * Note: The authority used to make the sign in request will be either the MSAL default:
 * https://login.microsoftonline.com/common or the default authority specified by you in your
 * configuration. This flow requires activity, scopes, and callback. Prompt is optional.
 *
 * @param signInParameters the {@link SignInParameters} containing the needed fields for signIn flow. Activity, scopes, and callback must be non-null.
 */
void signInAgain(@NonNull final SignInParameters signInParameters);

IMultipleAccountPublicClientApplication

/**
 * Acquire token interactively, will pop-up webUI. Interactive flow will skip the cache lookup.
 *
 * @param acquireTokenParameters {@link AcquireTokenParameters} instance containing the necessary fields. Activity, scopes, and callback must be non-null.
 */
void acquireToken(@NonNull final AcquireTokenParameters acquireTokenParameters);

/**
 * Perform acquire token silent call. If there is a valid access token in the cache, the sdk will return the access token; If
 * no valid access token exists, the sdk will try to find a refresh token and use the refresh token to get a new access token. If refresh token does not exist
 * or it fails the refresh, exception will be sent back via callback.
 *
 * @param acquireTokenSilentParameters {@link AcquireTokenSilentParameters} instance containing the necessary fields. Scopes, account, and authority must be non-null.
 */
@WorkerThread
IAuthenticationResult acquireTokenSilent(@NonNull final AcquireTokenSilentParameters acquireTokenSilentParameters) throws MsalException, InterruptedException;

/**
 * Perform acquire token silent call. If there is a valid access token in the cache, the sdk will return the access token; If
 * no valid access token exists, the sdk will try to find a refresh token and use the refresh token to get a new access token. If refresh token does not exist
 * or it fails the refresh, exception will be sent back via callback.
 *
 * @param acquireTokenSilentParameters {@link AcquireTokenSilentParameters} instance containing the necessary fields. Scopes, account, authority, and callback must be non-null.
 */
void acquireTokenSilentAsync(@NonNull final AcquireTokenSilentParameters acquireTokenSilentParameters);

IPublicClientApplication

/**
 * Acquire token interactively, will pop-up webUI. Interactive flow will skip the cache lookup.
 * Default value for {@link Prompt} is {@link Prompt#SELECT_ACCOUNT}.
 * <p>
 * Convey parameters via the AcquireTokenParameters object
 *
 * @param acquireTokenParameters AcquireTokenParameters instance containing the necessary fields. Activity, scopes, and callback must be non-null.
 */
void acquireToken(@NonNull final AcquireTokenParameters acquireTokenParameters);