Administrator Guide JustSSO is a Single Sign On (SSO) solution specially developed to integrate Google Apps suite to your Directory Service. Product developed by Just Digital v 11
Index Overview... 3 Main Requisites... 3 Information you will need before proceed... 4 Step 1 Just SSO configuration: VM s network and NTP parameters... 6 Step 2 JustSSO configuration: communication with Directory Service and Google Apps... 9 Step 3 Google Apps configuration: enabling and configuring SSO... 13 Optional Enabling Provisioning API in Google Apps... 15 Optional Layout... 16 Optional User mapping... 18 Optional Captcha... 21 Final considerations... 22 Page 2 of 22
Overview To use Just Digital Single Sign On (SSO) integrated to your Google Apps, you must satisfy the requirements described in this document. The setup process consists of 3 main steps: 1. VM installation and configuration of basic connectivity parameters: IP address, subnet mask, gateway, DNS and NTP. 2. JustSSO configuration, in order to: a. Communicate to your directory server and then be able to validate the accesses attempts and eventually update their passwords; b. Communicate to your Google Apps and then authorize the access that were validated and eventually replicate their passwords in the cloud. 3. Google Apps configuration in order to enable SSO function in your company domain. Before start the installation process, we recommend that you: Read the full setup guide. Assure that all requisites are satisfied. Have in hands all parameters demanded on this guide. Main Requisites Use Google Apps Business Edition or Education Edition Have VMWare installed, with the minimal amount of 512MB de RAM available to allocate to JustSSO virtual machine instance (1GB RAM recommended) and 5 GB of available disk space. The product is already tested and homologated to VMWare ESX 3.0 and VMWare Player. Configure Just SSO to communicate: o With your Directory Service, i.e.: MS Active Directory or OpenLDAP. o With your Google Apps domain. Configure, in your Google Apps domain console: o Single Sign On (SSO) settings o Optional: Enable the Provisioning API. As Google Apps will communicate with Just SSO, is necessary that Just SSO is reachable externally, otherwise, just people with access to its network will be able to authenticate and access Google Apps products. Take that in consideration when deciding the local (and IP address) where JustSSO VM will be placed. In case your company wishes to use the Password Replication to Google Apps feature, this VM should be able to access apps-apis.l.google.com through 443 port (https). In case you choose to use the Captcha feature, the VM should be able to access api-verify.recaptcha.net through 80 (http) and 443 (https) ports. Eventually, it will be necessary to create or modify some firewall rules to allow this scenario to work. Page 3 of 22
Information you will need before proceed Parameter Value Domain It s you company main domain, typically the one used your e-mails address. e.g.: justdigital.com.br License count Inform how many Google Apps accounts license have your company bought for this domain Network settings for you Just SSO VM You may choose to use DHCP to the virtual machine (default option) or manually. In case you choose the second option, you need to access the VM Shell and log in as the user named configure with password justsso. Once you are logged in, one self-explanation page asking for the networking settings will automatically be displayed. Domain and valid (public) IP address to access Just SSO from outside This information is used when configuring Google Apps SSO settings. For instance, if your company domain is justdigital.com.br, you could request to your network team create a sub-domain named sso pointing to the IP address where Just SSO will be installed. In this scenario, we would have: Log in page at: https://sso.justdigital.com.br/justsso/auth Page presented after Sign out: https://sso.justdigital.com.br/justsso/auth/logo ut Password update page: https://sso.justdigital.com.br/justsso/account/ Have in mind that in order to use the HTTPS protocol (highly recommended), it ll be necessary to install a SSL certificate generated by a Certification Entity, like VeriSign for instance, corresponding to subdomain/domain to be used by Just SSO. In case you use a self-signed certificate, your users will receive browser alerts informing that the page certificates are not trustful. Currently, the certification installation is done by Just Digital support team. In order to us be able to do it, you should send to us the generated certificate file. Page 4 of 22
Before asking the certificate to a Certifying Entity, contact our support team to provide you the Certificate Signing Request (CSR) generated by the VM. Ports The ports used by JustSSO are: 22 to remote support through SSH by the Just Digital support team from our office IP address 201.6.245.117 (main) and 200.207.116.254 (secondary) 80 or 443 (recommended) to your users authenticate to Google Apps using JustSSO 8443 administrative console used to configure Just SSO 123 the Just SSO VM (or appliance) needs to have its time always up to date, because of that the product needs access to a NTP server to keep synchronized it internal clock. The NTP service is usually available through the port 123, but you can use a different port. Other info Check the section related to Just SSO settings in order to get more details about the parameters. You also find in this guide 2 tables with a list of parameters that must be informed. Page 5 of 22
Step 1 Just SSO configuration: VM s network and NTP parameters For security reasons, just connecting directly to the VM console it s possible to change parameters related to: IP address Subnet mask Gateway address DNS search suffix DNS servers NTP servers Once logged in, one self-explanation page will be presented. The following screenshots illustrate these possibilities. Figure 1: Connection to VM shell using vsphere Client. To log in and have access to the following interface, use these credential: login = configure and password = justsso Page 6 of 22
Figure 2: Default TCP/IP setting: automatic (DHCP). To alternate between automatic and manual mode, use Page Up and Page Down keys. Figure 3: Manual TCP/IP setting. Inform the IP address that the VM will use, its network mask and gateway address. Page 7 of 22
Figure 4: Option accessible by pressing F6 to inform DNS search suffix and up to (3) DNS servers. Figure 5: Option accessible by pressing F7 key to inform NTP servers address in order to make sure that JustSSO virtual machine internal clock is always correct. Otherwise, authentication and password replication will not work. Page 8 of 22
Step 2 JustSSO configuration: communication with Directory Service and Google Apps Configure JustSSO is quite simple. The main settings are related to 2 parameters sets that are in turn related to the communication from JustSSO to the directory service and to Google Apps. 1. Access https://ip_do_justsso_vm:8443/justsso-admin/ and inform the login and password provided for you by the time you bought the product. 2. In the page Directory Server Communication, you ll inform data that JustSSO needs to communicate to your directory service: Figure 6 - Page to configure Directory Server Communication Page 9 of 22
The following table gives you more details about each field on this page. Parameter Value Comments Directory Service Select the option that corresponds to the directory service that your company uses. It could be AD (from Microsoft) or OpenLDAP. Directory Service URL Base DN Login Example: ldaps://10.0.2.15:636 User s Base Distinguished Name. e.g.: cn=users,dc=yourdomain,dc=com Inform an account with access to your directory service, e.g.: CN=Admin,CN=Users,DC=yourdomain,DC=com Password Password (Confirmation) Security Authentication Security Protocol SSL Store key Email Attribute Name Domain name in Dir. Serv. Password Attribute Name It ll be necessary an account with operator privileges case you wish your users are able to update their password from Google Apps account settings page. Hint: It s convenient to create a login to be used just by this application to communicate to your directory service, because you use a login of a real user, when this user for some reason update his password, the system will stop working until the password is updated in the config form. Inform if it s Simple (default) or None. Default value is SSL Upload a certificate generated by your directory service to allow secure communication with Just SSO. Attribute name in your directory service that contains users' email addresses. e.g.: userprincipalname Inform this value in case your users e-mail addresses are saved in the previous field with a different domain name. For instance, instead of @justdigital.com.br it s @justdigital.local. It s possible to inform more than one domain putting a ; between them, e.g.: @justdigital.local;justdigital.intranet Attribute name in your directory service that contains users' passwords, e.g.: userpassword 3. Click in the button Save; 4. Click in the Google Apps Communication tab to provide information that Just SSO needs in order to it communicate with Google Apps: Page 10 of 22
Figure 7 - Page to configure communication between JustSSO and Google Apps. Page 11 of 22
The following table gives you more detail about each field of this page. Parameter Value Comments Domain Corresponds to your Google Apps domain. Domain administrator (email) Password Private key Public key Show intermediate page? Replicate user password after password change? Replicate user password after login? Optimize password replication to Google Apps? Example: justdigital.com.br Example: administrador@justdigital.com.br Upload here the private key that you generate or that you receive from Just Digital by e -mail. Upload here the public key that you generate or that you receive from Just Digital by e -mail. Check this option to show an intermediate page (with alerts, highlights, messages,...) just after user log in. Check this option if you want users' passwords to be replicated to Google Apps when those update their passwords using JustSSO. Note: If you check this option, you need to enable Provisioning API in your Google Apps Domain control panel. Check this option if you want users' passwords to be replicated to Google Apps when those sign in through JustSSO. Note: If you check this option, you need to enable Provisioning API in your Google Apps Domain control panel. Check this option if you are ok with users' passwords being cached (in an encrypted format) at JustSSO, which optimizes password replication process. This way, the password at Google Apps will be updated only when a value informed by the user is different from the cached copy. 5. Click in the Save button. 6. Ready, the configuration by Just SSO side is complete. Page 12 of 22
Step 3 Google Apps configuration: enabling and configuring SSO 1. Access your Google Apps Domain Control Panel (remember you need to have the Business, Education or Government edition). 2. Locate the option named Authentication under Advanced Tools page: 3. Click in the link Set up single sign-on (SSO) to open the following page: 4. Check in the option Enable Single Sign-on. 5. In the fields Sign-in page URL *, Sign-out page URL * and Change password URL *, you must inform the login page URL, the URL to which the users will be redirected after they logout from Google apps and the password update page URL respectively. As explained in the Information you will need before proceed section, a typical configuration would be: Sign-in page URL: https://subdomain.yourdomain/justsso/auth Sign-out page URL: https://subdomain.yourdomain/justsso/auth/logout Change password URL: https://subdomain.yourdomain/justsso/account/ Where subdomain.yourdomain is a DNS Appointment who targets to the JustSSO IP Address installed to your company, which is not unusual to be in the company data center. Note 1: In case you wish your users are redirected to the sign-in page when they sign-out from Google Apps, all you need to do is repeat the value used in the Sign-in Page URL field in the Sign-out page URL field. Page 13 of 22
Note 2: The Change password page available in Just SSO will update the password in your Directory Service Server (whatever it is MS Active Directory or OpenLDAP). It ll also update this password at Google Apps cloud in case you specify that in Just SSO settings (more details in the next section). Note 3: It s up to you to use or not the Change password page available in Just SSO. If your company doesn t want to use it, you just need to inform a URL pointing, for instance, to a page with instructions to your users on how to change their passwords. You can also point to the Change password offered by JustSSO and change its layout and content in a way that no form is presented. 6. In the field Verification certificate, you must upload the certificate file containing the public key that will be used by Google Apps to verify the login requests. This file must match the one you uploaded when configured the JustSSO instance that will be used to manage authentication to this domain. In order to simplify things for you, a private/public key pair generated specifically for your company will be sent to you through e-mail. However, you can choose to ignore it and create your private/public key pair by yourself. 7. Now click on Save Changes button to finalize the process. Page 14 of 22
Optional Enabling Provisioning API in Google Apps Google Apps has a feature called provisioning API that allows third-party systems (like JustSSO) performs action in your Google Apps domain, like replicate to the cloud the users passwords when they update their password in the company Directory Server using the JustSSO's Change password page or when the user sign in using JustSSO (in case these option are checked). This use may be interesting because in case your Directory Service Server, or machine where JustSSO is installed, became unavailable or unreachable (link problem, for instance), your Google Apps domain administrator may access your Google Apps Console and uncheck the SSO option. In these scenario, once SSO is disabled, users may continue to access their Google Apps services (e.g.: e-mail and calendars) as usual except that now they re authenticating themselves directly in Google Apps cloud. To use the feature, you should take the following steps and then enable the desired options at JustSSO configuration page. 1. Locate Enable provisioning API section at settings pages under Users and groups menu 2. Check Enable provisioning API option. 3. Now click on Save Changes button to finish the process. Page 15 of 22
Optional Layout You can customize the layout of the following pages: Login Intermediate page Change password Change password message page (it s displayed when the password is successfully updated) Logout To do that, it s needed to get the HTML code necessary to achieve the desired layout, including all images and CSS, beside some special tags needed to the product work properly. The code for these special Tags are available in the respective configuration pages that are in turn accessible from the Layout menu. HTML sample code to the Login page: <html> <head> <title>just Digital Webmail</title> <body> <h1>informe seu login e senha nos campos abaixo para acessar sua caixa de e-mail:</h1> $form.geterrors().tohtml() <form action="/justsso/auth/authenticate"> $form.get("samlrequest").render() $form.get("relaystateurl").render() Login: $form.get("username").render() <br/> Senha: $form.get("password").render() <br/> <input type="submit" value="login"/> </form> </body> </html> Page 16 of 22
Figure 12 This module allows you customize layout of the pages you want Page 17 of 22
Optional User mapping JustSSO provides an automatic mapping between Directory Service (e.g. MS Active Directory (AD)) and Google Apps accounts assuming that both have the same nomenclature. In other words, it is assumed that if a given account in AD is mfarias, his account in Google Apps would also be mfarias. On the other hand, if the user in AD is mfarias but if you want your e-mail account on Google Apps is marcos, it s necessary some place where you could create such mapping to establish equivalence between these accounts in a proper way. So, if a user whose login in AD is mfarias and in Google Apps is marcos, in JustSSO would be created a mapping the AD name mfarias (FROM) and the Google Apps name marcos (TO). Once done this registration, this mapping would have an initial Waiting for confirmation state. The confirmation would be made through a link sent to the marcos' Google Apps e-mail box. Once he gets this link, he will need to provide his password in AD and in case it is OK, the mapping would then change to an "Active" state. Such confirmation mechanism is needed in order to make the process secure, looking for assure the legitimacy of the created mapping. An example of inappropriate mapping is one in which an SSO administrator (John) could put a map of his AD account pointing to the Google Apps CEO (Paul) s account and access the e- mails without Paul has any clue of that. The way JustSSO s mapping mechanism works, Paul s e-mail box would receive a message warning that such mapping was created. As explained before, the mapping will just became valid in case the generated link included in the confirmation e-mail message is accessed. Anyway, it is noteworthy to point out that to access the e-mail with confirmation link, in case SSO is already in place, the user will have an initial limitation to access his mailbox via the web interface, once the mapping is not yet active and it can t authenticate with your AD user (e.g. mfarias) and be redirected to a different account id (e.g. marcos). In this case, the user would have to access through other means, such as IMAP or POP3 to reach his e-mail box and perform the mapping confirmation process. Once confirmed, the user could log into the JustSSO with his AD account (e.g.: mfarias) and be redirected to his Google Apps email account (e.g. marcos). The following pictures illustrate this process: Figure 8 User mapping list and their status Page 18 of 22
Figure 9 Creating a user mapping Figure 10 E-mail message that is received to confirm a new User Mapping As the mapping feature will send an e-mail containing a link to a unique mapping confirmation page, it s necessary to have a SMTP set. To allow such configuration, the following page is available: Page 19 of 22
Figure 11 Page to inform SMTP server parameters in order to send mail messages It s always good to remind that the communication between Just SSO and the SMTP server must be allowed by your network topology/settings. Page 20 of 22
Optional Captcha As an additional security measure, you can enable the Captcha feature, which will make JustSSO display a Captcha after X unsuccessful attempts. You can enable it through the JustSSO administration console, menu Others settings, sub-menu Captcha. Besides that, it ll also be necessary: 1. Allow the VM to access the URL api-verify.recaptcha.net (Google service responsible for validating if the informed values correspond to the generated images) through 80 (http) and 443 (https) ports. 2. Include the $form.get("captcha").render() tag in the layout form, in a way that the generated Captcha image is displayed when appropriate. Page 21 of 22
Final considerations Important to note: SSO systems are not used by Google Apps when authenticating POP or IMAP access. So if you want your users have access using POP or IMAP, remember that: The access policies defined in your directory service will not be checked when users access their e-mail boxes by POP/IMAP, cause in these scenario the SSO solution is not involved. If this is a critical point to your company, you may opt to disable POP/IMAP access to all your users, forcing them to use a browser (inclusive from a mobile phone). To achieve that, all you need to do is: o access your Google Apps domain console; o o access Settings -> E-mail menu; in the page that is open; check the option Disable POP and IMAP access for all users. and click Save changes button. Learn more at http://www.google.com/support/a/bin/answer.py?answer=105694&hl=en If you want your users are able to access their e-mail boxes using POP / IMAP, remember that password validation is done by Google Apps, that is, with the passwords stored there, which will not necessarily be identical to that on your AD. In this case, you may consider enable the password replication process at login time to minimize this inconvenient. Yet, as an additional security measure, you can also use a reverse proxy to intermediate access to Just SSO instances. Page 22 of 22