AssureSign: AuthenticateUser

The AuthenticateUser operation provides a mechanism for authenticating user credentials for accessing AssureSign. When this operation is called, the provided user credentials are evaluated to verify access to AssureSign.

Any configured account security options such as password expiration, user account locking after X failed authentication attempts, etc. will be enforced by this operation just as they would be if the user was logging in manually through the AssureSign login page. Beginning with AssureSign version 4.4 AuthenticateUser returns an AuthenticationToken when successful that is a required element in certain DocumentNOW methods.

Note: In many integration methods this operation is not needed. This method will only need to be called in the following types of scenarios:

• Cases where per-user authentication is desired to ensure each specific user has access to AssureSign before allowing further integration. This type of security would have to be implemented/enforced at the client application level.
• Cases where a user has been configured to allow access to multiple accounts. In this type of scenario it becomes necessary for this method to be called so the correct context Identifier can be used when making requests to ensure requests go to the correct account (since the user has access to multiple accounts).
• User and Account Management DocumentNOW Operations

The AuthenticateUser operation requires knowledge of the following:

• the UserName of the user to authenticate
• the Password of the user to authenticate

Sample XML

<?xml version="1.0" encoding="utf-8"?> 
<AuthenticateUser xmlns="https://www.assuresign.net/Services/DocumentNOW/Users"> 
    <AuthenticateUserRequest UserName="jdoe@example.com" Password="Password" /> 
</AuthenticateUser>

The SOAP Action header is

https://www.assuresign.net/Services/DocumentNOW/Users/IUserService/AuthenticateUser

The returned result will include:

• a Sucess flag indicating whether or not the user credentials were authenticated successfully

If the call is successful, the result will also include the following:

• the AssureSign UserName
• the user's First Name
• the user's Last Name
• a list of the accounts the user has access to including the account names and context identifiers and a flag indicating whether or not a particular account is the primary account for that user
• an AuthenticationToken, which is a required element in certain DocumentNOW methods.
• ExpiredPasswordUrl will be returned if the user's password has expired, which may be used to access the expired password page for the user
• ChangePasswordUrl will be returned if relevant to the user account, which may be used to access the change password page for the user

Important: the AuthenticationToken will time out for use in API operations at 30 minutes.

If the call is not successful, the result will include a list of exceptions indicating the cause for authentication failure (invalid credentials, account is locked, account is inactive, etc.).

If the operation is not successful due to password expiration or a password change being required, an appropriate URL indicating the location where the user can change their password will also be provided.

Sample XML response is presented here:

<?xml version="1.0" encoding="utf-8"?> 
<AuthenticateUserResponse xmlns="https://www.assuresign.net/Services/DocumentNOW/Users">
    <AuthenticateUserResult Success="true" AuthenticationToken="[authentication token]" UserName="jdoe@example.com" FirstName="John" LastName="Doe"> 
        <Accounts> 
            <UserAccount Name="Example, Inc." ContextIdentifier="821ae27f-027c-4f21-a2e5-1667fc9b650a" IsPrimary="true" /> 
        </Accounts> 
    </AuthenticateUserResult> 
</AuthenticateUserResponse>