Passport Web Service Features

The following methods provide the means to create a Passport Account and interact with the Simplicity database using a Passport Account.

Account Creation & Activation

An account is a user profile, which will allow the said user access to the web forms and tools made available via the Data Integration Web Services.

An account comprises of an Account Name (which must be unique and is usually an email address), a password and the available permissions.

User accounts can be created, either with credentials (such as an authorizing key and password for the services, a campaign name or segment and an authorizing account name and password of a user) or without.

Process Flow: Account Creation & Activation

The following screen shots relate to the Account Creation & Activation process flow, shown above:

Step 1: User registers new account

Step 2: Registration succeeded

Step 3: Registration activation e-mail dispatched and recipient clicks the activation link

Step 4: Registrant is brought to the website to activate their account, where they click the Activate button.

Step 5: Account activation confirmation email is sent to registrant.

Account Log In and Log Out

A user with an enabled account can log in and out of the passport service. If the login is successful a token will be provided. This token is only valid for a configurable duration, and only with a valid token can the services be accessed.

You can also specify a campaign name and segment (that must exist in Simplicity) if you would like an activity record written again that campaign when the user logs in.

There is also the ability to define the login model, which defines the number of tokens allowed in a session. The three models are as follows:

MultipleLogins: Allows multiple concurrent tokens.

SingleLogin: If the user has an active token an error is returned.

RoamingLogin: If the user has an active session then the token is expired and a new token is issued.

On logging out, the token is expired and the services will be unavailable until the user logs in.

Process Flow: Login

The following screen shots relate to the Login process flow, shown above:

Step 1: User enters their username and password into the login form and clicks the Login button. If successful, they will be granted access to the website.

Step 2: If the user already has registered for an account but has not yet activated it, then they will have the option to resend the activation e-mail. Registration activation e-mail dispatched and recipient clicks the activation link

Step 3: Registrant is brought to the website to activate their account, where they click the Activate button.

Step 4: Account activation confirmation email is sent to registrant.

Step 5: Now that the user is properly activated, they will be able to login to the website.

Authentication

While to a user it may appear that they are traversing across a single site, sometimes this is not always the case from a technical perspective. This feature is a security measure that allows a token (that moves with the user through the site path) to be passed between sites or services, and allows each site/page/service to re-authenticate the user and ensure that any previous tokens can’t be used. This ensures that only one token is valid at any given time.

Setting and Resetting Passwords

A password to an account can be set if the password needs to change.

If the user has forgotten their password the password can be reset.

Both these methods can be used with credentials (such as an authorizing key and password for the services, a campaign name or segment and an authorizing account name and password of a user) or without.

Process Flow: Set Password

The following screen shot relates to the Set Password process flow, shown above:

Step 1: If they are already logged in to the site, the user navigates to the Update Password page. They enter their existing password and their new password. Upon clicking the Submit button, their password is instantly updated and will be used the next time they login.

Process Flow: Reset Password

The following screen shots relate to the Reset Password process flow, shown above:

Step 1: User enters the site and attempts to login. Since they forgot their password they click the Forgot Password link.

Step 2: They enter their current e-mail address which is stored against their account and Submit the form.

Step 3: As passwords are encrypted, we are unable to provide a reminder of the existing password. Therefore the password must be reset. If the e-mail address entered in the previous step is valid, then a Reset Password Request e-mail will be sent to that address.

When the user receives the e-mail, they will click the Reset Your Password link (assuming they legitimately requested the password reset), otherwise they can either ignore the e-mail or click the Cancel Reset link.

Step 4a: After clicking the Reset Your Password link, the user is brought to the Reset Password page where they will enter their new password.

Step 4b: If the user clicked the Cancel Reset link in the previous email then they will be brought to the Cancel Reset Password page. Upon clicking the Cancel Reset Password button, the pending reset password request will be terminated.

Step 5: After submitting their new password, the user will receive an e-mail confirmation with their current access credentials and a link to login to the site.

Step 6: User can now login with their new password.

Setting an Email Address

You can set an email address associated with an account, as long as the associated account has the appropriate permissions.

This can be used with credentials (such as an authorizing key and password for the services, a campaign name or segment and an authorizing account name and password of a user) or without.

Process Flow: Set Email Address

The following screen shot relates to the Set Email Address process flow, shown above:

Step 1: If they are already logged in to the site, the user navigates to the Update Email page. Their current e-mail address will be displayed and they will then enter the new e-mail address. Once they click the Submit button, their e-mail will instantly be changed.

Setting Account Permissions

An account can have its accessibility limited (where the user’s ability to use certain functions – like deleting another account by setting the appropriate permissions. Permissions are as follows:

• None No permissions.
• CreateAccount Can create a new account.
• DeleteAccount Can delete an existing account.
• EnableAccount Can enable an account that is disabled.
• DisableAccount Can disable an account that is enabled.
• SetPassword Can set a new password.
• ResetPassword Can reset an existing password.
• SetEmailAddress Can set an Email Address on an account.
• AccessDataIntegration Can access the Data Integration information.
• AlterAccount Can set or reset account permissions.

E-mail Templates & Merge Fields

The four following e-mail templates are able to receive merge fields that will be used to populate pre-defined fields in those e-mails:

• PWS_ACCOUNT_ACTIVATE_REQUEST
• Email for requesting account activation – used to confirm registering user owns the given email address.
• Merge fields:
• Username – New account username. The developer should supply this via the web method call to:CreateAccountForAccountOwnerWithConfirmation2WithCredentials
• Password – New account password. The developer should supply this via the web method call to:CreateAccountForAccountOwnerWithConfirmation2WithCredentials
• AccountActivationRequest_RSN – a GUID that will be used in the URL to confirm the account activation request. The system will generate this GUID and plug it into the e-mail template. When the user clicks the URL in the e-mail, the GUID will be read in and the account will then be activated.
• PWS_ACCOUNT_ACTIVATE_CONFIRM
• Email to confirm to user that their account has been activated. This is used with theActivateAccount web method.
• Merge fields:
• N/A
• PWS_PASSWORD_RESET_REQUEST
• Email for requesting to reset a forgotten password – used to confirm requesting user owns the account. Used with the ResetPasswordRequestweb method.
• Merge fields:
• ResetPasswordRequest_RSN – a GUID that will be used in the URL to confirm the reset password request. The system will generate this GUID and plug it into the e-mail template. When the user clicks the URL in the e-mail, the GUID will be read in and the password will then be allowed to be reset. Normally, this will be through a redirect to a Password Change page, or similar mechanism.
• PWS_PASSWORD_RESET_CONFIRM
• Email to confirm to user that their password has been reset. This is used with the SetPasswordFromResetPasswordRequestweb method.
• Merge fields:
• N/A

Passport Application Web Service Method Definitions

The following information provides the means to create a Passport Account and interact with the Simplicity database using said account. There are a fair number of web methods available, however the web methods mentioned below will meet most developers’ needs. This web service is accessed via http on port 80 or https on port 443 at the following URL relative to the client’s SCIS website:

/SingleView/Common/PassportApplicationSvc.asmx

• Creating a Passport Object
• Web Methods
• CreateAccountForAccountOwnerWithConfirmation2WithCredentials
• ActivateAccount
• Login
• ResetPasswordRequest
• CancelResetPasswordRequest
• SetPasswordFromResetPasswordRequest
• SetPassword
• SetEmailAddress
• Passport Result/Error Codes

Creating a Passport Object

To create a Passport Service object using VB.NET, first add a web reference to your project.

Web Reference URL:

/SingleView/Common/PassportApplicationSvc.asmx

Web Reference Name:PassportService

Now, use the following code:

Using passportsvc As New PassportService.PassportSvc

‘===== Code that interacts with the web service goes here =====

Web Service Method – CreateAccountForAccountOwnerWithConfirmation2WithCredentials

This method creates a new passport account that will allow a user to access the services.

Parameters

Key: Client ID (type GUID)

AuthPassword: The password used to authorise the use of this method.

CampaignName: The campaign which all activities associated with the login will be associated with. If blank or invalid no campaign tracking is initiated.

CampaignSegment: The campaign segment which all activities associated with the login will be associated with. If blank or invalid no campaign tracking is initiated.

AuthorizingAccountName: The name of the authorizing account.

AuthorizingAccountPassword: The password of the authorizing account

ApplicationName: The name of the management group which provides application-level access control.

NewAccountName: The username of the new account.

NewPassword: New account password.

AccountOwner The GUID of the person or organisation that is associated with this new account.

EmailAddress: Account owners Email Address.

PermissionstoSet: The permissions to give to the new account owner.

CreateGlobalAccessCode: A boolean value to control global access to response devices.

AccountStatus: The status of an account, which can be either “ActivationPending”, “Active” or “Inactive”.

ConfirmationEmailTemplateName: Should be PWS_ACCOUNT_ACTIVATE_REQUEST, unless otherwise discussed. This will generate the account activation request email to the user, which allows for verification of the request before the account is activated.

MergeEntities: An array of merge entities which dictate the database tables where the contents of dynamically populated email template fields are sourced from.

MergeFields: An array of custom merge fields which dictate the database fields where the contents of dynamically populated email template fields are sourced from.

ResponseDevices: An array of response devices which will be used to allow access to objects such as an online form.

CampaignSegment_RSN: The unique identifier (GUID) of the CampaignSegment.

Returns

An integer indicating the returned result/error.

Sample Code

Using passportsvc As New PassportService.PassportSvc

'===== Create a new passport account =====

Dim results As Integer

results = passportsvc.CreateAccountForAccountOwnerWithConfirmation2WithCredentials( _

Key, AuthPassword, CampaignName, CampaignSegment, AuthorizingApplicationName, _

AuthorizingAccountName, AuthorizingAccountPassword, ApplicationName, NewAccountName, _

NewPassword, AccountOwner, EmailAddress, PermissionsToSet, CreateGlobalAccessCode, _

AccountStatus, ConfirmationEmailTemplateName, MergeEntities(), MergeFields(), _

ResponseDevices(), CampaignSegment_RSN)

If results = 0 then

‘===== Successfully Created Account =====

Else

‘===== Implement error handling code here =====

End If

End Using

Web Service Method – ActivateAccount

This method takes several input variables and returns a Passport ActivateAccountResult object.

Parameters

Token: Token supplied by logging into the Passport Web Service

AuthPassword: The password used to authorise the use of this method.

AccountActivationRequest_RSN: The GUID that was passed back to the account holder upon creation of a new account. This is used for verification purposes.

EmailTemplateName: Should be PWS_ACCOUNT_ACTIVATE_CONFIRM, unless otherwise discussed. This will generate the account activation confirmation email to the user.

ResponseDevices: An array of response devices which will be used to allow access to objects such as an online form.

CampaignSegment_RSN: The unique identifier (GUID) of the CampaignSegment.

Returns

A passport object of class “ActivateAccountResult” with an error code embedded within.

Sample Code

Using passportsvc As New PassportService.PassportSvc

'===== Activate a recently created passport account =====

Dim results As PassportService.ActivateAccountResult

results = passportsvc.ActivateAccount(Token, AuthPassword, _ AccountActivationRequest_RSN, EmailTemplateName, ResponseDevices(), _ CampaignSegment_RSN)

If results.ErrorCode = 0 then

‘===== Successfully Activated Account =====

Else

‘===== Implement error handling code here =====

End If

End Using

Web Service Method – Login

This method takes several input variables and returns a Passport LoginResult object.

Parameters

Key: Client ID (type GUID)

AuthPassword: The password used to authorise the use of this method.

CampaignName: The campaign which all activities associated with the login will be associated with. If blank or invalid no campaign tracking is initiated.

CampaignSegment: The campaign segment which all activities associated with the login will be associated with. If blank or invalid no campaign tracking is initiated.

ApplicationName: The name of the management group which provides application-level access control.

AccountName: The username used to validate credentials.

Password: The password used to validate credentials. Optional WHEN Authorised Username and Password is provided. This allows the client database to maintain master username and passwords and Simplicity to be a slave without storing any passwords.

TokenValidDuration: The duration the token is valid (in seconds).

LoginModel: The type of model to use (MultipleLogins, SingleLogin, RoamingLogin)

Additional Notes:

MultipleLogins: Allows multiple concurrent tokens.

SingleLogin: If the user has an active token then an error (1016) is returned.

RoamingLogin: If the user has an active session then the token is expired and a new token is issued.

Returns

A passport object of class ‘Login Result’ with a token, error code, account name, and email address. It also returns the account RSN, the account Owner RSN, type and display value, and the account permissions.

Permissions

AccountName must be an Active account. AccountName must have a password specified.

Sample Code

Using passportsvc As New PassportService.PassportSvc

'===== Login to passport account =====

Dim results As PassportService.LoginResult

results = passportsvc.Login(Key, AuthPassword, CampaignName, _ CampaignSegment, ApplicationName, AccountName, Password, _ TokenValidDuration,LoginModel)

If results.ErrorCode = 0 then

‘===== Successfully Logged In =====

Else

‘===== Implement error handling code here =====

End If

End Using

Web Service Method – ResetPasswordRequest

This method takes the token of a session and applicable parameters (shown below) to request a reset of the password for the specified AccountName.

Parameters

Token:Token supplied by logging into the Passport Web Service

AuthPassword: The password used to authorise the use of this method.

ApplicationName: The name of the management group which provides application-level access control.

AccountName:Name of the account for which to reset the password.

EmailTemplateName: Should be PWS_PASSWORD_RESET_REQUEST, unless otherwise discussed. This will generate the password reset request confirmation email to the user.

ResponseDevices:An array of response devices which will be used to allow access to objects such as an online form.

CampaignSegment_RSN: The unique identifier (GUID) of the CampaignSegment.

ResetPasswordRequestValidDuration: Sets the allowable time in which the request may be confirmed (in milliseconds), otherwise it will expire and require a second request to be submitted.

Returns

A Passport object of class ResetPasswordRequestResult, which has a Reset Password Request RSN GUID and a results/error code. The GUID returned will need to be passed back for verification using the SetPasswordFromResetPasswordRequestweb method.

Permissions

Account associated with Token must have ‘Reset Password’ rights.

Sample Code

Using passportsvc As New PassportService.PassportSvc

'===== Request reset of account password =====

Dim results As PassportService.ResetPasswordRequestResult

results = passportsvc.ResetPasswordRequest(Token, AuthPassword, _

ApplicationName, AccountName, EmailTemplateName, ResponseDevices(), _ CampaignSegment_RSN, ResetPasswordRequestValidDuration)

If results.ErrorCode = 0 then

‘===== Successfully Submitted Reset Request =====

Else

‘===== Implement error handling code here =====

End If

End Using

Web Service Method – CancelResetPasswordRequest

This method takes the token of a session and applicable parameters (shown below) to cancel a previous request to reset the password for an account associated with the ResetPasswordRequest_RSN.

Parameters

Token: Token supplied by logging into the Passport Web Service

AuthPassword: The password used to authorise the use of this method.

ResetPasswordRequest_RSN: Passes the GUID received from the original Reset Password Request back in to identify which reset request to cancel.

Returns

A Passport object of class “CancelResetPasswordRequestResult”, which has an error code.

Sample Code

Using passportsvc As New PassportService.PassportSvc

'===== Cancel reset request of account password =====

Dim results As PassportService.CancelResetPasswordRequestResult

results = passportsvc.CancelResetPasswordRequest(Token, AuthPassword, _

ResetPasswordRequest_RSN)

If results.ErrorCode = 0 then

‘===== Successfully Canceled Reset Request =====

Else

‘===== Implement error handling code here =====

End If

End Using

Web Service Method – SetPasswordFromResetPasswordRequest

This method takes the token of a session and applicable parameters (shown below) and sets the password for the account passed into the previous ResetPasswordRequest method call.

Parameters

Token: Token supplied by logging into the Passport Web Service

AuthPassword: The password associated with the key.

ResetPasswordRequest_RSN: Passes the GUID received from the original Reset Password Request back in for verification.

NewPassword: New Password of account

EmailTemplateName: Should be PWS_PASSWORD_RESET_CONFIRM, unless otherwise discussed. This will generate the password reset confirmation email to the user.

ResponseDevices: An array of response devices which will be used to allow access to objects such as an online form.

CampaignSegment_RSN: The unique identifier (GUID) of the CampaignSegment.

Returns

An object of typeSetPasswordFromRequestResult.

Sample Code

Using passportsvc As New PassportService.PassportSvc

'===== Request reset of account password =====

Dim results As PassportService.SetPasswordFromRequestResult

results = passportsvc.SetPasswordFromResetPasswordRequest(Token, _ AuthPassword, ResetPasswordRequest_RSN, NewPassword, _ EmailTemplateName, ResponseDevices(), CampaignSegment_RSN)

If results.ErrorCode = 0 then

‘===== Successfully Reset Password =====

Else

‘===== Implement error handling code here =====

End If

End Using

Web Service Method – SetPassword

This method takes the token of a session and applicable parameters (shown below) and sets the password of that account to whatever is provided as NewPassword.

Parameters

Token: Token supplied by logging into the Passport Web Service

AuthPassword: The password used to authorise the use of this method.

ApplicationName:The name of the management group which provides application-level access control.

AccountName:Name of the account for which to reset the password.

OldPassword:Current password of account

NewPassword:New Password of account

Returns

An integer indicating the returned result/error.

Permissions

Account associated with Token must have ‘Change Password’ rights.

Sample Code

Using passportsvc As New PassportService.PassportSvc

'===== Change Account Password =====

Dim results As Integer

results = passportsvc.SetPassword(Token, AuthPassword, ApplicationName, _ AccountName, OldPassword, NewPassword)

If results = 0 then

‘===== Successfully Changed Password =====

Else

‘===== Implement error handling code here =====

End If

End Using

Web Service Method – SetEmailAddress

This method takes the token of a session and applicable parameters (shown below) and sets the new email address of that account to whatever is provided as EmailAddress.

Parameters

Token: Token supplied by logging into the Passport Web Service

AuthPassword: The password used to authorise the use of this method.

ApplicationName:The name of the management group which provides application-level access control.

AccountName:Name of the account for which to reset the email address.

EmailAddress:The new email address for the account specified

Returns

An integer indicating the returned result/error.

Permissions

Account associated with Token must have ‘Change Email Address’ rights.

Sample Code

Using passportsvc As New PassportService.PassportSvc

'===== Change Account Email Address =====

Dim results As Integer

results = passportsvc.SetEmailAddress(Token, AuthPassword, _ ApplicationName, AccountName, EmailAddress)

If results = 0 then

‘===== Successfully Changed Email Address =====

Else

‘===== Implement error handling code here =====

End If

End Using

Passport Application Web Service – Result/Error Codes

‘Label Code’ refers to the Token as it is stored in the database.

‘Token’ refers to the Token as it is stored in the passport application.

0 OK

1001 Exception

1002 Invalid Campaign

1003 Ambiguous Campaign

1004 Invalid Campaign Segment

1005 Ambiguous Campaign Segment

1006 Duplicate Label Code:

1007 Invalid Old Password

1008 Invalid Password

1009 Invalid Email Address

1010 Invalid Account Name

1011 Duplicate Account Name

1012 Invalid Name

1013 Account Status Active

1014 Account Status Inactive

1016 User already has an active token

3001 Invalid Token

3004 Insufficient Privileges

3006 Maximum Session Requests Exceeded

3007 Invalid Credentials

Frequently Asked Questions

Can the Passport Application web service be used without the Data Integration web service?

Yes.

In using the usernames and passwords do all email addresses in the database need to be unique?

The email addresses associated with an account don’t need to be unique, but the username does.

Do you record the login stats?

The Passport Web Services run alongside Simplicity. Each user account is linked back to Simplicity, and it is there that the login stats are recorded.

Can anyone create an account?

Only accounts with the appropriate permissions. An account with the ‘Create Account’ permissions can. If you set up a website with a ‘general’ account, then yes, users using that account would be able to create new accounts.

What permissions are there?

The available permissions for an account are as follows:

• None No permissions.
• CreateAccount Can create a new account.
• DeleteAccount Can delete an existing account.
• EnableAccount Can enable an account that is disabled.
• DisableAccount Can disable an account that is enabled.
• SetPassword Can set a new password.
• ResetPassword Can reset an existing password.
• SetEmailAddress Can set an Email Address on an account.
• AccessDataIntegration Can access the Data Integration information.
• AlterAccount Can set or reset account permissions.

It is highly recommended that only a trained developer with experience in VB.NET implement the framework into a web form to be used by an average user.