com.microsoft.identity.client

Class PublicClientApplication

java.lang.Object

com.microsoft.identity.client.PublicClientApplication

public final class PublicClientApplication
extends java.lang.Object

This is the entry point for developer to create public native applications and make API calls to acquire tokens.

Client ID: The clientID of your application is a unique identifier which can be obtained from the app registration portal.

Authority: A URL indicating a directory that MSAL can use to obtain tokens. In Azure AD it is of the form https://<[nstance]/[tenant], where [instance] is the directory host (e.g. https://login.microsoftonline.com) and [tenant] is an identifier within the directory itself (e.g. a domain associated to the tenant, such as contoso.onmicrosoft.com, or the GUID representing the TenantID property of the directory) For B2C, it is of the form https://[instance]/tfp/[tenant]/[policy] where instance and tenant are same as Azure AD, and [policy] is a string like signup

MSAL PublicClientApplication provides three constructors allowing the client id to be set either via AndroidManifest.xml metadata or using constructor parameters. Similarly, if developer chooses not to use the default authority https://login.microsoftonline.com, an alternate can also be configured using the manifest, constructor parameters, or in acquire token calls.

Redirect is auto-generated in the library in the format of msal://auth, and it cannot be overridden.

Developer MUST have BrowserTabActivity declared in their manifest, which must have the correct intent-filter configured. If the wrong scheme and host is provided, the sdk will fail the PublicClientApplication creation.

Expected format will be:

 <activity
     android:name="com.microsoft.identity.client.BrowserTabActivity">
     <intent-filter>
         <action android:name="android.intent.action.VIEW" />
         <category android:name="android.intent.category.DEFAULT" />
         <category android:name="android.intent.category.BROWSABLE" />
         <data android:scheme="msal<AppClientId>"
              android:host="auth" />
     </intent-filter>
 </activity>
 

Other Terminology:

Scopes:Permissions that the developers wants included in the access token received . Not all scopes are guaranteed to be included in the access token returned.

Login Hint: Usually an email, to pass to the service at the beginning of the interactive authentication flow.

Extra Scopes to Consent: Permissions you want the user to consent to in the same authentication flow, but won't be included in the returned access token.

Constructor Summary

Constructors

Constructor and Description
PublicClientApplication(Context context) PublicClientApplication(Context) will read the client id (which must be set) from manifest, and if authority is not set, default authority(https://login.microsoftonline.com/common) will be used.
PublicClientApplication(Context context, java.lang.String clientId) PublicClientApplication(Context, String) allows the client id to be passed instead of providing through the AndroidManifest metadata.
PublicClientApplication(Context context, java.lang.String clientId, java.lang.String authority) PublicClientApplication(Context, String, String) allows the client id and authority to be passed instead of providing them through metadata.

Method Summary

Modifier and Type	Method and Description
void	acquireToken(Activity activity, java.lang.String[] scopes, AuthenticationCallback callback) Acquire token interactively, will pop-up webUI.
void	acquireToken(Activity activity, java.lang.String[] scopes, java.lang.String loginHint, AuthenticationCallback callback) Acquire token interactively, will pop-up webUI.
void	acquireToken(Activity activity, java.lang.String[] scopes, java.lang.String loginHint, UiBehavior uiBehavior, java.lang.String extraQueryParameters, AuthenticationCallback callback) Acquire token interactively, will pop-up webUI.
void	acquireToken(Activity activity, java.lang.String[] scopes, java.lang.String loginHint, UiBehavior uiBehavior, java.lang.String extraQueryParams, java.lang.String[] extraScopesToConsent, java.lang.String authority, AuthenticationCallback callback) Acquire token interactively, will pop-up webUI.
void	acquireToken(Activity activity, java.lang.String[] scopes, User user, UiBehavior uiBehavior, java.lang.String extraQueryParameter, AuthenticationCallback callback) Acquire token interactively, will pop-up webUI.
void	acquireToken(Activity activity, java.lang.String[] scopes, User user, UiBehavior uiBehavior, java.lang.String extraQueryParams, java.lang.String[] extraScopesToConsent, java.lang.String authority, AuthenticationCallback callback) Acquire token interactively, will pop-up webUI.
void	acquireTokenSilentAsync(java.lang.String[] scopes, User user, AuthenticationCallback callback) Perform acquire token silent call.
void	acquireTokenSilentAsync(java.lang.String[] scopes, User user, java.lang.String authority, boolean forceRefresh, AuthenticationCallback callback) Perform acquire token silent call.
static java.lang.String	getSdkVersion()
User	getUser(java.lang.String userIdentifier) Returns the User that is matching the provided user identifier.
java.util.List<User>	getUsers() Returns the list of Users we have tokens in the cache.
void	handleInteractiveRequestRedirect(int requestCode, int resultCode, Intent data) MSAL requires the calling app to pass an Activity which MUST call this method to get the auth code passed back correctly.
void	remove(User user) Deletes all matching tokens (access & refresh tokens) for the User instance from the application cache.
void	setComponent(java.lang.String component) Specify the string identifier to identify the component that consumes MSAL.
void	setSliceParameters(java.lang.String sliceParameters) Custom query parameters which maybe sent to the STS for dogfood testing.
void	setValidateAuthority(boolean validateAuthority) By Default, authority validation is turned on.

Methods inherited from class java.lang.Object

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

Constructor Detail

PublicClientApplication

public PublicClientApplication(@NonNull
                               Context context)

PublicClientApplication(Context) will read the client id (which must be set) from manifest, and if authority is not set, default authority(https://login.microsoftonline.com/common) will be used.

Client id MUST be set in the manifest as the meta data(IllegalArgumentException will be thrown if client id is not provided), name for client id in the metadata is: "com.microsoft.identity.client.ClientId".

Redirect uri MUST be set in the manifest as the meta data(IllegalArgumentException will be thrown if client id is not provided), name for redirect uri in metadata is: "com.microsoft.identity.client.RedirectUri".

Authority can be set in the meta data, if not provided, the sdk will use the default authority https://login.microsoftonline.com/common.

Parameters:

context - Application's Context. The sdk requires the application context to be passed in PublicClientApplication. Cannot be null.

Note: The Context should be the application context instead of the running activity's context, which could potentially make the sdk hold a strong reference to the activity, thus preventing correct garbage collection and causing bugs.

PublicClientApplication

public PublicClientApplication(@NonNull
                               Context context,
                               @NonNull
                               java.lang.String clientId)

PublicClientApplication(Context, String) allows the client id to be passed instead of providing through the AndroidManifest metadata. If this constructor is called, the default authority https://login.microsoftonline.com/common will be used.

Parameters:

context - Application's Context. The sdk requires the application context to be passed in PublicClientApplication. Cannot be null.

Note: The Context should be the application context instead of the running activity's context, which could potentially make the sdk hold a strong reference to the activity, thus preventing correct garbage collection and causing bugs.

clientId - The application's client id.

PublicClientApplication

public PublicClientApplication(@NonNull
                               Context context,
                               @NonNull
                               java.lang.String clientId,
                               @NonNull
                               java.lang.String authority)

PublicClientApplication(Context, String, String) allows the client id and authority to be passed instead of providing them through metadata.

Parameters:

context - Application's Context. The sdk requires the application context to be passed in PublicClientApplication. Cannot be null.

Note: The Context should be the application context instead of an running activity's context, which could potentially make the sdk hold a strong reference to the activity, thus preventing correct garbage collection and causing bugs.

clientId - The application client id.

authority - The default authority to be used for the authority.

Method Detail

getSdkVersion

public static java.lang.String getSdkVersion()

Returns:

The current version for the sdk.

setValidateAuthority

public void setValidateAuthority(boolean validateAuthority)

By Default, authority validation is turned on. To turn on authority validation, set setValidateAuthority(boolean) to false.

Parameters:

validateAuthority - True if authority validation is on, false otherwise. By default, authority validation is turned on.

setComponent

public void setComponent(java.lang.String component)

Specify the string identifier to identify the component that consumes MSAL. This is intended for libraries that consume MSAL which are embedded in apps that might also be using MSAL as well. This allows logging, telemetry apps, or library developers to differentiate MSAL usage from the app to MSAL usage by component libraries.

Parameters:

component - The component identifier string passed into MSAL when creating the application object

setSliceParameters

public void setSliceParameters(java.lang.String sliceParameters)

Custom query parameters which maybe sent to the STS for dogfood testing. This parameter should not be set by developers as it may have adverse effect on the application.

Parameters:

sliceParameters - The custom query parameters(for dogfood testing) sent to token and authorize endpoint.

getUsers

public java.util.List<User> getUsers()
                              throws MsalClientException

Returns the list of Users we have tokens in the cache.

Returns:

Immutable List of User.

Throws:

MsalClientException - If failed to retrieve users from the cache.

getUser

public User getUser(java.lang.String userIdentifier)
             throws MsalClientException

Returns the User that is matching the provided user identifier.

Parameters:

userIdentifier - The unique identifier for a User across tenant.

Returns:

The User matching the provided user identifier.

Throws:

MsalClientException - If failed to retrieve users from the cache.

handleInteractiveRequestRedirect

public void handleInteractiveRequestRedirect(int requestCode,
                                             int resultCode,
                                             Intent data)

MSAL requires the calling app to pass an Activity which MUST call this method to get the auth code passed back correctly.

Parameters:

requestCode - The request code for interactive request.

resultCode - The result code for the request to get auth code.

data - Intent either contains the url with auth code as query string or the errors.

acquireToken

public void acquireToken(@NonNull
                         Activity activity,
                         @NonNull
                         java.lang.String[] scopes,
                         @NonNull
                         AuthenticationCallback callback)

Acquire token interactively, will pop-up webUI. Interactive flow will skip the cache lookup. Default value for UiBehavior is UiBehavior.SELECT_ACCOUNT.

Parameters:

activity - Non-null Activity that is used as the parent activity for launching the AuthenticationActivity. All apps doing an interactive request are required to call the handleInteractiveRequestRedirect(int, int, Intent) within the calling activity Activity#onActivityResult(int, int, Intent).

scopes - The non-null array of scopes to be requested for the access token. MSAL always sends the scopes 'openid profile offline_access'. Do not include any of these scopes in the scope parameter.

callback - The AuthenticationCallback to receive the result back. 1) If user cancels the flow by pressing the device back button, the result will be sent back via AuthenticationCallback.onCancel(). 2) If the sdk successfully receives the token back, result will be sent back via AuthenticationCallback.onSuccess(AuthenticationResult) 3) All the other errors will be sent back via AuthenticationCallback.onError(MsalException).

acquireToken

public void acquireToken(@NonNull
                         Activity activity,
                         @NonNull
                         java.lang.String[] scopes,
                         java.lang.String loginHint,
                         @NonNull
                         AuthenticationCallback callback)

Acquire token interactively, will pop-up webUI. Interactive flow will skip the cache lookup. Default value for UiBehavior is UiBehavior.SELECT_ACCOUNT.

Parameters:

activity - Non-null Activity that will be used as the parent activity for launching the AuthenticationActivity. All the apps doing interactive request are required to call the handleInteractiveRequestRedirect(int, int, Intent) within the calling activity Activity#onActivityResult(int, int, Intent).

scopes - The non-null array of scopes to be requested for the access token. MSAL always sends the scopes 'openid profile offline_access'. Do not include any of these scopes in the scope parameter.

loginHint - Optional. If provided, will be used as the query parameter sent for authenticating the user, which will have the UPN pre-populated.

callback - The Non-null AuthenticationCallback to receive the result back. 1) If user cancels the flow by pressing the device back button, the result will be sent back via AuthenticationCallback.onCancel(). 2) If the sdk successfully receives the token back, result will be sent back via AuthenticationCallback.onSuccess(AuthenticationResult) 3) All the other errors will be sent back via AuthenticationCallback.onError(MsalException).

acquireToken

public void acquireToken(@NonNull
                         Activity activity,
                         @NonNull
                         java.lang.String[] scopes,
                         java.lang.String loginHint,
                         UiBehavior uiBehavior,
                         java.lang.String extraQueryParameters,
                         @NonNull
                         AuthenticationCallback callback)

Acquire token interactively, will pop-up webUI. Interactive flow will skip the cache lookup. Default value for UiBehavior is UiBehavior.SELECT_ACCOUNT.

Parameters:

activity - Non-null Activity that will be used as the parent activity for launching the AuthenticationActivity. All the apps doing interactive request are required to call the handleInteractiveRequestRedirect(int, int, Intent) within the calling activity Activity#onActivityResult(int, int, Intent).

scopes - The non-null array of scopes to be requested for the access token. MSAL always sends the scopes 'openid profile offline_access'. Do not include any of these scopes in the scope parameter.

loginHint - Optional. If provided, will be used as the query parameter sent for authenticating the user, which will have the UPN pre-populated.

uiBehavior - The UiBehavior for prompting behavior. By default, the sdk use UiBehavior.SELECT_ACCOUNT.

extraQueryParameters - Optional. The extra query parameters sent to authorize endpoint.

callback - The Non-null AuthenticationCallback to receive the result back. 1) If user cancels the flow by pressing the device back button, the result will be sent back via AuthenticationCallback.onCancel(). 2) If the sdk successfully receives the token back, result will be sent back via AuthenticationCallback.onSuccess(AuthenticationResult) 3) All the other errors will be sent back via AuthenticationCallback.onError(MsalException).

acquireToken

public void acquireToken(@NonNull
                         Activity activity,
                         @NonNull
                         java.lang.String[] scopes,
                         User user,
                         UiBehavior uiBehavior,
                         java.lang.String extraQueryParameter,
                         @NonNull
                         AuthenticationCallback callback)

Acquire token interactively, will pop-up webUI. Interactive flow will skip the cache lookup. Default value for UiBehavior is UiBehavior.SELECT_ACCOUNT.

Parameters:

activity - Non-null Activity that will be used as the parent activity for launching the AuthenticationActivity. All the apps doing interactive request are required to call the handleInteractiveRequestRedirect(int, int, Intent) within the calling activity Activity#onActivityResult(int, int, Intent).

scopes - The non-null array of scopes to be requested for the access token. MSAL always sends the scopes 'openid profile offline_access'. Do not include any of these scopes in the scope parameter.

user - Optional. If provided, will be used to force the session continuation. If user tries to sign in with a different user, error will be returned.

uiBehavior - The UiBehavior for prompting behavior. By default, the sdk use UiBehavior.SELECT_ACCOUNT.

extraQueryParameter - Optional. The extra query parameter sent to authorize endpoint.

callback - The Non-null AuthenticationCallback to receive the result back. 1) If user cancels the flow by pressing the device back button, the result will be sent back via AuthenticationCallback.onCancel(). 2) If the sdk successfully receives the token back, result will be sent back via AuthenticationCallback.onSuccess(AuthenticationResult) 3) All the other errors will be sent back via AuthenticationCallback.onError(MsalException).

acquireToken

public void acquireToken(@NonNull
                         Activity activity,
                         @NonNull
                         java.lang.String[] scopes,
                         java.lang.String loginHint,
                         UiBehavior uiBehavior,
                         java.lang.String extraQueryParams,
                         java.lang.String[] extraScopesToConsent,
                         java.lang.String authority,
                         @NonNull
                         AuthenticationCallback callback)

Acquire token interactively, will pop-up webUI. Interactive flow will skip the cache lookup. Default value for UiBehavior is UiBehavior.SELECT_ACCOUNT.

Parameters:

activity - Non-null Activity that will be used as the parent activity for launching the AuthenticationActivity. All the apps doing interactive request are required to call the handleInteractiveRequestRedirect(int, int, Intent) within the calling activity Activity#onActivityResult(int, int, Intent).

scopes - The non-null array of scopes to be requested for the access token. MSAL always sends the scopes 'openid profile offline_access'. Do not include any of these scopes in the scope parameter.

loginHint - Optional. If provided, will be used as the query parameter sent for authenticating the user, which will have the UPN pre-populated.

uiBehavior - The UiBehavior for prompting behavior. By default, the sdk use UiBehavior.SELECT_ACCOUNT.

extraQueryParams - Optional. The extra query parameter sent to authorize endpoint.

extraScopesToConsent - Optional. The extra scopes to request consent.

authority - Optional. Can be passed to override the configured authority.

callback - The Non-null AuthenticationCallback to receive the result back. 1) If user cancels the flow by pressing the device back button, the result will be sent back via AuthenticationCallback.onCancel(). 2) If the sdk successfully receives the token back, result will be sent back via AuthenticationCallback.onSuccess(AuthenticationResult) 3) All the other errors will be sent back via AuthenticationCallback.onError(MsalException).

acquireToken

public void acquireToken(@NonNull
                         Activity activity,
                         @NonNull
                         java.lang.String[] scopes,
                         User user,
                         UiBehavior uiBehavior,
                         java.lang.String extraQueryParams,
                         java.lang.String[] extraScopesToConsent,
                         java.lang.String authority,
                         @NonNull
                         AuthenticationCallback callback)

Acquire token interactively, will pop-up webUI. Interactive flow will skip the cache lookup. Default value for UiBehavior is UiBehavior.SELECT_ACCOUNT.

Parameters:

activity - Non-null Activity that will be used as the parent activity for launching the AuthenticationActivity. All the apps doing interactive request are required to call the handleInteractiveRequestRedirect(int, int, Intent) within the calling activity Activity#onActivityResult(int, int, Intent).

scopes - The non-null array of scopes to be requested for the access token. MSAL always sends the scopes 'openid profile offline_access'. Do not include any of these scopes in the scope parameter.

user - Optional. If provided, will be used to force the session continuation. If user tries to sign in with a different user, error will be returned.

uiBehavior - The UiBehavior for prompting behavior. By default, the sdk use UiBehavior.SELECT_ACCOUNT.

extraQueryParams - Optional. The extra query parameter sent to authorize endpoint.

extraScopesToConsent - Optional. The extra scopes to request consent.

authority - Optional. Can be passed to override the configured authority.

callback - The Non-null AuthenticationCallback to receive the result back. 1) If user cancels the flow by pressing the device back button, the result will be sent back via AuthenticationCallback.onCancel(). 2) If the sdk successfully receives the token back, result will be sent back via AuthenticationCallback.onSuccess(AuthenticationResult) 3) All the other errors will be sent back via AuthenticationCallback.onError(MsalException).

acquireTokenSilentAsync

public void acquireTokenSilentAsync(@NonNull
                                    java.lang.String[] scopes,
                                    @NonNull
                                    User user,
                                    @NonNull
                                    AuthenticationCallback callback)

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.

Parameters:

scopes - The non-null array of scopes to be requested for the access token. MSAL always sends the scopes 'openid profile offline_access'. Do not include any of these scopes in the scope parameter.

user - User represents the user to silently request tokens.

callback - AuthenticationCallback that is used to send the result back. The success result will be sent back via AuthenticationCallback.onSuccess(AuthenticationResult). Failure case will be sent back via {

acquireTokenSilentAsync

public void acquireTokenSilentAsync(@NonNull
                                    java.lang.String[] scopes,
                                    @NonNull
                                    User user,
                                    java.lang.String authority,
                                    boolean forceRefresh,
                                    @NonNull
                                    AuthenticationCallback callback)

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.

Parameters:

scopes - The non-null array of scopes to be requested for the access token. MSAL always sends the scopes 'openid profile offline_access'. Do not include any of these scopes in the scope parameter.

user - User represents the user to silently request tokens.

authority - Optional. Can be passed to override the configured authority.

forceRefresh - True if the request is forced to refresh, false otherwise.

callback - AuthenticationCallback that is used to send the result back. The success result will be sent back via AuthenticationCallback.onSuccess(AuthenticationResult). Failure case will be sent back via {

remove

public void remove(User user)

Deletes all matching tokens (access & refresh tokens) for the User instance from the application cache.

Parameters:

user - User whose tokens should be deleted.