Configuring Google Workspace as an authentication provider for OpenAthens

This is an example using Google Workspace (formerly G Suite) of how to set up and configure a SAML source to sign into OpenAthens.

Prerequisites

• Access to your Google Workspace admin console
• Access to the OpenAthens administration area

Method

Configure Google Workspace settings

In your dashboard you will want to add a custom SAML app. At the time of writing this can be found under:

Apps > Web and mobile apps > Add app > Add custom SAML app

The wizard will give you an option to download the metadata. This is an excellent time to do so as you will need it when you configure the OpenAthens end.

The fields you will need to complete are:

If you cancel the wizard before you finish, you will need to re-download the metadata next time as it will be subtly different.

You will need to set up attribute mapping for at least the email address at this point. Make a note of the attribute name you choose. If you will need more information than just the email in OpenAthens such as given names, you can set them up at the same time or come back later. Attribute names are case sensitive.

Configure OpenAthens settings

1. In your OpenAthens administration area go to Management > Connections > Add > SAML
   
   
   1. For full details on this type of connection, see the SAML connector page.
      
      
2. Upload the google metadata
   
   
3. Enter the name of the email attribute from earlier as both the unique user attribute and the display name attribute.
   
   
4. Save
   
   
5. Go to the 'Relying party' tab and make a note of the metadata address it shows there.

Finish Google Workspace configuration

Now that the OpenAthens connection has been set up you can update the ACS and EntityID placeholders you used in your Google Workspace SAML app.

1. Navigate to the Google Workspace app (Apps > Web and mobile apps)
   
   
2. Click on the app and then on the service provider details section

Referring to the metadata address you copied from the admin area, you will have something that looks like this:

https://login.openathens.net/saml/2/metadata-sp/yourdomain.net/la/1234

It is the last bit you're interested in (yourdomain.net/la/1234)  as that will form part of the ACS URL and entityID of your connection that you are specifying in the Google Workspace SAML App. Update these to match that part of your metadata address:

You will need to 'turn on' and allocate the app to your users before it will work.

This sets up the basics and will use any default permission sets. You can at this point progress to testing if you wish, but many will want to set additional attributes to be released by Google Workspace such as a display name.

If you created additional attribute mappings within Google Workspace, you can map them on the Attributes tab - see: Attribute mapping. OpenAthens will cache these attributes when the user signs in, so changes at the Google Workspace end won't be picked up until the next time the user starts an OpenAthens session. 

If you want to assign permission sets based on attributes passed by Google Workspace, see: Permission set rules.

Testing

If you are not already using OpenAthens in production you can simply set the connection as live, visible and default.

If you already have active users you have two options:

1. Enable OpenAthens login as well - users will be presented a choice. Good if you have many testers.
   
   1. On the Preferences > Domain page check the option to show the OpenAthens sign-in and save
   2. Now set your SAML connection as live and visible (but not default) and save
2. Use debug mode. Good if you have only a few testers.
   
   1. There is no need to set your SAML connection as live or visible - in debug mode it will appear for you but not your end users.

The test:

1. Clear any OpenAthens or Google account sessions - private browsing mode may be useful here
2. Go to a resource and select yourself at the WAYF
3. Depending on how you are testing...
   1. Debug & dual modes should present login options and selecting the Google option should transfer you to the Google sign-in.
      1. Debug mode will additionally show you the attributes being passed to us by Google, and from us to a resource. You will need to click a continue button to progress.
   2. Default mode should transfer you directly to the Google sign-in
4. The Google Apps account you signed in with should also now appear in the relevant section of the accounts list in the OpenAthens administration area. 

Go live

Once you are happy that it is working, return to the connection and set it as live and visible. If it is to be your only login option, also set it as default and unset the OpenAthens account option on the domain preferences page if you had set it.

Whilst our service desk will always try to be helpful, they can only support the OpenAthens part of this.