ENTAADeveloperGuidebook » ENTAA API Specifications

ENTAA API Specifications

Last modified by Matthew Harshbarger on 2014/07/01 15:11

Contents 

Interface: AAServiceInterface

Method: AAUserInterface authenticate(String appId, String userId, String password)

This method authenticates the userId and password for the specified application. It returns an AAUserInterface object which would contain a List of allowed auth levels for the user. If the user is authenticated, but has no associated identity baseline defined, this method throws AccountNotInitializedException.

Exceptions

  • InvalidUserException
  • AccountDisabledException
  • AccountLockedException
  • AccountNotInitializedException
  • ChangePasswordException
  • InsufficientDataException
  • UnexpectedFatalException


XML Request

<AAService>
<Authenticate>
 <AppId value=””/>
  <UserId value=””/>
  <Password value=””/>
  <ProviderId value=””/> 
</Authenticate>
</AAService>

Note: ProviderId is optional

XML Response

<AAService >
<Result value=”0/1/2/3/4/9/10/100” method=”Authenticate” appId=””></Result>
<EmpId></EmpId>
 <ProviderId value=””/>
<UserId value=””/>
<PrivilegeList appId=””>
 <Privilege code=”” ></Privilege>
 <Privilege code=”” ></Privilege>
 .
 .
</PrivilegeList>
<CustomAttributeList appId=””>
 <CustomAttribute code=””></CustomAttribute>
 <CustomAttribute code=””></CustomAttribute>
 .
 .
</CustomAttributeList>
</AAService>

Result Element: This would contain any relevant message. For instance, in case of a fatal exception on server side, this might provide additional information on what exactly went wrong. Possible values:

  • 0 – success
  • 1 – InvalidUserException
  • 2 – AccountLockedException
  • 3 – ChangePasswordException
  • 4 – InsufficientDataException
  • 9 – AccountNotInitializedException
  • 10 – AccountDisabledException
  • 100 – UnexpectedFatalException

PrivilegeList Element: This element contains Privilege sub-elements indicating the allowed privileges for the user.  Each Privilege element contains a ‘code’ attribute with the admin-defined privilege code.


Method: AAUserInterface getUserObject(String tokenId, String appId)

This method retrieves User object for the specified token. This method is used by the client application in the SSO scenario. It returns an AAUserInterface object which would contain a List of allowed auth levels for the user.

Exceptions

  • InvalidTokenException
  • UnexpectedFatalException


XML Request

<AAService>
<GetUserObject>
 <TokenId value=””/>
 <AppId value=”” />
</GetUserObject>
</AAService>

XML Response

<AAService >
<Result value=”0/13/100” method=”GetUserObject” appId=””></Result>
<EmpId></EmpId>
 <ProviderId value=””/>
<UserId value=””/>
<PrivilegeList appId=””>
 <Privilege code=”” ></Privilege>
 <Privilege code=”” ></Privilege>
 .
 .
</PrivilegeList>
<CustomAttributeList appId=””>
 <CustomAttribute code=””></CustomAttribute>
 <CustomAttribute code=””></CustomAttribute>
 .
 .
</CustomAttributeList>
</AAService>

Result Element: Similar to authenticate, above. Possible values for this method:

  • 0 – success
  • 13 – InvalidTokenException
  • 100 – UnexpectedFatalException


Method: void changePassword(String appId, String userId, String oldPassword, String newPassword)

This method changes the password for the given userId, password and appId combination

Exceptions

  • InvalidUserException
  • AccountLockedException
  • AccountDisabledException
  • AccountNotInitializedException
  • InsuffiecientDataException
  • InvalidNewPasswordException
  • UnexpectedFatalException


XML Request

<AAService>
<ChangePassword>
  <AppId value=””/>
 <UserId value=””/>
  <OldPassword value=””/>
 <NewPassword value=””/>
 <ProviderId value=””/>
</ChangePassword>
</AAService>

Note: ProviderId is optional


XML Response

<AAService>
<Result value=”0/1/2/3/4/5/9/10/100” method=”ChangePassword” appId=”” providerId=””></Result>
</AAService>

Result Element: Similar to authenticate, above.


Method: String changePasswordByAdmin(String appId, String adminUserId, String adminPassword, String userId, String newPassword)

This method allows an admin user to the password of a user to a particular value. User must have PWD (or ACCT?) privilege to perform this task.

Exceptions

  • AdminPermissionException
  • AdminAccountLockedException
  • AdminAccountDisabledException
  • AdminAccountNotInitializedException
  • AccountNotInitializedException
  • InvalidUserException
  • AccountLockedException
  • AccountDisabledException
  • InsufficientDataException
  • UnexpectedFatalException


XML Request

<AAService>
<ChangePasswordByAdmin>
  <AppId value=””/>
 <AdminUserId value=””/>
  <AdminPassword value=””/>
 <UserId value=””/>
 <NewPassword value=””/>
 <ProviderId value=””/>
</ChangePasswordByAdmin>
</AAService>

XML Response

<AAService>
<Result value=”0/1/2/4/6/7/9/10/11/12/100” method=”ChangePasswordByAdmin” appId=”” providerId=””></Result>
</AAService>


Method: String resetPassword(String appId, String adminUserId, String adminPassword, String userId)

This method allows an admin user to reset the password of a specified user. Returns the new randomly generated password. User must have PWD (or ACCT?) privilege to perform this task.

Exceptions

  • AdminPermissionException
  • AdminAccountLockedException
  • AdminAccountDisabledException
  • AdminAccountNotInitializedException
  • InvalidUserException
  • AccountLockedException
  • AccountDisabledException
  • InsufficientDataException
  • UnexpectedFatalException


XML Request

<AAService>
<ResetPassword>
  <AppId value=””/>
 <AdminUserId value=””/>
  <AdminPassword value=””/>
 <UserId value=””/>
<ProviderId value=””/>
</ResetPassword>
</AAService>

XML Response

<AAService>
<Result value=”0/1/2/4/6/7/10/11/12/100” method=”ResetPassword” appId=”” providerId=””></Result>
<NewPassword value=””/>
</AAService>


Method: Void createAccount(String appId, String userId, String userPassword, String firstName, String lastName, String eMail, String[] privileges)

This method allows a user to create an account himself (self registration).

Exceptions

  • InvalidUserException
  • InsufficientDataException
  • InvalidNewPasswordException
  • UnexpectedFatalException


XML Request

<AAService>
<CreateAccount>
  <AppId value=””/>
 <ApplicationUserId value=””/>
  <ApplicationPassword value=””/>
 <UserId value=””/>
  <Password value=””/>
 <FirstName value=””/>
 <LastName value=””/>
 <Email value=””/>
 <PrivilegeList>
  <Privilege value=””/>
  ….
 </PrivilegeList>
 <ProviderId value=””/>
</CreateAccount>
</AAService>

XML Response

<AAService>
<Result value=”0/1/2/4/6/7/9/10/11/12/100” method=”CreateAccount” appId=”” providerId=””></Result>
</AAService>


Method: AAPrivilegeInterface[] getUserPrivileges(String appId, String adminUserId, String adminPassword, String userId)

This method retrieves the privileges of the specified user. User must have OWNER or PRIV privilege to perform this task.

Exceptions

  • AdminPermissionException
  • AdminAccountLockedException
  • AdminAccountDisabledException
  • AdminAccountNotInitializedException
  • InvalidUserException
  • AccountLockedException
  • AccountDisabledException
  • InsufficientDataException
  • UnexpectedFatalException


XML Request

<AAService>
<GetUserPrivileges>
  <AppId value=””/>
 <AdminUserId value=””/>
  <AdminPassword value=””/>
 <UserId value=””/>
 <ProviderId value=””/>
</GetUserPrivileges>
</AAService>

XML Response

<AAService>
<Result value=”0/1/2/4/6/7/10/11/12/100” method=”GetUserPrivileges” appId=”” providerId=””></Result>
<PrivilegeList appId=””>
 <Privilege code=”” ></Privilege>
 <Privilege code=”” ></Privilege>
 .
 .
</PrivilegeList>
</AAService>


Method: void setUserPrivileges(String appId, String adminUserId, String adminPassword, String userId, AAPrivilegeInterface[] privileges)

This method sets the specified set of privileges to the user. User must have OWNER or PRIV privilege to perform this task.

Exceptions

  • AdminPermissionException
  • AdminAccountLockedException
  • AdminAccountDisabledException
  • AdminAccountNotInitializedException
  • AccountNotInitializedException
  • InvalidUserException
  • AccountLockedException
  • AccountDisabledException
  • InvalidPrivilegeException
  • InsufficientDataException
  • UnexpectedFatalException


XML Request

<AAService>
<SetUserPrivileges>
  <AppId value=””/>
 <AdminUserId value=””/>
  <AdminPassword value=””/>
 <UserId value=””/>
 <ProviderId value=””/>
  <PrivilegeList >
  <Privilege value=””/>
 <Privilege value=””/>
    .
  .
 <PrivilegeList>
</SetUserPrivileges>
</AAService>

XML Response

<AAService>
<Result value=”0/1/2/4/6/7/8/9/10/11/12/100” method=”SetUserPrivileges” appId=””></Result>
</AAService>


Method: AAPrivilegeInterface[] listAppPrivileges(String appId, String adminUserId, String adminPassword)

This method returns a list of all the available privileges for the specified Application. User must have OWNER or PRIV privilege to perform this task.

Exceptions

  • AdminPermissionException
  • AdminAccountLockedException
  • AccountLockedException
  • AdminAccountDisabledException
  • AccountDisabledException
  • AdminAccountNotInitializedException
  • InvalidUserException
  • InsufficientDataException
  • UnexpectedFatalException


XML Request

<AAService>
<ListAppPrivileges”>
  <AppId value=””/>
 <AdminUserId value=””/>
  <AdminPassword value=””/>
  <ProviderId value=””/>
</ListAppPrivileges>
</AAService>

XML Response

<AAService>
<Result value=”0/1/2/4/6/9/11/100” method=”ListAppPrivileges” appId=”” providerId=””></Result>
<PrivilegeList appId=””>
 <Privilege code=”” ></Privilege>
 <Privilege code=”” ></Privilege>
 .
 .
</PrivilegeList>
</AAService>


Method: string[] getPrivilegeUsers(String appId, String adminUserId, String adminPassword, String userId, String priv)

This method retrieves the list of user accounts that have the specified privilege code. User must have OWNER or PRIV privilege to perform this task.

Exceptions

  • AdminPermissionException
  • AdminAccountLockedException
  • AdminAccountDisabledException
  • AdminAccountNotInitializedException
  • InvalidUserException
  • AccountLockedException
  • AccountDisabledException
  • InsufficientDataException
  • UnexpectedFatalException


XML Request

<AAService>
<GetPrivilegeUsers>
 <AppId value=””/>
 <AdminUserId value=””/>
 <AdminPassword value=””/>
 <UserId value=””/>
 <ProviderId value=””/>
 <Privilege value=””/>
</GetPrivilegeUsers>
</AAService>

XML Response

<AAService>
<Result value=”0/1/2/4/6/7/10/11/12/100” method=”GetPrivilegeUsers” appId=”” providerId=””></Result>
<TransactionLogId>''translogid''</TransactionLogId>
<UserList appId=””>
 <UserId>''userid1''</UserId>
 <UserId>''userid1''</UserId>
 .
 .
</UserList >
</AAService>


Method: string[] getPrivilegeUsersByToken(String appId, String tokenId, String userId, String priv)

This method retrieves the list of user accounts that have the specified privilege code. User must have OWNER or PRIV privilege to perform this task.

Exceptions

  • AdminPermissionException
  • AdminAccountLockedException
  • AdminAccountDisabledException
  • AdminAccountNotInitializedException
  • InvalidTokenException
  • InvalidUserException
  • AccountLockedException
  • AccountDisabledException
  • InsufficientDataException
  • UnexpectedFatalException


XML Request

<AAService>
<GetPrivilegeUsersByToken>
 <AppId value=””/>
 <TokenId value=””/>
 <UserId value=””/>
 <ProviderId value=””/>
 <Privilege value=””/>
</GetPrivilegeUsersByToken>
</AAService>

XML Response

<AAService>
<Result value=”0/1/2/4/6/7/10/11/12/100” method=”GetPrivilegeUsersByToken” appId=”” providerId=””></Result>
<TransactionLogId>''translogid''</TransactionLogId>
<UserList appId=””>
 <UserId>''userid1''</UserId>
 <UserId>''userid1''</UserId>
 .
 .
</UserList >
</AAService>


Method: String getPasswordRules(String appId)

This method returns password format rules for the underlying provider.

Exceptions

  • UnexpectedFatalException


XML Request

<AAService>
<GetPasswordRules”>
  <AppId value=””/>
  <ProviderId value=””/>
</ GetPasswordRules >
</AAService>

XML Response

<AAService>
<Result value=”0/100” method=”GetPasswordRules” appId=”” providerId=””></Result>
<PasswordRules”>
</PasswordRulest>
</AAService>


Method: void updateAccount(AAUserInterface user);

This method updates the user account on the server side with any changes made on the client side.  The user object’s properties can be changed by setting new values by calling setproperty(newValue) methods.

Exceptions

  • UnexpectedFatalException


XML Request

<AAService>
 <UpdateAccount>
 <AppId value=””/>
  <UserId value=””/>
  <Password value=””/>
  <ProviderId value=””/> 
  <firstname value=””/>
  <lastname value=””/>
  <email value=””/>
  <phonenumber value=””/>
 </UpdateAccount>
</AAService>

XML Response

<AAService>
<Result value=”0/100” method=”updateAccount” appId=”” providerId=””></Result>
</AAService>


Method: String getSignonUrl(String appId, String callingApp)

This method returns a valid URL to Sign On to A&A . This enables SSO enabled applications take advantage of the A&A’s SSO features. Application Id and calling application’s return URL should be posted to SSO system.

Important note: After successful signon, A&A will redirect the user to “callingApp” URL with tokenId parameter. For further details about the user (such as privileges), application needs to call getUserObject passing the received tokenId. See getUserObject in this document.


Example

To get the logon URL for app ID "ITE_BUGS" and return the user to your post-logon action, use the following example:

getSignonUrl("ITE_BUGS", "http://www.iowa.gov/myapp?afterlogonaction") 
    = "https://entaa.iowa.gov/entaa/sso?appId=ITE_BUGS&callingApp=http://www.iowa.gov/myapp?afterlogonaction";

Note: This is a client-side method. No XML is sent to the server, and no exceptions are returned.


Specifying a Tab on the Common Interface

Depending no your implementation needs, you may want to send the user to a specific tab

  • SIGN IN Tab: Default if nothing is specified, or if "tab=" is sent with no value
  • CREATE AN ACCOUNT Tab: "tab=createacct"
  • FORGOT PASSWORD Tab: "tab=forgotpwd"
  • FORGOT ID Tab: "tab=forgotid"

Specifying a header logo on the Common Interface

To keep some continuity between your application and the ENTAA Common Interface screens, you can specify the URL of an image to be displayed at the top of the CI pages.  To do this, use the logo parameter in the redirect URL you provide to the user.  Make sure to URL encode the logo URL to prevent it from being garbled by the user's browser.  You should also make sure values passed for the callingApp and logo are lowercase.  Using the example from above: https://entaa.iowa.gov/entaa/sso?appId=ITE_BUGS&callingApp=http://www.iowa.gov/myapp?afterlogonaction&logo=http://myserver/image/myheader.gif

Method: String getSignoffUrl(String appId, String callingApp)

This method returnes a valid URL to logoff of all A&A SSO applications.

Note: This is a client-side method. No XML is sent to the server, and no exceptions are returned.


Method: String getBaselineUrl(String appId, String userid, String callingApp)

This method returns a valid URL to Identity Baseline Administration screens.

Following parameters need to be posted to A&A Admin Server: commandName, appId, accountId and callingApp

Where commandName should be GotoIdentityBaselineSetup for Baseline setup.

callingApp should contain the URL to return to from A&A after baseline is setup.

Make sure the data is properly encoded before posting.

URL Example:  https://entaa.iowa.gov/entaa/admin?commandName=GotoIdentityBaselineSetup&appId=WARRANTS&accountId=firstname.lastname@iowa.gov&callingApp=https://entaa.iowa.gov/warrants/logon.jsp

Note: This is a client-side method. No XML is sent to the server, and no exceptions are returned.


Method: String getSelfServiceUrl(String appId, String userid, String callingApp)

This method returns a valid URL to Self Service screens.

Following parameters need to be posted to A&A Admin Server: commandName, appId, userId and callingApp, where commandName should be GotoSelfServPwd for Baseline setup.

callingApp should contain the URL to return to from A&A after self service is completed. Make sure the data is properly encoded before posting.

URL Example:  https://entaa.iowa.gov/entaa/admin?commandName=GotoSelfServPwd&appId=WARRANTS&userId=firstname.lastname@iowa.gov&callingApp=https://entaa.iowa.gov/warrants/logon.jsp
Note: This is a client-side method. No XML is sent to the server, and no exceptions are returned.


Method: static String getChangePasswordUrl(String appId, String userid, String callingApp)

This method returns a valid URL to A&A Change Password screen.

This method returns a valid URL to Self Service screens.

Following parameters need to be posted to A&A Admin Server:

commandName, appId, accountId and callingApp

Where commandName should be GotoChangePassword for Baseline setup.

callingApp should contain the URL to return to from A&A after the password is changed on A&A. Make sure the data is properly encoded before posting.

URL Example:  https://entaa.iowa.gov/entaa/admin?commandName=GotoChangePassword&appId=WARRANTS&AccountId=firstname.lastname@iowa.gov&callingApp=https://entaa.iowa.gov/warrants/logon.jsp

Note: This is a client-side method. No XML is sent to the server, and no exceptions are returned.


Method: String getTokenUrl(String appId, String callingApp) v3.0 and above

This method returns a valid URL to fetch a new token if the user's session is still vaild.  If the user's session is gone then tokenId=false is returned as a get string parameter.

Following parameters need to be posted to A&A Admin Server: appId and callingApp.

CallingApp should contain the URL to return to from A&A after get token is completed. Make sure the data is properly encoded before posting.

URL Example: https://entaa.iowa.gov/entaa/admin?commandName=NewToken&appId=WARRANTS&callingApp=https://entaa.iowa.gov/warrants/logon.jsp
Note: This is a client-side method. No XML is sent to the server, and no exceptions are returned.

Method: String getSessionKeepAliveUrl(String appId, String callingApp) v3.0 and above

This method returns a valid URL used to refresh the user's session.  If the user's session is gone or was new then tokenId=false is returned as a get string parameter else a valid token is returned.

Following parameters need to be posted to A&A Admin Server: appId and callingApp.

CallingApp should contain the URL to return to from A&A after session keep alive is completed. Make sure the data is properly encoded before posting.

URL Example: https://entaa.iowa.gov/entaa/admin?commandName=SessionKeepAlive&appId=WARRANTS&callingApp=https://entaa.iowa.gov/warrants/logon.jsp
Note: This is a client-side method. No XML is sent to the server, and no exceptions are returned.

Interface: AAUserInterface

Method: Boolean authorize(String authCode)

This method returns true if the user has privilege to the specified authCode.

Note: This is a client-side method. No XML is sent to the server, and no exceptions are returned.


Method: void changePassword(String newPassword)

See changePassword(String appId, String userId, String oldPassword, String newPassword), above. All parameters except newPassword are provided automatically by the AAUser object.


Method: String changeUserPassword(String userId, String newPassword)

See changePasswordByAdmin(String appId, String adminUserId, String adminPassword, String userId, String newPassword), above. All parameters except userId and newPassword are provided automatically by the AAUser object. This method allows an admin user to the password of a user to a particular value.


Method: String getAppId()

This method returns the Application Id of the user.

Note: This is a client-side method. No XML is sent to the server, and no exceptions are returned.


Method: String getId()

This method returns the User Id of the user.

Note: This is a client-side method. No XML is sent to the server, and no exceptions are returned.


Method: String getEmpId()

This method returns the User’s Employee Id.

Note: This is a client-side method. No XML is sent to the server, and no exceptions are returned.


Method: String getPassword()

This method returns the Password of the user.

Note: This is a client-side method. No XML is sent to the server, and no exceptions are returned.


Method: AAPrivilegeInterface[] getPrivileges()

This method returns a list of all the allowed privileges for this user.

Note: This is a client-side method. No XML is sent to the server, and no exceptions are returned.


Method: AAPrivilegeInterface[] getUserPrivileges(String userId)

See getUserPrivileges(String appId, String adminUserId, String adminPassword, String userId), above. All parameters except userId are provided automatically by the AAUser object. Allows an admin user to retrieve the privileges assigned to the specified user.


Method: AAPrivilegeInterface[] listAppPrivileges()

See listAppPrivileges(String appId, String adminUserId, String adminPassword), above. All parameters are provided automatically by the AAUser object. Allows an admin user to retrieve the list of available privileges for the current application.


Method: String resetUserPassword(String userId)

See resetPassword(String appId, String adminUserId, String adminPassword, String userId), above. All parameters except userId are provided automatically by the AAUser object. Allows an admin user to reset the password of a specified user.


Method: void setUserPrivileges(String userId, AAPrivilegeInterface[] privileges)

See setUserPrivileges(String appId, String adminUserId, String adminPassword, String userId, AAPrivilegeInterface[] privileges), above. All parameters except userId and privileges are provided automatically by the AAUser object. Allows an admin user to assign the specified set of privileges to the user.


Method: String getPasswordRules()

This method returns password format rules for the underlying provider.

Exceptions

  • UnexpectedFatalException


Method: String getCustomAttributeValue(String attrbuteName)

This method returns the specified Custom Attribute. Throws UnexpectedFatalException if the specified attribute is not found.

Note: This is a client-side method. No XML is sent to the server, and no exceptions are returned.


Method: AACustomAttributeInterface[] getCustomAttributes()

This method returns all the custom attributes names. If there are no Custom Attributes to return, this method returns an empty array.

Note: This is a client-side method. No XML is sent to the server, and no exceptions are returned.


Interface: AACustomAttributeInterface

Method: String getName()

This method returns the attribute name.

Note: This is a client-side method. No XML is sent to the server, and no exceptions are returned.


Method: String getValue()

This method returns the attribute value.

Note: This is a client-side method. No XML is sent to the server, and no exceptions are returned.


Interface: AAPrivilegeInterface

Method: String getPrivilegeCode()

This method returns the privilege code.

Note: This is a client-side method. No XML is sent to the server, and no exceptions are returned.


Method: String getPrivilegeDesc()

This method returns the privilege description. authCode.

Note: This is a client-side method. No XML is sent to the server, and no exceptions are returned.

Tags:
Created by Mike Phillips on 2011/06/07 11:13

This wiki is licensed under a Creative Commons 2.0 license
XWiki Enterprise 3.0.36132 - Documentation