Under Construction...
I get no benefit (neither directly nor indirectly from Personify) for writing this. This is my own interest and my indention is to share my snippet of work so that others can benefit rather than writing the same from scratch. This work is not fully hand written by me, but its collection of script over the period of time. Meaning this is not a copy paste of work from somewhere else. But Its hard work collection of work and combined into single piece to make personify api interaction easy.
It's AMS System. But, I must also say, i have no IDEA what PERSONIFY is or can do. I never worked with Personify directly. Its all through vendor. Meaning, the whole thing starts when our client says their AMS is Personify. They will share us their set of vendor credentials and other required configuration values (test logins for sso) and that's it. So all my experience here was about one time study of their Web services. After studying I had come up with core CFML components for Personify SSO integrations. In my experience, I had about 10 personify clients setup using my core implementation. I have no idea how many are running right now.
And this is what I could find on personify sso.
Personify Single Sign-On provides a means for organizations to facilitate movement of their members and customers between their organization website and the websites of their third-party vendors and partners.
Personify SSO provides associations and their vendor websites with a single sign-on (login) service, eliminating the need for separate logins and providing users with a personalized and seamless interface across the sites. A centralized database stores and maintains the required login information for the users for each website. Web services interact with this database to provide an Internet interface that allows websites to request login and other authentication data. All sites must implement an interface to call the centralized web services. The Personify database is the primary source for member and customer information for associations, including demographics information and web access-related data (i.e., user IDs and passwords). When I started this, I hated personify so much because no other SSO that I worked before had these many calls and such complex input and output results.
Another reason was lack of api knowledge base or wiki kind of pages. There are few AMS systems out there that provides at least single page SSO help pages.
But accidentally i stumped upon some help pages such as this one http://pfy.carpenters.org/OnlineHelp/mergedProjects/sso/index.htm
I had no idea, whether its their official or some vendor page etc.. But i was only happy that i found and started getting some sense about how Personify works.
In the beginning its all scary because they listed out so many web service methods.
One would really wonder, why its all necessary for simple SSO.
But that;s the fact. Many api's out there, dont provide their API help pages just for one single module.
So the Web services are nothing but "the whole AMS".
This is what I like about how they said they do their SSO.
Using SSO, a website will send a request to the web service when a user first attempts to log into the site. If a user goes to another participating site after logging in, the new site sends a request to the web service and receives confirmation that the user is already logged on, maintaining the common login. Sites also interact with the web service by automatically updating user information if it changes on any participating site. Okey, there are three web services provided by personify.
In order to get the sso done, personify maintains separate database it seems. And whatever happens during sso handshake between association website (AMS), vendor and personify. Its mainly like communication layer between the vendors and SSO. The vendors should consume this SSO Web Services to get into respective SSO domain and retrieve SSO/Personify-related data.
In order to get the sso done, personify maintains separate database it seems. And whatever happens during sso handshake between association website (AMS), vendor and personify. Its mainly like communication layer between the vendors and SSO. The vendors should consume this SSO Web Services to get into respective SSO domain and retrieve SSO/Personify-related data.
Identify Management Service (IMS), is not a mandatory web service or atleast for sso. We had clients who does not have/provide IMS service details meaning they dont want to share/integrate their users member information or how their business rules controlled member roles. Personify says Integrating the IMS to the vendor website enriches the user’s experience and controls access to the vendor’s website.
It's not every vendor sites requires to drive the workflow based on what sso defines as logged in user roles. But if it does than that where the IMS service comes in handy. For simple login flow (sso) does not require this service to be exposed to the vendor and i guess that's the model we see here.
The IMS database holds all the necessary information about the IMS components. The role definitions, role assignments, and vendor access to those roles are defined and stored in the IMS databases. Please note that the IMS database is part of the SSO database and must be implemented on top of the SSO database to function properly.
The IMS set up is something like a windows service sync-ing data between personify database and IMS database for user roles. It comes with both web service (for vendors) and web app (for configuration). But these details are just beyond the sso but what IMS itself in personify world.
Is the one who is trying to use the existing AMS (Personify) login system for authentication.
Is the one who is trying to get info vendor site (using their AMS login/authentication).
Below are the list of web methods found in their web service description.
But definitely we don't need all of them for getting the SSO done. We will see that later we when on code walk through.
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
SSOCustomerRegister – Allows a vendor to register a customer with SSO.
AuthorizeAccess – Authenticates vendors’ credentials and then authorizes their access to a particular web service.
TIMSSCustomerIdentifierGet – Provides the Personify Customer Number. Must be called with a valid Customer Token. The Personify Customer Number is needed when calling the Data Access web services to get more customer information. This would be normally called by vendors who do not have their own identifier for a customer via VendorSSOCustomerIdentifierGet.
VendorTokenEncrypt – Returns the encrypted Vendor Token. This method allows a vendor to create a valid token without having to implement Rijndael encryption.
VendorSSOCustomerIdentifierSet – Allows vendors to determine how they identify a customer. The identifier is a custom identifier which SSO associates with this customer for a particular vendor.
CustomerTokenDecrypt – Returns the decrypted Customer Token. This method allows a vendor to decrypt a Vendor Token without having to implement Rijndael decryption.
SSOCustomerTokenIsValid – Verifies that the customer’s token is valid. Tokens are single use. A new token is returned if the provided token is valid.
SSOCustomerAuthenticate – Allows a vendor to authenticate a customer’s credentials with SSO.
VendorSSOCustomerIdentifierGet – Provides the vendor’s identifier for a customer. Must be called with a valid Customer Token.
SSOCustomerLogout – Logs the customer out of SSO. All Customer Tokens for this customer are no longer valid after they log out.
SSOCustomerGetByEmail – Gets the SSO customer record. The service accepts email ID as the parameter. If two customers are sharing the same email record, this will throw an exception.
SSOCustomerGet - Gets the SSO customer record. The service accepts Timss Customer ID (Combination of Master Customer Id and sub Customer Id) as the parameter.
SSOCustomerGetByUsername - Gets rthe SSO customer record. The service accepts user name as the parameter. This function is to be used if the customer allows duplicate email records.
SSOCustomerGetByCustomerToken – Gets the SSO customer record. The service accepts customer token as the parameter.
SSOCustomerAuthenticate – Authenticates the customer and returns the vendor ID. The function does not authenticate if the account has been disabled.
SSOCustomerUpdateEmail – Updates the customer's email. This service accepts email as the parameter. If two customers are sharing the same email record, this will throw an exception.
SSOCustomerUpdatePassword - Updates the customer's password. This service accepts email as the parameter. If Two customers are sharing the same email record, this will throw an exception.
SSOCustomerUpdateUserName - Updates the customer's user name. This service accepts email as the parameter. If two customers are sharing the same email record, this will throw an exception.
SSOCustomerUpdateEmailByTimssID – Updates the customer's email address using Master Customer ID and Sub Customer ID. This is a Personify-specific web service and should not be used by other vendors.
SSOCustomerUpdateEmailByUserName – Updates the customer's email address using the User Name as the input parameter. If clients are allowing duplicate emails for their SSO accounts, this is the web service they should use to update email for a customer.
SSOCustomerUpdateUserNameByTimssID - Updates the customer's user name using Master Customer ID and Sub Customer ID. This is a Personify-specific web service and should not be used by other vendors.
SSOSendPasswordReset – Sends an email to the customer to reset their password. This service requires email address only for reset password. Clients should use this service only if duplicate emails are not allowed in their system.
SSOSendPasswordResetByUserName - Sends an email to the customer to reset their password. This service requires email address and user name for resetting the password. Clients should use this service only if duplicate emails are allowed in their system.
SSOEnableDisableCustomerAccount – Enables or disables the customer's account. Once the account is disabled, the user will not be able to log in.
Very limited set of methods for getting the customer details.
This stage happens after successful sso roundtrip. Meaning, customer trying to get into vendor site, and vendor site redirects to personify AMS for authentication and there customer logs in, validated and customer has been returned to vendor site.
Now vendor site, validate itself against sso web service and gets the confirmation about the recently logged in user (that vendor had redirected) and then makes subsequent calls to "Data Services" to retrieve the customer (logged in user) information such as "his/her Personal data".
The worst part of this service is that we need to make multiple calls (endpoints) to get the customer personal information.
Meaning they have separate end point for retrieving "Email", "Phone" and "Address". Funny! but one might have that is one of securing the personal data flying over a single call. Whatever its funny to me!
To get customer or user information:
i. CustomerInformationGet- will get a customer name (first name, last name, age etc..).
ii. CustomerAddressGet- will get customer address.
iii. CustomerPhoneGet- will get customer phone.
iv. CustomerMembershipGet- will get customer membership details.
Very limited set of methods for getting the customer/user/logged in person roles.
To get Roles enabled for a Vendor:
i. IMSVendorRolesGet - will get a list of all roles.
ii. IMSVendorWebRolesGet - will get a list of web-enabled roles.
b. To get Roles a Customer Qualifies for:
i. IMSCustomerRolesGet - will get a list of all roles.
ii. IMSCustomerWebRolesGet - will get a list of web enabled roles.
iii. IMSCustomerRoleGetByTIMSSCustomerID - will get the customer roles but requires the valid Personify customer ID to get the role assignments.
Default
instance.meta.vendorusername = "vendorUsername";instance.meta.vendorpassword = "vendorPassword";instance.meta.vendorblock = "vendorBlock";instance.meta.vendoridentifier = "1";/auth/customer/auth/vendor/candidate/customers/customers/{id}/customers/{id}/activities/customers/{id}/relationships/customers/{id}/roles/membershipOrders/productsAbility to consume web services.
Ability to encrypt/decrypt data using Rijndael/AES encryption algorithm.
-----------------------------------------------------------------------------------------------------------
Personify Single Sign-On uses the following standards:
Kerberos type model for password-based tokens and replay mitigation
SSL, HTTPS
SOAP, WSDL, XML, XML SCHEMA
AES - Rijndael