Integrating Google Apps with OIF / IdP

Google Apps provide a set of services that companies sometimes leverage for their day to day activities, which allow their employees to offload mail, calendar, document storage... in the Google cloud.

When a company purchases Google Apps for its employees, it needs to create user accounts in Google and provide the employees with their account information:

  • Username and password to access Google Apps
  • How to set/reset their password in Google Apps (initially, or if the password needs to be reset periodically)

Every time the user needs to access Google Apps, an authentication operation will take place where the user will enter the Google Apps credentials, which will be different from the on-premise company's user credentials.

Google Apps supports the SAML 2.0 SSO protocol as a Service Provider, where the Google Apps service for the company can be integrated with the on-premise Federation SSO IdP server in order to:

  • Provide true SSO capabilities for the user: the user authentication state is propagated from the on-premise security domain to Google Apps
  • Not force the user to manage and remember a different set of credentials
  • Allow the on-premise administrator to control more efficiently password policies locally.

In this article, I will describe step by step how to integrate Google Apps as an SP with OIF as an IdP via the SAML 2.0 SSO protocol.

Important note: enabling Federation SSO for a domain will also affect the administrators for that domain who will need to authenticate via Federation SSO thereafter.

Enjoy the reading!

User Mapping


Users in Google Apps are uniquely identified by their email addresses which was set when those users were created.

During a SAML 2.0 SSO flow, the IdP will need to provide the user ID to Google Apps:

  • In the SAML 2.0 NameID field
  • With the NameID value set:
    • Either to the user's email address at Google Apps
    • Or the identifying part of the email address (ie: before the @ character)

As an example, I will show the information the IdP should send for company ACME which purchased a Google Apps service, for their acme.com domain.

To view a user account in Google Apps, perform the following steps:

  • Launch a browser
  • Go to http://www.google.com/a
  • Click Sign In

Perform the following steps:

  • In the domain field, enter the name of your domain (in this example, www.acme.com)
  • Select Admin Console
  • Click Go

Perform the following steps:

  • In the Dashboard, click on Users

Perform the following steps:

  • Select a user to view

The next screen will show details about the user. The email address is displayed underneath the user's identity. In this example, the ACME IdP will have to send to Google Apps either alice or alice@acme.com during the SAML 2.0 SSO operation:

OIF/IdP Configuration


Google Apps Identifier

Google Apps can be configured by the Google Apps administrator to be known to the IdP:

  • Either as google.com
  • Or as google.com/a/<YOUR_DOMAIN.COM> (for example: google.com/a/acme.com)

This behavior is dictated by the "Use a domain specific issuer" in the Google Apps SSO admin section.

Typically, you would not need to use a specific issuer/providerID, and Google Apps in the SAML 2.0 SSO flow would be known as google.com.

Google Apps SP Partner

To create Google Apps as an SP Partner, perform the following steps:

  • Go to the OAM Administration Console: http(s)://oam-admin-host:oam-admin-port/oamconsole
  • Navigate to Identity Federation -> Identity Provider Administration
  • Click on the “Create Service Provider Partner” button
  • In the Create screen:
    • Enter a name for the partner: GoogleApps for example
    • Select SAML 2.0 as the Protocol
    • In the Service Details:
      • Click Enter Manually
      • Set the Provider ID to google.com (if in Google Apps you enabled the "Use a domain specific issuer" feature, you would enter google.com/a/<YOUR_DOMAIN.COM>).
      • Set the Assertion Consumer URL to https://www.google.com/a/<YOUR_DOMAIN.COM>/acs (for example https://www.google.com/a/acme.com/acs)
    • Select Email Address as the NameID format
    • Select the LDAP User Attribute containing the userID that will need to be provided to Google Apps. In my example, the uid attribute contained the userID: select User ID Store Attribute then enter uid
    • Select the Attribute Profile that will be used to populate the SAML Assertion with attributes (default empty profile is acceptable since Google Apps does not expect any SAML Attributes other than the NameID)
    • Click Save

Collecting OIF Information

The following information will need to be provided into the Google Apps SSO Admin console:

  • SAML 2.0 SSO IdP endpoint
  • X.509 Signing Certificate used by the IdP to sign the SAML 2.0 Assertion

In this earlier article, I listed the endpoints published by OIF. The SAML 2.0 SSO IdP endpoint and the SAML 2.0 logout endpoint would be http(s)://oam-public-hostname:oam-public-port/oamfed/idp/samlv20, with oam-public-hostname and oam-public-port being the values of the public endpoint, where the user will access the OAM/OIF application (load balancer, HTTP reverse proxy...).

If you are unsure about the oam-public-hostname and oam-public-port, you can:

  • Go to the OAM Administration Console: http(s)://oam-admin-host:oam-admin-port/oamconsole
  • Navigate to Configuration -> Access Manager Settings
  • The oam-public-hostname  is the OAM Server Host, the oam-public-port is the OAM Server Port and the protocol (http or https) is listed in OAM Server Protocol.

In the same article, I also explained how to determine which key entry is used to sign SAML messages and how to retrieve the corresponding Signing Certificate used by OIF/IdP:

  • Go to the OAM Administration Console: http(s)://oam-admin-host:oam-admin-port/oamconsole
  • Navigate to Configuration -> Federation Settings
  • The Signing Key field in the General section indicates which key ID entry is used for SAML message signature operations

To retrieve the certificate file of a specific key ID, open a browser and use the following URL to retrieve the certificate and save it locally:
http://oam-runtime-host:oam-runtime-port/oamfed/idp/cert?id=<KEYENTRY_ID>

  • The id query parameter contains the key entry ID for the certificate. Replace <KEYENTRY_ID>
  • An example would be:
    http://acme.com/oamfed/idp/cert?id=osts_signing 

Google Apps Configuration


To configure Google Apps for SAML 2.0 SSO flow, perform the following steps:

  • Launch a browser
  • Go to https://www.google.com/enterprise/apps/business/
  • Authenticate and go to the Admin Dashboard
  • Click on More Controls

Perform the following steps:

  • Click Security

Perform the following steps:

  • Click Advanced Settings

Perform the following steps:

  • Click "Set up single sign-on (SSO)"

In the SSO Setup page, upload the certificate:

  • In the Verification Certificate section, click Choose file
  • Select the OIF IdP certificate saved earlier
  • Click upload

In the SSO Setup page, to set up the URLs and enable Federation SSO:

  • Enter the Sign-in URL (IdP SAML 2.0 SSO endpoint), similar to http(s)://oam-public-hostname:oam-public-port/oamfed/idp/samlv20 (for example: https://sso.acme.com/oamfed/idp/samlv20)
  • Enter the Sign-out URL (IdP SAML 2.0 Logout endpoint), similar to http(s)://oam-public-hostname:oam-public-port/oamfed/idp/samlv20 (for example: https://sso.acme.com/oamfed/idp/samlv20)
  • Enter the Change Password URL for your deployment (note: in this example I use /changePassword, but this is not an OAM/OIF service; you would need to enter the Password Management service URL for your deployment)
  • Check the "Enable Single Sign-On" to turn on Federation SSO
  • Save

Testing


To test:

  • Open a fresh browser
  • Go to these URLs to authenticate via Federation SSO for the following Google Apps:
    • Gmail: https://mail.google.com/a/<YOUR_DOMAIN.COM>/ (for example https://mail.google.com/a/acme.com/)
    • Calendar: https://calendar.google.com/a/<YOUR_DOMAIN.COM>/ (for example https://calendar.google.com/a/acme.com/)
    • Documents: https://docs.google.com/a/<YOUR_DOMAIN.COM>/ (for example https://docs.google.com/a/acme.com/)
  • Enter the Gmail URL for example
  • You will be redirected to OIF IdP
  • Enter your credentials

Perform the following steps:

  • Click Login
  • The Gmail application will be displayed:

In the next article, I will cover the various settings that can be used to configure OIF/SP for sending an SSO Request, when the Federation SSO flow starts.
Cheers,
Damien Carru

Comments:

Post a Comment:
  • HTML Syntax: NOT allowed
About

Damien Carru is a member of the Oracle Identity Management organization, focusing on Federation and SSO. This blog will cover Federation use cases involving Oracle Access Manager, Oracle Identity Federation and Oracle Security Token Service

Search

Categories
Archives
« September 2015
SunMonTueWedThuFriSat
  
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
   
       
Today