Skip to main content
Skip table of contents

Configuring Google Workspace as an authentication provider for OpenAthens

Using Google Workspace (formerly G Suite) as an example, this guide explains how to set up and configure a SAML source to sign in to OpenAthens.

Prerequisites

  • Access to your Google Workspace admin console

  • Access to the OpenAthens administration area

Method

Configure Google Workspace settings

In your Google admin console:

  1. Create a custom SAML app.

  2. Download the metadata.

  3. Complete the following settings:

Field

Application name

Anything that makes sense to you

Description

Anything that makes sense to you

ACS URL

Come back to this later. To get through the setup wizard, enter something like 'https://anything.example'

EntityID

Come back to this later. To get through the setup wizard, enter something like 'anything'

Start URL

Leave empty

Signed Response

True

Name ID

Use primary email

If you exit the setup wizard before completing all the details, you will need to download the metadata (which will have changed) again on your next session.

  1. Set up attribute mapping for at least the email address (Name ID). Make a note of the attribute name you choose for reference. If you need other user attributes, you can set those up either now or later. (Attribute names are case sensitive.)

Configure OpenAthens settings

  1. In your OpenAthens admin area, go to Management > Connections.

    Main Connections page. In the left sidebar are a list of federations to which the domain belongs and a list of local connections that are currently configured. There is also a button to create a new local authentication connection.The main content area shows key details such as your entity ID and scope.

  2. Under Local authentication in the left sidebar, press Create. A pop-up opens, showing available connectors.

    Pop-up window titled 'Select local authentication system type'. Following are the options 'API', 'Evergreen ILS', 'Microsoft ADFS', 'OIDC', 'SirsiDynix', 'CAS', 'LDAP', 'Microsoft Azure' and 'SAML'. At the bottom of the window are 'Configure' and 'Cancel' buttons.

  3. Select SAML and press Configure.

    Pop-up window titled 'Add SAML authentication system'. Advisory text reads, 'Upload SAML 2 metadata via a URL or file'. There is a text input field labeled 'Metadata URL' and a file upload control. At the bottom of the window are 'Add' and 'Cancel' buttons.

  1. Click the Choose File button and upload the Google metadata.

  2. Press Add. The connector is created with a temporary name. You can now view or edit its details.

    Details of a connector called 'Temporary Relying Party'. Its settings are divided into several tabs - 'Details' (the default), 'Relying party', 'Attributes', 'Permissions', 'Certificates', 'Advanced' and 'Contact'. Fields shown in the default Details tab include 'Display name', 'Description', 'Metadata URL', 'Entity ID', 'SSO endpoint', 'Display name mapping', 'Display name attribute', 'Unique user mapping' and 'Unique user attribute'. There are also buttons to 'Save changes' or delete the connector.


  3. Set both Display name mapping and Unique user mapping to Use attribute.

  4. In both the Display name attribute and Unique user attribute fields, enter the name of the email address attribute you configured in Google.

  5. Press Save changes.

  6. Finally, go to the </> Relying party tab and copy the Metadata URL shown there.

    'Relying party' tab of the connector. It contains a single field, 'Metadata URL', in which a URL is pre-loaded.

For more details on this type of connection, see SAML connector.

Complete Google Workspace configuration

Once the OpenAthens connection is set up, update the ACS URL and EntityID placeholders in your Google Workspace SAML app.

Construct ACS URL and EntityID

Take the metadata URL you saved from OpenAthens and copy the second half of it, beginning with your individual domain name. For example, if the metadata URL is https://login.openathens.net/saml/2/metadata-sp/yourdomain.net/la/1234, copy the part “yourdomain.net/la/1234”.

Your ACS URL is https://login.openathens.net/saml/2/acs/[individual part of the metadata URL], for example https://login.openathens.net/saml/2/acs/yourdomain.net/la/1234.

Your EntityID is https://login.openathens.net/saml/2/metadata-sp/[individual part of the metadata URL], for example https://login.openathens.net/saml/2/metadata-sp/yourdomain.net/la/1234.

Configure your Google app

  1. In your Google admin console, go to the app you created.

  2. In the Service provider details section, enter the following information:

Field

ACS URL

https://login.openathens.net/saml/2/acs/[individual part of the metadata URL]

EntityID

https://login.openathens.net/saml/2/metadata-sp/[individual part of the metadata URL]

  1. Perform any further configuration you need, for example:

Testing

Prepare for testing

If you are not already using OpenAthens in production:

  1. In the OpenAthens admin area, go to Manage > Connections.

  2. Open your Google connection for editing.

  3. In the Details tab, set the Status of the connection to Live, Visible and Default.

    Group of three checkboxes titled 'Status'. The options are 'Live', 'Visible' and 'Default'. The user can tick any, all or none of the boxes.

  4. Save your changes.

If you already have active users, you have two options:

  1. Enable OpenAthens login so that users are given a choice of login options. Good if you have many testers.

    1. In Preferences > Domain, turn on the option Show OpenAthens sign-in. Save your changes.

    2. In Manage > Connections, set the Status of your SAML connection to Live and Visible (but not Default). Save your changes.

  2. Use debug mode. Good if you have only a few testers.
    There is no need to set the Status of your SAML connection as live or visible. In debug mode, the connection does not appear for end users.

Test

  1. Clear any OpenAthens or Google account sessions. You may find private browsing mode useful.

  2. Go to a resource. At the WAYF prompt, select your Google app account.

  3. Depending on how you are testing:

    1. Debug and dual modes give login options. Select the Google option to use the Google login.
      Debug mode additionally shows you the attributes being passed to OpenAthens by Google, and from OpenAthens to the resource. You will need to click a button to proceed.

    2. Default mode transfers you directly to the Google login.

  4. The 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 the connection is working, ensure it is set it as Live and Visible. If it is to be your only login option, also set it as Default. Disable the option Show OpenAthens sign-in in Preferences > Domain if you previously enabled it.

While our service desk will always try to be helpful, they can only support the OpenAthens end of the connection.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.

Contact Support Close