com.microsoft.aad.adal4j

Class AuthenticationContext

java.lang.Object

com.microsoft.aad.adal4j.AuthenticationContext

public class AuthenticationContext
extends Object

The main class representing the authority issuing tokens for resources. It provides several ways to request access token, namely via Authorization Code, Confidential Client and Client Certificate.

Constructor Summary

Constructors

Constructor and Description
AuthenticationContext(String authority, boolean validateAuthority, ExecutorService service) Constructor to create the context with the address of the authority.

Method Summary

Modifier and Type	Method and Description
Future<DeviceCode>	acquireDeviceCode(String clientId, String resource, AuthenticationCallback<DeviceCode> callback) Acquires a device code from the authority
Future<AuthenticationResult>	acquireToken(String resource, AsymmetricKeyCredential credential, AuthenticationCallback callback) Acquires security token from the authority.
Future<AuthenticationResult>	acquireToken(String resource, ClientAssertion clientAssertion, AuthenticationCallback callback) Acquires security token from the authority.
Future<AuthenticationResult>	acquireToken(String resource, ClientCredential credential, AuthenticationCallback callback) Acquires security token from the authority.
Future<AuthenticationResult>	acquireToken(String resource, String clientId, String username, String password, AuthenticationCallback callback) Acquires a security token from the authority using a username/password flow.
Future<AuthenticationResult>	acquireToken(String resource, UserAssertion userAssertion, AsymmetricKeyCredential credential, AuthenticationCallback callback) Acquires an access token from the authority on behalf of a user.
Future<AuthenticationResult>	acquireToken(String resource, UserAssertion userAssertion, ClientCredential credential, AuthenticationCallback callback) Acquires an access token from the authority on behalf of a user.
Future<AuthenticationResult>	acquireTokenByAuthorizationCode(String authorizationCode, String resource, String clientId, URI redirectUri, AuthenticationCallback callback) Acquires security token from the authority using an authorization code previously received.
Future<AuthenticationResult>	acquireTokenByAuthorizationCode(String authorizationCode, URI redirectUri, AsymmetricKeyCredential credential, AuthenticationCallback callback) Acquires security token from the authority using an authorization code previously received.
Future<AuthenticationResult>	acquireTokenByAuthorizationCode(String authorizationCode, URI redirectUri, AsymmetricKeyCredential credential, String resource, AuthenticationCallback callback) Acquires security token from the authority using an authorization code previously received.
Future<AuthenticationResult>	acquireTokenByAuthorizationCode(String authorizationCode, URI redirectUri, ClientAssertion clientAssertion, AuthenticationCallback callback) Acquires security token from the authority using an authorization code previously received.
Future<AuthenticationResult>	acquireTokenByAuthorizationCode(String authorizationCode, URI redirectUri, ClientAssertion clientAssertion, String resource, AuthenticationCallback callback) Acquires security token from the authority using an authorization code previously received.
Future<AuthenticationResult>	acquireTokenByAuthorizationCode(String authorizationCode, URI redirectUri, ClientCredential credential, AuthenticationCallback callback) Acquires security token from the authority using an authorization code previously received.
Future<AuthenticationResult>	acquireTokenByAuthorizationCode(String authorizationCode, URI redirectUri, ClientCredential credential, String resource, AuthenticationCallback callback) Acquires security token from the authority using an authorization code previously received.
Future<AuthenticationResult>	acquireTokenByDeviceCode(DeviceCode deviceCode, AuthenticationCallback callback) Acquires security token from the authority using an device code previously received.
Future<AuthenticationResult>	acquireTokenByRefreshToken(String refreshToken, AsymmetricKeyCredential credential, AuthenticationCallback callback) Acquires a security token from the authority using a Refresh Token previously received.
Future<AuthenticationResult>	acquireTokenByRefreshToken(String refreshToken, AsymmetricKeyCredential credential, String resource, AuthenticationCallback callback) Acquires a security token from the authority using a Refresh Token previously received.
Future<AuthenticationResult>	acquireTokenByRefreshToken(String refreshToken, ClientCredential credential, AuthenticationCallback callback) Acquires a security token from the authority using a Refresh Token previously received.
Future<AuthenticationResult>	acquireTokenByRefreshToken(String refreshToken, ClientCredential credential, String resource, AuthenticationCallback callback) Acquires a security token from the authority using a Refresh Token previously received.
Future<AuthenticationResult>	acquireTokenByRefreshToken(String refreshToken, String clientId, AuthenticationCallback callback) Acquires a security token from the authority using a Refresh Token previously received.
Future<AuthenticationResult>	acquireTokenByRefreshToken(String refreshToken, String clientId, ClientAssertion clientAssertion, AuthenticationCallback callback) Acquires a security token from the authority using a Refresh Token previously received.
Future<AuthenticationResult>	acquireTokenByRefreshToken(String refreshToken, String clientId, ClientAssertion clientAssertion, String resource, AuthenticationCallback callback) Acquires a security token from the authority using a Refresh Token previously received.
Future<AuthenticationResult>	acquireTokenByRefreshToken(String refreshToken, String clientId, String resource, AuthenticationCallback callback) Acquires a security token from the authority using a Refresh Token previously received.
String	getAuthority() Authority associated with the context instance
String	getCorrelationId() Returns the correlation id configured by the user.
Proxy	getProxy() Returns Proxy configuration
SSLSocketFactory	getSslSocketFactory() Returns SSLSocketFactory configuration object.
boolean	isLogPii() Returns logPii - boolean value, which determines whether Pii (personally identifiable information) will be logged in
void	setCorrelationId(String correlationId) Set optional correlation id to be used by the API.
void	setLogPii(boolean logPii) Set logPii - boolean value, which determines whether Pii (personally identifiable information) will be logged in
void	setProxy(Proxy proxy) Sets Proxy configuration to be used by the context for all network communication.
void	setSslSocketFactory(SSLSocketFactory sslSocketFactory) Sets SSLSocketFactory object to be used by the context.
boolean	shouldValidateAuthority() Returns validateAuthority boolean value passed as a constructor parameter.

Methods inherited from class java.lang.Object

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

Constructor Detail

AuthenticationContext

public AuthenticationContext(String authority,
                             boolean validateAuthority,
                             ExecutorService service)
                      throws MalformedURLException

Constructor to create the context with the address of the authority.

Parameters:

authority - URL of the authenticating authority

validateAuthority - flag to enable/disable authority validation.

service - ExecutorService to be used to execute the requests. Developer is responsible for maintaining the lifetime of the ExecutorService.

Throws:

MalformedURLException - thrown if URL is invalid

Method Detail

isLogPii

public boolean isLogPii()

Returns logPii - boolean value, which determines whether Pii (personally identifiable information) will be logged in

Returns:

boolean value of logPii

setLogPii

public void setLogPii(boolean logPii)

Set logPii - boolean value, which determines whether Pii (personally identifiable information) will be logged in

Parameters:

logPii - boolean value

getProxy

public Proxy getProxy()

Returns Proxy configuration

Returns:

Proxy Object

setProxy

public void setProxy(Proxy proxy)

Sets Proxy configuration to be used by the context for all network communication. Default is null and system defined properties if any, would be used.

Parameters:

proxy - Proxy configuration object

getSslSocketFactory

public SSLSocketFactory getSslSocketFactory()

Returns SSLSocketFactory configuration object.

Returns:

SSLSocketFactory object

setSslSocketFactory

public void setSslSocketFactory(SSLSocketFactory sslSocketFactory)

Sets SSLSocketFactory object to be used by the context.

Parameters:

sslSocketFactory - The SSL factory object to set

acquireToken

public Future<AuthenticationResult> acquireToken(String resource,
                                                 String clientId,
                                                 String username,
                                                 String password,
                                                 AuthenticationCallback callback)

Acquires a security token from the authority using a username/password flow.

Parameters:

clientId - Name or ID of the client requesting the token.

resource - Identifier of the target resource that is the recipient of the requested token.

username - Username of the managed or federated user.

password - Password of the managed or federated user. If null, integrated authentication will be used.

callback - optional callback object for non-blocking execution.

Returns:

A Future object representing the AuthenticationResult of the call. It contains Access Token, Refresh Token and the Access Token's expiration time.

acquireToken

public Future<AuthenticationResult> acquireToken(String resource,
                                                 ClientAssertion clientAssertion,
                                                 AuthenticationCallback callback)

Acquires security token from the authority.

Parameters:

resource - Identifier of the target resource that is the recipient of the requested token.

clientAssertion - The client assertion to use for client authentication.

callback - optional callback object for non-blocking execution.

Returns:

A Future object representing the AuthenticationResult of the call. It contains Access Token and the Access Token's expiration time. Refresh Token property will be null for this overload.

acquireToken

public Future<AuthenticationResult> acquireToken(String resource,
                                                 UserAssertion userAssertion,
                                                 ClientCredential credential,
                                                 AuthenticationCallback callback)

Acquires an access token from the authority on behalf of a user. It requires using a user token previously received.

Parameters:

resource - Identifier of the target resource that is the recipient of the requested token.

userAssertion - userAssertion to use as Authorization grant

credential - The client credential to use for token acquisition.

callback - optional callback object for non-blocking execution.

Returns:

A Future object representing the AuthenticationResult of the call. It contains Access Token and the Access Token's expiration time. Refresh Token property will be null for this overload.

Throws:

AuthenticationException - AuthenticationException

acquireToken

public Future<AuthenticationResult> acquireToken(String resource,
                                                 UserAssertion userAssertion,
                                                 AsymmetricKeyCredential credential,
                                                 AuthenticationCallback callback)

Acquires an access token from the authority on behalf of a user. It requires using a user token previously received. Uses certificate to authenticate client.

Parameters:

resource - Identifier of the target resource that is the recipient of the requested token.

userAssertion - userAssertion to use as Authorization grant

credential - The certificate based client credential to use for token acquisition.

callback - optional callback object for non-blocking execution.

Returns:

A Future object representing the AuthenticationResult of the call. It contains Access Token and the Access Token's expiration time. Refresh Token property will be null for this overload.

Throws:

AuthenticationException - AuthenticationException

acquireToken

public Future<AuthenticationResult> acquireToken(String resource,
                                                 ClientCredential credential,
                                                 AuthenticationCallback callback)

Acquires security token from the authority.

Parameters:

resource - Identifier of the target resource that is the recipient of the requested token.

credential - The client credential to use for token acquisition.

callback - optional callback object for non-blocking execution.

Returns:

A Future object representing the AuthenticationResult of the call. It contains Access Token and the Access Token's expiration time. Refresh Token property will be null for this overload.

acquireToken

public Future<AuthenticationResult> acquireToken(String resource,
                                                 AsymmetricKeyCredential credential,
                                                 AuthenticationCallback callback)
                                          throws AuthenticationException

Acquires security token from the authority.

Parameters:

resource - Identifier of the target resource that is the recipient of the requested token.

credential - object representing Private Key to use for token acquisition.

callback - optional callback object for non-blocking execution.

Returns:

A Future object representing the AuthenticationResult of the call. It contains Access Token and the Access Token's expiration time. Refresh Token property will be null for this overload.

Throws:

AuthenticationException - AuthenticationException

acquireTokenByAuthorizationCode

public Future<AuthenticationResult> acquireTokenByAuthorizationCode(String authorizationCode,
                                                                    String resource,
                                                                    String clientId,
                                                                    URI redirectUri,
                                                                    AuthenticationCallback callback)

Acquires security token from the authority using an authorization code previously received.

Parameters:

authorizationCode - The authorization code received from service authorization

resource - Identifier of the target resource that is the recipient of the requested token.

clientId - The client assertion to use for token acquisition endpoint.

redirectUri - The redirect address used for obtaining authorization code.

callback - optional callback object for non-blocking execution.

Returns:

A Future object representing the AuthenticationResult of the call. It contains Access Token, Refresh Token and the Access Token's expiration time.

acquireTokenByAuthorizationCode

public Future<AuthenticationResult> acquireTokenByAuthorizationCode(String authorizationCode,
                                                                    URI redirectUri,
                                                                    ClientAssertion clientAssertion,
                                                                    AuthenticationCallback callback)

Acquires security token from the authority using an authorization code previously received.

Parameters:

authorizationCode - The authorization code received from service authorization endpoint.

redirectUri - The redirect address used for obtaining authorization code.

clientAssertion - The client assertion to use for client authentication.

callback - optional callback object for non-blocking execution.

Returns:

A Future object representing the AuthenticationResult of the call. It contains Access Token, Refresh Token and the Access Token's expiration time.

acquireTokenByAuthorizationCode

public Future<AuthenticationResult> acquireTokenByAuthorizationCode(String authorizationCode,
                                                                    URI redirectUri,
                                                                    ClientAssertion clientAssertion,
                                                                    String resource,
                                                                    AuthenticationCallback callback)

Acquires security token from the authority using an authorization code previously received.

Parameters:

authorizationCode - The authorization code received from service authorization endpoint.

redirectUri - The redirect address used for obtaining authorization code.

clientAssertion - The client assertion to use for client authentication.

resource - Identifier of the target resource that is the recipient of the requested token. It can be null if provided earlier to acquire authorizationCode.

callback - optional callback object for non-blocking execution.

Returns:

A Future object representing the AuthenticationResult of the call. It contains Access Token, Refresh Token and the Access Token's expiration time.

acquireTokenByAuthorizationCode

public Future<AuthenticationResult> acquireTokenByAuthorizationCode(String authorizationCode,
                                                                    URI redirectUri,
                                                                    ClientCredential credential,
                                                                    AuthenticationCallback callback)

Acquires security token from the authority using an authorization code previously received.

Parameters:

authorizationCode - The authorization code received from service authorization endpoint.

redirectUri - The redirect address used for obtaining authorization code.

credential - The client credential to use for token acquisition.

callback - optional callback object for non-blocking execution.

Returns:

A Future object representing the AuthenticationResult of the call. It contains Access Token, Refresh Token and the Access Token's expiration time.

acquireTokenByAuthorizationCode

public Future<AuthenticationResult> acquireTokenByAuthorizationCode(String authorizationCode,
                                                                    URI redirectUri,
                                                                    ClientCredential credential,
                                                                    String resource,
                                                                    AuthenticationCallback callback)

Acquires security token from the authority using an authorization code previously received.

Parameters:

authorizationCode - The authorization code received from service authorization endpoint.

redirectUri - The redirect address used for obtaining authorization code.

credential - The client credential to use for token acquisition.

resource - Identifier of the target resource that is the recipient of the requested token. It can be null if provided earlier to acquire authorizationCode.

callback - optional callback object for non-blocking execution.

Returns:

A Future object representing the AuthenticationResult of the call. It contains Access Token, Refresh Token and the Access Token's expiration time.

acquireTokenByAuthorizationCode

public Future<AuthenticationResult> acquireTokenByAuthorizationCode(String authorizationCode,
                                                                    URI redirectUri,
                                                                    AsymmetricKeyCredential credential,
                                                                    AuthenticationCallback callback)
                                                             throws AuthenticationException

Acquires security token from the authority using an authorization code previously received.

Parameters:

authorizationCode - The authorization code received from service authorization endpoint.

redirectUri - The redirect address used for obtaining authorization code.

credential - object representing Private Key to use for token acquisition.

callback - optional callback object for non-blocking execution.

Returns:

A Future object representing the AuthenticationResult of the call. It contains Access Token, Refresh Token and the Access Token's expiration time.

Throws:

AuthenticationException - thrown if AsymmetricKeyCredential fails to sign the JWT token.

acquireTokenByAuthorizationCode

public Future<AuthenticationResult> acquireTokenByAuthorizationCode(String authorizationCode,
                                                                    URI redirectUri,
                                                                    AsymmetricKeyCredential credential,
                                                                    String resource,
                                                                    AuthenticationCallback callback)
                                                             throws AuthenticationException

Acquires security token from the authority using an authorization code previously received.

Parameters:

authorizationCode - The authorization code received from service authorization endpoint.

redirectUri - The redirect address used for obtaining authorization code.

credential - object representing Private Key to use for token acquisition.

resource - Identifier of the target resource that is the recipient of the requested token. It can be null if provided earlier to acquire authorizationCode.

callback - optional callback object for non-blocking execution.

Returns:

A Future object representing the AuthenticationResult of the call. It contains Access Token, Refresh Token and the Access Token's expiration time.

Throws:

AuthenticationException - thrown if AsymmetricKeyCredential fails to sign the JWT token.

acquireDeviceCode

public Future<DeviceCode> acquireDeviceCode(String clientId,
                                            String resource,
                                            AuthenticationCallback<DeviceCode> callback)

Acquires a device code from the authority

Parameters:

clientId - Identifier of the client requesting the token

resource - Identifier of the target resource that is the recipient of the requested token.

callback - optional callback object for non-blocking execution.

Returns:

A Future object representing the DeviceCode of the call. It contains device code, user code, its expiration date, message which should be displayed to the user.

Throws:

AuthenticationException - thrown if the device code is not acquired successfully

acquireTokenByDeviceCode

public Future<AuthenticationResult> acquireTokenByDeviceCode(DeviceCode deviceCode,
                                                             AuthenticationCallback callback)
                                                      throws AuthenticationException

Acquires security token from the authority using an device code previously received.

Parameters:

deviceCode - The device code result received from calling acquireDeviceCode.

callback - optional callback object for non-blocking execution.

Returns:

A Future object representing the AuthenticationResult of the call. It contains AccessToken, Refresh Token and the Access Token's expiration time.

Throws:

AuthenticationException - thrown if authorization is pending or another error occurred. If the errorCode of the exception is AdalErrorCode.AUTHORIZATION_PENDING, the call needs to be retried until the AccessToken is returned. DeviceCode.interval - The minimum amount of time in seconds that the client SHOULD wait between polling requests to the token endpoin

acquireTokenByRefreshToken

public Future<AuthenticationResult> acquireTokenByRefreshToken(String refreshToken,
                                                               String clientId,
                                                               ClientAssertion clientAssertion,
                                                               AuthenticationCallback callback)

Acquires a security token from the authority using a Refresh Token previously received.

Parameters:

refreshToken - Refresh Token to use in the refresh flow.

clientId - Name or ID of the client requesting the token.

clientAssertion - The client assertion to use for client authentication.

callback - optional callback object for non-blocking execution.

Returns:

A Future object representing the AuthenticationResult of the call. It contains Access Token, Refresh Token and the Access Token's expiration time.

acquireTokenByRefreshToken

public Future<AuthenticationResult> acquireTokenByRefreshToken(String refreshToken,
                                                               String clientId,
                                                               ClientAssertion clientAssertion,
                                                               String resource,
                                                               AuthenticationCallback callback)

Acquires a security token from the authority using a Refresh Token previously received.

Parameters:

refreshToken - Refresh Token to use in the refresh flow.

clientId - Name or ID of the client requesting the token.

clientAssertion - The client assertion to use for client authentication.

resource - Identifier of the target resource that is the recipient of the requested token. If null, token is requested for the same resource refresh token was originally issued for. If passed, resource should match the original resource used to acquire refresh token unless token service supports refresh token for multiple resources.

callback - optional callback object for non-blocking execution.

Returns:

A Future object representing the AuthenticationResult of the call. It contains Access Token, Refresh Token and the Access Token's expiration time.

acquireTokenByRefreshToken

public Future<AuthenticationResult> acquireTokenByRefreshToken(String refreshToken,
                                                               ClientCredential credential,
                                                               AuthenticationCallback callback)

Acquires a security token from the authority using a Refresh Token previously received.

Parameters:

refreshToken - Refresh Token to use in the refresh flow.

credential - The client credential used for token acquisition.

callback - optional callback object for non-blocking execution.

Returns:

A Future object representing the AuthenticationResult of the call. It contains Access Token, Refresh Token and the Access Token's expiration time.

acquireTokenByRefreshToken

public Future<AuthenticationResult> acquireTokenByRefreshToken(String refreshToken,
                                                               ClientCredential credential,
                                                               String resource,
                                                               AuthenticationCallback callback)

Acquires a security token from the authority using a Refresh Token previously received.

Parameters:

refreshToken - Refresh Token to use in the refresh flow.

credential - The client credential used for token acquisition.

resource - Identifier of the target resource that is the recipient of the requested token. If null, token is requested for the same resource refresh token was originally issued for. If passed, resource should match the original resource used to acquire refresh token unless token service supports refresh token for multiple resources.

callback - optional callback object for non-blocking execution.

Returns:

A Future object representing the AuthenticationResult of the call. It contains Access Token, Refresh Token and the Access Token's expiration time.

acquireTokenByRefreshToken

public Future<AuthenticationResult> acquireTokenByRefreshToken(String refreshToken,
                                                               AsymmetricKeyCredential credential,
                                                               AuthenticationCallback callback)
                                                        throws AuthenticationException

Acquires a security token from the authority using a Refresh Token previously received.

Parameters:

refreshToken - Refresh Token to use in the refresh flow.

credential - object representing Private Key to use for token acquisition.

callback - optional callback object for non-blocking execution.

Returns:

A Future object representing the AuthenticationResult of the call. It contains Access Token, Refresh Token and the Access Token's expiration time.

Throws:

AuthenticationException - thrown if AsymmetricKeyCredential fails to sign the JWT token.

acquireTokenByRefreshToken

public Future<AuthenticationResult> acquireTokenByRefreshToken(String refreshToken,
                                                               AsymmetricKeyCredential credential,
                                                               String resource,
                                                               AuthenticationCallback callback)
                                                        throws AuthenticationException

Acquires a security token from the authority using a Refresh Token previously received.

Parameters:

refreshToken - Refresh Token to use in the refresh flow.

credential - object representing Private Key to use for token acquisition.

resource - Identifier of the target resource that is the recipient of the requested token. If null, token is requested for the same resource refresh token was originally issued for. If passed, resource should match the original resource used to acquire refresh token unless token service supports refresh token for multiple resources.

callback - optional callback object for non-blocking execution.

Returns:

A Future object representing the AuthenticationResult of the call. It contains Access Token, Refresh Token and the Access Token's expiration time.

Throws:

AuthenticationException - thrown if AsymmetricKeyCredential fails to sign the JWT token.

acquireTokenByRefreshToken

public Future<AuthenticationResult> acquireTokenByRefreshToken(String refreshToken,
                                                               String clientId,
                                                               AuthenticationCallback callback)

Acquires a security token from the authority using a Refresh Token previously received. This method is suitable for the daemon OAuth2 flow when a client secret is not possible.

Parameters:

refreshToken - Refresh Token to use in the refresh flow.

clientId - Name or ID of the client requesting the token.

callback - optional callback object for non-blocking execution.

Returns:

A Future object representing the AuthenticationResult of the call. It contains Access Token, Refresh Token and the Access Token's expiration time.

Throws:

AuthenticationException - thrown if the access token is not refreshed successfully

acquireTokenByRefreshToken

public Future<AuthenticationResult> acquireTokenByRefreshToken(String refreshToken,
                                                               String clientId,
                                                               String resource,
                                                               AuthenticationCallback callback)

Acquires a security token from the authority using a Refresh Token previously received. This method is suitable for the daemon OAuth2 flow when a client secret is not possible.

Parameters:

refreshToken - Refresh Token to use in the refresh flow.

clientId - Name or ID of the client requesting the token.

resource - Identifier of the target resource that is the recipient of the requested token. If null, token is requested for the same resource refresh token was originally issued for. If passed, resource should match the original resource used to acquire refresh token unless token service supports refresh token for multiple resources.

callback - optional callback object for non-blocking execution.

Returns:

A Future object representing the AuthenticationResult of the call. It contains Access Token, Refresh Token and the Access Token's expiration time.

Throws:

AuthenticationException - thrown if the access token is not refreshed successfully

getCorrelationId

public String getCorrelationId()

Returns the correlation id configured by the user. It does not return the id automatically generated by the API in case the user does not provide one.

Returns:

String value of the correlation id

setCorrelationId

public void setCorrelationId(String correlationId)

Set optional correlation id to be used by the API. If not provided, the API generates a random id.

Parameters:

correlationId - String value

shouldValidateAuthority

public boolean shouldValidateAuthority()

Returns validateAuthority boolean value passed as a constructor parameter.

Returns:

boolean value

getAuthority

public String getAuthority()

Authority associated with the context instance

Returns:

String value