How SSO Works in WhosOnLocation
About Single Sign-on
By default, your administrators and users are authenticated and logged in using
WhosOnLocation’s user authentication. You can however bypass this and require your administrators and users to log in via single sign-on using WhosOnLocation Remote Authentication or SAML (available in all accounts).
Single sign-on is a mechanism that allows you to authenticate users in your systems and subsequently tell WhosOnLocation that the user has been authenticated. The user is then allowed to access WhosOnLocation without being prompted to enter separate login credentials.
When using single sign-on the authentication process is handled outside of the WhosOnLocation application, you verify the identity of the user and then let our application know in a secure fashion.
WhosOnLocation supports two methods of single sign-on.
1. Secure Assertion Mark-up Language (SAML) 2.0, which allows you to provide single sign-on to WhosOnLocation using enterprise identity providers such as Active Directory and LDAP or choose a 3rd party SAML service such as Okta, OneLogin, and PingIdentity.
2. A JSON Web Token is forwarded by your system to securely identify the user.
Setting up single sign-on with SAML
After you've enabled SAML (by building a SAML server yourself or by using one of the SAML services), all user management and authentication is handled outside of your WhosOnLocation. This can be paired with our Active Directory Sync feature to automatically add/change/delete users in your WhosOnLocation account.
The only user data that is stored in WhosOnLocation is the user name and email address. However, you can also choose to sync the following user data: phone,
location, given name, surname, and role. You do this with by adding these attributes to your SAML assertion code.
How SAML for WhosOnLocation Works
SAML for WhosOnLocation works the way SAML does with all other service providers. The typical use case is that your users belong to a corporation and all user
authentication is managed by your corporate authentication system (for example, Active Directory or LDAP), which is referred to generically as an identity provider (IdP).
After you've enabled SAML as the type of single sign-on for your WhosOnLocation, users who visit your WhosOnLocation and attempt to log in are redirected to your SAML server for authentication. Your users' identities can be stored either on the SAML server or can be validated by an identity directory such as Microsoft Active Directory or LDAP. Once authenticated, users are redirected back to your WhosOnLocation and
Configuring Your SAML Implementation
You have a number of options when considering a SAML service, including building a SAML server in-house (for example, OpenAM) or choosing a SAML service such as Okta, OneLogin, and PingIdentity.
To set up SAML in your WhosOnLocation, you'll need the following:
A SAML server with provisioned users or connected to an identity repository such as Microsoft Active Directory or LDAP
The Remote Login URL for your SAML server (sometimes called SAML Single Sign-on URL)
The SHA1 fingerprint of the SAML certificate from your SAML server
After you have your SAML server properly configured, you use the remote login URL and the SHA1 fingerprint to configure SAML within your WhosOnLocation.
User Attributes That Can Be Set In SAML
You can set the following user attributes for users signing in via SAML:
Attribute Description
email Email of the user being signed in, used to uniquely identify the user record in WhosOnLocation.
givenname The user’s first name surname The user’s last name location The user’s home location
phone A phone number (DDI), specified as a string.
mobile A mobile number, specified as a string.
Enabling SAML Single Sign-On In Your WhosOnLocation
With your SAML server configured and the information you need for setting up SAML in WhosOnLocation at hand, log in to your WhosOnLocation as an administrator and follow this procedure.
To enable SAML in your WhosOnLocation fill out the following options on your WhosOnLocation security page.
SAML SSO URL This is the URL that WhosOnLocation will invoke to redirect users to your Identity Provider.
Remote logout URL This is the URL that WhosOnLocation will return your users to after they log out.
IP Range The IP range for which WhosOnLocation will redirect to your Identity Provider.
Setting up single sign-on with JWT (JSON
Web Token)
JWT, a widely adopted open standard, provides a flexible framework for creating a custom SSO solution.
At the core of single sign-on is a security mechanism that allows WhosOnLocation to trust the login requests it gets from your systems. WhosOnLocation only grants access to the users that have been authenticated by you. WhosOnLocation SSO relies on a technology called JSON Web Token (JWT) for securing the exchange of user authentication data.
JWT Implementation Code Examples
The actual JWT implementation is straight forward and most modern languages have libraries available. WhosOnLocation provides examples for various web languages or you can develop your own to follow the simple format.
The Single Sign-On Authentication Process
Once you enable single sign-on, login requests are redirected to a remote login URL which is able to identify the user. This is usually a webserver within your network or DMZ which is part of your authenticated domain. The webserver does not need to be publicly accessible from the Internet and we do not have any remote access to it. The user’s browser is simple redirected to the URL specified and then gets redirected back to WhosOnLocation with the secure identity appended.
Here are the steps of the single sign-on authentication process:
1. An unauthenticated user (not already logged in) navigates to your WhosOnLocation URL.
2. The WhosOnLocation SSO mechanism recognizes that SSO is enabled and that the user is not authenticated.
3. The user is redirected to the remote login URL configured for the SSO settings (for example, https://myintranet.company.com/WhosOnLocation/sso).
4. A script on your side authenticates the user using your proprietary login process (eg. IIS + Active Directory).
5. Your script builds a JWT request that contains the relevant user data. 6. You redirect the customer back to the WhosOnLocation application at
https://login.whosonlocation.com/login/jwt with the JWT payload.
7. WhosOnLocation verifies the payload has come from the customer using the shared secret key and then grants the user a session.
As you can see, this process relies on browser redirects and passing signed messages using JWT. The redirects happen entirely in the browser and there is no direct
CONFIGURING YOUR JWT IMPLEMENTATION
To perform SSO for a user, you need to send several required user attributes to WhosOnLocation as a hash. Most importantly, WhosOnLocation requires an email address to uniquely identify the user.
Beyond the required attributes, which are shown in the table below, you may optionally send additional user profile data. This data is synced between your user management system and WhosOnLocation.
Attribute Mandatory Description
iat Yes Issued At. The time the token was generated, this is used to help ensure that a given token gets used shortly after it's generated. The value must be the number of seconds since UNIX epoch. WhosOnLocation allows up to two minutes clock skew, so make sure to configure NNTP or similar on your servers.
jti Yes JSON Web Token ID. A unique id for the token, used by WhosOnLocation to prevent token replay attacks.
Name Yes The name of this user. The user in WhosOnLocation will be created or updated in accordance with this.
email Yes Email of the user being signed in, used to uniquely identify the user record in WhosOnLocation.
phone No A phone number (DDI), specified as a string.
mobile No A mobile number, specified as a string.
Most JWT implementations take a hash and a secret, and return a plain string payload to send to the other side. For context, here's an example in Ruby:
payload = JWT.encode({
:email => "[email protected]", :name => "Bob",
:iat => Time.now.to_i, :jti => rand(2<<64).to_s }, "Our shared secret")
response.headers["Location"] =
"https://login.whosonlocation.com/login/jwt?jwt=#{payload}"
ERROR HANDLING
If WhosOnLocation encounters an error while processing a JWT login request, it will report a message that explains what the issue is. A standard login form will be
ADDITIONAL INFORMATION ABOUT JWT
JWT is a recent open standard that is being driven by the international standards body IETF and has top-level backers from the technology sector (for example, Microsoft, Facebook, and Google).
The fundamental building blocks of JWT are very well understood components and the result of this is a fairly simple spec, which is available here
http://tools.ietf.org/html/draft-jones-json-web-token-10. There are a lot of open source implementations of the JWT
spec that cover most modern technologies. This means that you can get JWT single sign-on set up without much difficulty.
One thing to be aware of is that the JWT payload is merely encoded and signed, not encrypted, so don't put any sensitive data in the data table. JWT works by serializing the JSON that is being transmitted to a string. It then base 64 encodes that string and then makes an HMAC of the base 64 string which depends on the shared secret. This produces a signature that the recipient side can use.
If you require any further information about SSO for WhosOnLocation please contact us on:
Email: [email protected] Thank you.
