Implementing Single Sign-On (SSO) from another website
Tip: If you are running WordPress, you can use our Single Sign On for GoToMyAccounts plugin.
Single Sign-On (SSO) allows you to link seamlessly to your GTMA portal from another website. We provide sample code so you can easily implement this on various platforms. The SSO system we implemented requires the super user set a SSO Master Password inside your portal. You will set this as a parameter in the sample code as well as the portal URL.
What does SSO allow me to do?
If you have an existing website or portal that requires users to logon (and their email is stored as part of their logon/profile), SSO will pass that information as well as the SSO Master Password to your GTMA portal and automatically log that user into any page you want to link to. A good example might be to provide your users direct access to their invoices. The remainder of this document is written for developers and contains the technical information required for implementation.
How to setup SSO with your portal (for developers)
There are currently three sample code files in our SSO sample code repository and you can use those as your starting point. The samples we have created are PHP, ASP.net, and Legacy ASP. We may create additional samples as needed. You can also look at the existing samples and port them to other languages very easily.
- In your web portal, on the left side menu, click Integrations, and then click "SSO Tokens". (requires admin permissions).
- On the SSO Tokens page, you can create new tokens and remove existing tokens. You cannot edit or view existing tokens. This is a security feature. Because of this, you must copy the token and save it in a safe place. Copy the SSO token and paste it into your SSO code (see example code).
- In your SSO code, you will also set the portal URL. This can either be something like "myco.gotomyaccounts.com", or if you use a custom domain it can be anything you may have setup for your own domain.
- The sample files are named "gtma-redirect.xxx" however you can name this file whatever you like. You will be using this file as a redirector for all links you wish to point to in your portal. When using this file to redirect your users, you will set the target page in the portal. For example, a link might look like:
<span data-mce-style="font-size: small;" style="font-size: small;"><br> <span data-mce-style="font-family: courier new,courier;" style="font-family: courier new,courier;">gtma-redirect.php?target=invoices.html</span></span>
Note: DO NOT generate or post to our servers on all your pages. Always use the redirect page as your link and have that page handle the SSO processing. This will give you MUCH better performance.
- The ONLY other parameter you must modify in the sample code is where the user's email address is set. Normally, you can get this parameter from the session your user is logged in with. Whatever method you choose, it is VERY important that users cannot access the redirect page unless they are logged in through some password protection schema. Never allow the redirect page to execute without your user logged in.
- If you look at the sample code, you will see that the process involves retrieving a token from the portal server and this is passed back to our server when the redirect begins. The token is stored in our database and is a serialized datetime stamp (epoch time). It is usable for only 20 seconds once it is generated. it is valid only for that one user you are authenticating in the link. The SSO master password must match as well as the email address for the user. Note: SSO will only work for those users who have a unique email address in your customer list. You can try passing in a username if you set one for a user in the portal, but that method is beta at this time.
- If you receive "Invalid Response" when you attempt to use the link, this means our server failed to return a valid token. Check your SSO Token, your portal URL, and make sure the email address being passed in is valid. Also, make sure your user is not suspended and enabled for access in the portal.
- Most pages should handle the redirect just fine. If you receive a 404 error or run into some other problem, please open a support ticket so we can assist you.