Administrator Guide. v 11

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

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

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.

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

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.

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 2: Default TCP/IP setting: automatic (DHCP). To alternate between automatic and manual mode, use “Page Up” and “Page Down” keys.

Figure 4: Option accessible by pressing F6 to inform “DNS search suffix” and up to (3) DNS servers.

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:

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

Example:

ldaps://10.0.2.15:636

Base DN

User’s Base Distinguished Name. e.g.:

cn=Users,dc=yourdomain,dc=com

Login

Inform an account with access to your directory

service, e.g.:

CN=Admin,CN=Users,DC=yourdomain,DC=com

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.

Password

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.

Password

(Confirmation)

Security Authentication

Inform if it’s Simple (default) or None.

Security Protocol

Default value is SSL

SSL Store key

Upload a certificate generated by your directory service to allow secure communication with Just SSO.

Email Attribute Name

Attribute name in your directory service that contains users' email addresses. e.g.: userPrincipalName

Domain name in Dir.

Serv.

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

Password Attribute

Name

Attribute name in your directory service that contains users' passwords, e.g.: userPassword

3. Click in the button Save;

Parameter Value Comments

Domain

Corresponds to your Google Apps domain. Example: justdigital.com.br

Domain administrator

(email)

Example: [email protected]

Password

Private key

Upload here the private key that you generate or that you receive from Just Digital by e -mail.

Public key

Upload here the public key that you generate or that you receive from Just Digital by e -mail.

Show intermediate page?

Check this option to show an intermediate page (with alerts, highlights, messages, ...) just after user log in.

Replicate user password

after password change?

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.

Replicate user password

after login?

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.

Optimize password

replication to Google

Apps?

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.

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 respective

ly

.

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.

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.

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.

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"/>

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).

Figure 9 – Creating a user mapping

Figure 10 – E-mail message that is received to confirm a new User Mapping

Figure 11 – Page to inform SMTP server parameters in order to send mail messages

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.

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 access “Settings” -> “E-mail” menu;

o 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”.