com.okta.authn.sdk.client

Interface AuthenticationClient

All Known Implementing Classes:

DefaultAuthenticationClient

public interface AuthenticationClient

The Okta Authentication API provides operations to authenticate users, perform multi-factor enrollment and verification, recover forgotten passwords, and unlock accounts. It can be used as a standalone API to provide the identity layer on top of your existing application, or it can be integrated with the Okta Sessions API to obtain an Okta session cookie and access apps within Okta.

The API is targeted for developers who want to build their own end-to-end login experience to replace the built-in Okta login experience and addresses the following key scenarios:

• Primary authentication allows you to verify username and password credentials for a user.
• Multifactor authentication (MFA) strengthens the security of password-based authentication by requiring additional verification of another factor such as a temporary one-time password or an SMS passcode. The Authentication API supports user enrollment with MFA factors enabled by the administrator, as well as MFA challenges based on your Okta Sign-On Policy.
• Recovery allows users to securely reset their password if they’ve forgotten it, or unlock their account if it has been locked out due to excessive failed login attempts. This functionality is subject to the security policy set by the administrator.

Create a client using the AuthenticationClients builder.

 Client client = AuthenticationClients.builder().build();
 

NOTE: We recommend you evaluate using an OIDC/OAuth 2.0 flow before considering this API

Since:

0.1.0

See Also:

Okta Authentication API documentation

Method Summary

Modifier and Type	Method and Description
AuthenticationResponse	activateFactor(String factorId, ActivateFactorRequest request, AuthenticationStateHandler stateHandler) The sms, call and token:software:totp factor types require activation to complete the enrollment process.
AuthenticationResponse	answerRecoveryQuestion(RecoveryQuestionAnswerRequest request, AuthenticationStateHandler stateHandler) Answers the user’s recovery question to ensure only the end user redeemed the recovery token for recovery transaction with a RECOVERY status.
AuthenticationResponse	answerRecoveryQuestion(String answer, String stateToken, AuthenticationStateHandler stateHandler) Answers the user’s recovery question to ensure only the end user redeemed the recovery token for recovery transaction with a RECOVERY status.
AuthenticationResponse	authenticate(AuthenticationRequest request, AuthenticationStateHandler stateHandler) Initiates a username and password login against Okta's Authentication API.
AuthenticationResponse	authenticate(String username, char[] password, String relayState, AuthenticationStateHandler stateHandler) Initiates a username and password login against Okta's Authentication API.
AuthenticationResponse	cancel(String stateToken) Cancels the current transaction and revokes the state token.
AuthenticationResponse	challengeFactor(String factorId, String stateToken, AuthenticationStateHandler stateHandler) Requests a challenge factor be sent to the user via the corresponding {code}factorId{code}.
AuthenticationResponse	changePassword(ChangePasswordRequest changePasswordRequest, AuthenticationStateHandler stateHandler) This operation changes a user’s password by providing the existing password and the new password password for authentication transactions with either the PASSWORD_EXPIRED or PASSWORD_WARN state.
AuthenticationResponse	changePassword(char[] oldPassword, char[] newPassword, String stateToken, AuthenticationStateHandler stateHandler) This operation changes a user’s password by providing the existing password and the new password password for authentication transactions with either the PASSWORD_EXPIRED or PASSWORD_WARN state.
AuthenticationResponse	enrollFactor(FactorEnrollRequest factorEnrollRequest, AuthenticationStateHandler stateHandler) Enrolls a user with a factor assigned by their MFA Policy.
AuthenticationResponse	enrollFactor(com.okta.sdk.resource.user.factor.FactorType factorType, com.okta.sdk.resource.user.factor.FactorProvider factorProvider, com.okta.sdk.resource.user.factor.FactorProfile factorProfile, String stateToken, AuthenticationStateHandler stateHandler) Enrolls a user with a factor assigned by their MFA Policy.
com.okta.sdk.ds.DataStore	getDataStore() Returns the internal DataStore of the client.
<T extends com.okta.sdk.resource.Resource> T	instantiate(Class<T> clazz) Delegates to the internal dataStore instance.
AuthenticationResponse	previous(String stateToken, AuthenticationStateHandler stateHandler) Moves the current transaction state back to the previous state.
AuthenticationResponse	recoverPassword(RecoverPasswordRequest request, AuthenticationStateHandler stateHandler) Starts a new password recovery transaction for a given user and issues a recovery token that can be used to reset a user’s password.
AuthenticationResponse	recoverPassword(String username, com.okta.sdk.resource.user.factor.FactorType factorType, String relayState, AuthenticationStateHandler stateHandler) Starts a new password recovery transaction for a given user and issues a recovery token that can be used to reset a user’s password.
AuthenticationResponse	resendActivateFactor(String factorId, String stateToken, AuthenticationStateHandler stateHandler) Resend an activation factor challenge to a user.
AuthenticationResponse	resendVerifyFactor(String factorId, String stateToken, AuthenticationStateHandler stateHandler) Resend a factor verification challenge to a user.
AuthenticationResponse	resetPassword(ChangePasswordRequest changePasswordRequest, AuthenticationStateHandler stateHandler) Resets a user’s password to complete a recovery transaction with a PASSWORD_RESET state.
AuthenticationResponse	resetPassword(char[] newPassword, String stateToken, AuthenticationStateHandler stateHandler) Resets a user’s password to complete a recovery transaction with a PASSWORD_RESET state.
AuthenticationResponse	skip(String stateToken, AuthenticationStateHandler stateHandler) Skip the current transaction state and advance to the next state.
AuthenticationResponse	unlockAccount(String username, com.okta.sdk.resource.user.factor.FactorType factorType, String relayState, AuthenticationStateHandler stateHandler) Starts a new unlock recovery transaction for a given user and issues a recovery token that can be used to unlock a user’s account.
AuthenticationResponse	unlockAccount(UnlockAccountRequest request, AuthenticationStateHandler stateHandler) Starts a new unlock recovery transaction for a given user and issues a recovery token that can be used to unlock a user’s account.
AuthenticationResponse	verifyActivation(String factorId, String stateToken, AuthenticationStateHandler stateHandler) Returns the state of factor's activation.
AuthenticationResponse	verifyFactor(String factorId, String stateToken, AuthenticationStateHandler stateHandler) Verifies the state of a factor.
AuthenticationResponse	verifyFactor(String factorId, VerifyFactorRequest request, AuthenticationStateHandler stateHandler) Verifies an enrolled factor for an authentication transaction with the MFA_REQUIRED or MFA_CHALLENGE state
AuthenticationResponse	verifyRecoveryToken(String recoveryToken, AuthenticationStateHandler stateHandler) Validates a recovery token that was distributed to the end user to continue the recovery transaction.
AuthenticationResponse	verifyUnlockAccount(com.okta.sdk.resource.user.factor.FactorType factorType, VerifyRecoveryRequest request, AuthenticationStateHandler stateHandler) Verifies a recovery challenge sent to the user for primary authentication for a recovery transaction with RECOVERY_CHALLENGE status.

Method Detail

getDataStore

com.okta.sdk.ds.DataStore getDataStore()

Returns the internal DataStore of the client. It is typically not necessary to invoke this method as the Client implements the DataStore API and will delegate to this instance automatically.

Returns:

the client's internal DataStore.

instantiate

<T extends com.okta.sdk.resource.Resource> T instantiate(Class<T> clazz)

Delegates to the internal dataStore instance. This is a convenience mechanism to eliminate the constant need to call client.getDataStore() every time one needs to instantiate Resource.

Type Parameters:

T - the Resource sub-type

Parameters:

clazz - the Resource class to instantiate.

Returns:

a new instance of the specified Resource.

authenticate

AuthenticationResponse authenticate(String username,
                                    char[] password,
                                    String relayState,
                                    AuthenticationStateHandler stateHandler)
                             throws AuthenticationException

Initiates a username and password login against Okta's Authentication API. A user should not be considered logged in until both the response status is {code SUCCESS} and the sessionToken is non null.

Parameters:

username - User’s non-qualified short-name (e.g. dade.murphy) or unique fully-qualified login (e.g dade.murphy@example.com)

password - User’s password credential

relayState - Optional state value that is persisted for the lifetime of the authentication transaction

stateHandler - State handler that handles the resulting status change corresponding to the Okta authentication state machine

Returns:

An authentication response

Throws:

AuthenticationFailureException - when username or password are invalid

AuthenticationException - any other authentication related error

authenticate

AuthenticationResponse authenticate(AuthenticationRequest request,
                                    AuthenticationStateHandler stateHandler)
                             throws AuthenticationException

Initiates a username and password login against Okta's Authentication API. A user should not be considered logged in until both the response status is {code SUCCESS} and the sessionToken is non null.

Parameters:

request - a request object holds all attributes sent to the remote API.

stateHandler - State handler that handles the resulting status change corresponding to the Okta authentication state machine

Returns:

An authentication response

Throws:

AuthenticationFailureException - when username or password are invalid

AuthenticationException - any other authentication related error

changePassword

AuthenticationResponse changePassword(char[] oldPassword,
                                      char[] newPassword,
                                      String stateToken,
                                      AuthenticationStateHandler stateHandler)
                               throws AuthenticationException

This operation changes a user’s password by providing the existing password and the new password password for authentication transactions with either the PASSWORD_EXPIRED or PASSWORD_WARN state.

Parameters:

oldPassword - User’s current password that is expired or about to expire

newPassword - New password for user

stateToken - state token for current transaction

stateHandler - State handler that handles the resulting status change corresponding to the Okta authentication state machine

Returns:

An authentication response

Throws:

CredentialsException - thrown if old password is invalid, or the new password fails to meet the requirements of the password policy

AuthenticationException - any other authentication related error

changePassword

AuthenticationResponse changePassword(ChangePasswordRequest changePasswordRequest,
                                      AuthenticationStateHandler stateHandler)
                               throws AuthenticationException

This operation changes a user’s password by providing the existing password and the new password password for authentication transactions with either the PASSWORD_EXPIRED or PASSWORD_WARN state.

Parameters:

changePasswordRequest - a request object holds all attributes sent to the remote API.

stateHandler - State handler that handles the resulting status change corresponding to the Okta authentication state machine

Returns:

An authentication response

Throws:

CredentialsException - thrown if old password is invalid, or the new password fails to meet the requirements of the password policy

AuthenticationException - any other authentication related error

resetPassword

AuthenticationResponse resetPassword(char[] newPassword,
                                     String stateToken,
                                     AuthenticationStateHandler stateHandler)
                              throws AuthenticationException

Resets a user’s password to complete a recovery transaction with a PASSWORD_RESET state.

Parameters:

newPassword - User’s new password

stateToken - state token for current transaction

stateHandler - State handler that handles the resulting status change corresponding to the Okta authentication state machine

Returns:

An authentication response

Throws:

CredentialsException - thrown if old password is invalid, or the new password fails to meet the requirements of the password policy

AuthenticationException - any other authentication related error

resetPassword

AuthenticationResponse resetPassword(ChangePasswordRequest changePasswordRequest,
                                     AuthenticationStateHandler stateHandler)
                              throws AuthenticationException

Resets a user’s password to complete a recovery transaction with a PASSWORD_RESET state.

Parameters:

changePasswordRequest - a request object holds all attributes sent to the remote API

stateHandler - State handler that handles the resulting status change corresponding to the Okta authentication state machine

Returns:

An authentication response

Throws:

CredentialsException - thrown if old password is invalid, or the new password fails to meet the requirements of the password policy

AuthenticationException - any other authentication related error

enrollFactor

AuthenticationResponse enrollFactor(com.okta.sdk.resource.user.factor.FactorType factorType,
                                    com.okta.sdk.resource.user.factor.FactorProvider factorProvider,
                                    com.okta.sdk.resource.user.factor.FactorProfile factorProfile,
                                    String stateToken,
                                    AuthenticationStateHandler stateHandler)
                             throws AuthenticationException

Enrolls a user with a factor assigned by their MFA Policy.

Parameters:

factorType - type of factor

factorProvider - factor provider

factorProfile - profile of a supported factor

stateToken - state token for current transaction

stateHandler - State handler that handles the resulting status change corresponding to the Okta authentication state machine

Returns:

An authentication response

Throws:

AuthenticationException - any other authentication related error

See Also:

supported factor profiles

enrollFactor

AuthenticationResponse enrollFactor(FactorEnrollRequest factorEnrollRequest,
                                    AuthenticationStateHandler stateHandler)
                             throws AuthenticationException

Enrolls a user with a factor assigned by their MFA Policy.

Parameters:

factorEnrollRequest - a request object holds all attributes sent to the remote API.

stateHandler - State handler that handles the resulting status change corresponding to the Okta authentication state machine

Returns:

An authentication response

Throws:

AuthenticationException - any other authentication related error

See Also:

supported factor profiles

recoverPassword

AuthenticationResponse recoverPassword(String username,
                                       com.okta.sdk.resource.user.factor.FactorType factorType,
                                       String relayState,
                                       AuthenticationStateHandler stateHandler)
                                throws AuthenticationException

Starts a new password recovery transaction for a given user and issues a recovery token that can be used to reset a user’s password.

Parameters:

username - User’s non-qualified short-name (e.g. dade.murphy) or unique fully-qualified login (dade.murphy@example.com)

factorType - Recovery factor to use for primary authentication

relayState - Optional state value that is persisted for the lifetime of the recovery transaction

stateHandler - State handler that handles the resulting status change corresponding to the Okta authentication state machine

Returns:

An authentication response

Throws:

AuthenticationException - any other authentication related error

recoverPassword

AuthenticationResponse recoverPassword(RecoverPasswordRequest request,
                                       AuthenticationStateHandler stateHandler)
                                throws AuthenticationException

Starts a new password recovery transaction for a given user and issues a recovery token that can be used to reset a user’s password.

Parameters:

request - a request object holds all attributes sent to the remote API.

stateHandler - State handler that handles the resulting status change corresponding to the Okta authentication state machine

Returns:

An authentication response

Throws:

AuthenticationException - any other authentication related error

unlockAccount

AuthenticationResponse unlockAccount(String username,
                                     com.okta.sdk.resource.user.factor.FactorType factorType,
                                     String relayState,
                                     AuthenticationStateHandler stateHandler)
                              throws AuthenticationException

Starts a new unlock recovery transaction for a given user and issues a recovery token that can be used to unlock a user’s account.

Parameters:

username - User’s non-qualified short-name (dade.murphy) or unique fully-qualified login (dade.murphy@example.com)

factorType - Recovery factor to use for primary authentication

relayState - Optional state value that is persisted for the lifetime of the recovery transaction

stateHandler - State handler that handles the resulting status change corresponding to the Okta authentication state machine

Returns:

An authentication response

Throws:

AuthenticationException - any other authentication related error

unlockAccount

AuthenticationResponse unlockAccount(UnlockAccountRequest request,
                                     AuthenticationStateHandler stateHandler)
                              throws AuthenticationException

Starts a new unlock recovery transaction for a given user and issues a recovery token that can be used to unlock a user’s account.

Parameters:

request - a request object holds all attributes sent to the remote API.

stateHandler - State handler that handles the resulting status change corresponding to the Okta authentication state machine

Returns:

An authentication response

Throws:

AuthenticationException - any other authentication related error

answerRecoveryQuestion

AuthenticationResponse answerRecoveryQuestion(String answer,
                                              String stateToken,
                                              AuthenticationStateHandler stateHandler)
                                       throws AuthenticationException

Answers the user’s recovery question to ensure only the end user redeemed the recovery token for recovery transaction with a RECOVERY status.

Parameters:

answer - answer to user’s recovery question

stateToken - state token for current transaction

stateHandler - State handler that handles the resulting status change corresponding to the Okta authentication state machine

Returns:

An authentication response

Throws:

InvalidRecoveryAnswerException - thrown when the answer is invalid

AuthenticationException - any other authentication related error

answerRecoveryQuestion

AuthenticationResponse answerRecoveryQuestion(RecoveryQuestionAnswerRequest request,
                                              AuthenticationStateHandler stateHandler)
                                       throws AuthenticationException

Answers the user’s recovery question to ensure only the end user redeemed the recovery token for recovery transaction with a RECOVERY status.

Parameters:

request - a request object holds all attributes sent to the remote API.

stateHandler - State handler that handles the resulting status change corresponding to the Okta authentication state machine

Returns:

An authentication response

Throws:

InvalidRecoveryAnswerException - thrown when the answer is invalid

AuthenticationException - any other authentication related error

previous

AuthenticationResponse previous(String stateToken,
                                AuthenticationStateHandler stateHandler)
                         throws AuthenticationException

Moves the current transaction state back to the previous state.

Parameters:

stateToken - state token for current transaction

stateHandler - State handler that handles the resulting status change corresponding to the Okta authentication state machine

Returns:

An authentication response

Throws:

AuthenticationException - any other authentication related error

skip

AuthenticationResponse skip(String stateToken,
                            AuthenticationStateHandler stateHandler)
                     throws AuthenticationException

Skip the current transaction state and advance to the next state.

Parameters:

stateToken - state token for current transaction

stateHandler - State handler that handles the resulting status change corresponding to the Okta authentication state machine

Returns:

An authentication response

Throws:

AuthenticationException - any other authentication related error

cancel

AuthenticationResponse cancel(String stateToken)

Cancels the current transaction and revokes the state token.

Parameters:

stateToken - state token for current transaction

Returns:

An authentication response

activateFactor

AuthenticationResponse activateFactor(String factorId,
                                      ActivateFactorRequest request,
                                      AuthenticationStateHandler stateHandler)
                               throws AuthenticationException

The sms, call and token:software:totp factor types require activation to complete the enrollment process.

Parameters:

factorId - id of factor returned from enrollment

request - the request object containing the required attributes to fulfill the activation

stateHandler - State handler that handles the resulting status change corresponding to the Okta authentication state machine

Returns:

An authentication response

Throws:

AuthenticationException - any other authentication related error

verifyFactor

AuthenticationResponse verifyFactor(String factorId,
                                    VerifyFactorRequest request,
                                    AuthenticationStateHandler stateHandler)
                             throws AuthenticationException

Verifies an enrolled factor for an authentication transaction with the MFA_REQUIRED or MFA_CHALLENGE state

Parameters:

factorId - id of factor returned from enrollment

request - the request object containing the required attributes to fulfill the verification

stateHandler - State handler that handles the resulting status change corresponding to the Okta authentication state machine

Returns:

An authentication response

Throws:

AuthenticationException - any other authentication related error

verifyFactor

AuthenticationResponse verifyFactor(String factorId,
                                    String stateToken,
                                    AuthenticationStateHandler stateHandler)
                             throws AuthenticationException

Verifies the state of a factor. Some factors (Push, Duo, etc) depend on a user action, this method can be used to poll the state of the a factor and transition to the next state when completed.

Parameters:

factorId - id of factor returned from enrollment

stateToken - state token for current transaction

stateHandler - State handler that handles the resulting status change corresponding to the Okta authentication state machine

Returns:

An authentication response

Throws:

AuthenticationException - any other authentication related error

challengeFactor

AuthenticationResponse challengeFactor(String factorId,
                                       String stateToken,
                                       AuthenticationStateHandler stateHandler)
                                throws AuthenticationException

Requests a challenge factor be sent to the user via the corresponding {code}factorId{code}.

Parameters:

factorId - id of factor returned from enrollment

stateToken - state token for current transaction

stateHandler - State handler that handles the resulting status change corresponding to the Okta authentication state machine

Returns:

An authentication response

Throws:

AuthenticationException - any other authentication related error

verifyUnlockAccount

AuthenticationResponse verifyUnlockAccount(com.okta.sdk.resource.user.factor.FactorType factorType,
                                           VerifyRecoveryRequest request,
                                           AuthenticationStateHandler stateHandler)
                                    throws AuthenticationException

Verifies a recovery challenge sent to the user for primary authentication for a recovery transaction with RECOVERY_CHALLENGE status.

Parameters:

factorType - type of factor

request - the request object containing the required attributes to fulfill this challenge

stateHandler - State handler that handles the resulting status change corresponding to the Okta authentication state machine

Returns:

An authentication response

Throws:

AuthenticationException - any other authentication related error

resendActivateFactor

AuthenticationResponse resendActivateFactor(String factorId,
                                            String stateToken,
                                            AuthenticationStateHandler stateHandler)
                                     throws AuthenticationException

Resend an activation factor challenge to a user. Factors that require the challenge sent to the user (push, call, sms, etc) may need to be resent to ensure delivery.

Parameters:

factorId - id of factor returned from enrollment

stateToken - state token for current transaction

stateHandler - State handler that handles the resulting status change corresponding to the Okta authentication state machine

Returns:

An authentication response

Throws:

AuthenticationException - any other authentication related error

resendVerifyFactor

AuthenticationResponse resendVerifyFactor(String factorId,
                                          String stateToken,
                                          AuthenticationStateHandler stateHandler)
                                   throws AuthenticationException

Resend a factor verification challenge to a user. Factors that require the challenge sent to the user (push, call, sms, etc) may need to be resent to ensure delivery.

Parameters:

factorId - id of factor returned from enrollment

stateToken - state token for current transaction

stateHandler - State handler that handles the resulting status change corresponding to the Okta authentication state machine

Returns:

An authentication response

Throws:

AuthenticationException - any other authentication related error

verifyActivation

AuthenticationResponse verifyActivation(String factorId,
                                        String stateToken,
                                        AuthenticationStateHandler stateHandler)
                                 throws AuthenticationException

Returns the state of factor's activation. Some factors (Push, Duo, etc) depend on a user action, this method can be used to poll the state of the a factor's activation and transition to the next state when completed.

Parameters:

stateToken - state token for current transaction

stateHandler - State handler that handles the resulting status change corresponding to the Okta authentication state machine

Returns:

An authentication response

Throws:

AuthenticationException - any other authentication related error

verifyRecoveryToken

AuthenticationResponse verifyRecoveryToken(String recoveryToken,
                                           AuthenticationStateHandler stateHandler)
                                    throws AuthenticationException

Validates a recovery token that was distributed to the end user to continue the recovery transaction.

Parameters:

recoveryToken - Recovery token that was distributed to the end user via out-of-band mechanism such as email

stateHandler - State handler that handles the resulting status change corresponding to the Okta authentication state machine

Returns:

An authentication response

Throws:

AuthenticationException - any other authentication related error