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.

SignInParameters Class Builder

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().

/**
 * Encapsulates the parameters for calling {@link SingleAccountPublicClientApplication#signIn(SignInParameters)}.
 * Not a subclass of TokenParameters because it does not need fields such as Account, AccountRecord.
 *
 * Activity  -  Non-null {@link Activity} that is used as the parent activity for launching the {@link com.microsoft.identity.common.internal.providers.oauth2.AuthorizationActivity}.
 *
 * LoginHint -  Optional. If provided, will be used as the query parameter sent for authenticating the user,
 *              which will have the UPN pre-populated.
 *
 * Scopes    -  The non-null list of scopes to be consented to during sign in.
 *              MSAL always sends the scopes 'openid profile offline_access'.  Do not include any of these scopes in the scope parameter.
 *              The access token returned is for MS Graph and will allow you to query for additional information about the signed in account.
 *
 * Callback  -  {@link AuthenticationCallback} that is used to send the result back. The success result will be
 *              sent back via {@link AuthenticationCallback#onSuccess(IAuthenticationResult)}.
 *              Failure case will be sent back via AuthenticationCallback.onError(MsalException).
 *
 * Prompt    -  Optional. Indicates the type of user interaction that is required.
 *              If no argument is supplied the default behavior will be used (default is SELECT_ACCOUNT).
 */
final SignInParameters signInParameters = SignInParameters.builder()
        .withActivity(ACTIVITY)
        .withLoginHint(LOGINHINT)
        .withScope(SCOPE)
        .withScopes(SCOPES)
        .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();

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();

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

    /**
     * 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);