Copyright: WhosOnLocation Limited

Transcription

1 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 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). The service provider (SP), in this case of course WhosOnLocation, establishes a trust relationship with IdP and allows that external IdP to authenticate users and then seamlessly log them in to WhosOnLocation. In other words, a user logs in at work and then has automatic access to the many other corporate applications such as , your CRM, and so on without having to login separately to those services. Aside from the convenience this provides to users, all user authentication is handled internally by a system that you have complete control over.

2 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 automatically logged in.

3 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 Signon 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 givenname surname location phone mobile Description of the user being signed in, used to uniquely identify the user record in WhosOnLocation. The user s first name The user s last name The user s home location A phone number (DDI), specified as a string. 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 Remote logout URL IP Range Certificate Fingerprint This is the URL that WhosOnLocation will invoke to redirect users to your Identity Provider. This is the URL that WhosOnLocation will return your users to after they log out. The IP range for which WhosOnLocation will redirect to your Identity Provider. The SHA1 fingerprint of the SAML certificate, obtain this from your Identity Provider.

4 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, 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 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 connection between WhosOnLocation and your systems, so you can keep your authentication scripts safely behind your corporate firewall..

5 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 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. Yes 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({ : => "bob@example.com", :name => "Bob", :iat => Time.now.to_i, :jti => rand(2<<64).to_s }, "Our shared secret") response.headers["location"] = " 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 presented to allow the user or administrator to log in manually (if they have a password set).

6 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 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: helpdesk@whosonlocation.com Thank you. WhosOnLocation Support Team