Skip to content

Latest commit

 

History

History
108 lines (73 loc) · 7.6 KB

openid-connect-setup.md

File metadata and controls

108 lines (73 loc) · 7.6 KB

Configuring Annalist to use OpenID Connect

Annalist is designed to use third party authentication services based on OpenID Connect , which is a simple identity layer built over the OAuth2 proptocol.

Currently, Annalist has been tested with identity services provided by Google and GitHub, but should work with other identity providers. The instructions below are for setting up with Google. Some of the steps for other providers will almost certainly be different, but should follow a similar pattern.

In the following, the domain annalist.example.net will need to be replaced with the domain being used for the Annalist system being configured.

In outline, the steps are:

  1. Install Annalist. This is covered in Installing and setting up Annalist.

  2. Register the installed Annalist service with the identity provider.

  3. Create a local "client secrets" file containing application authentication protocol details provided by the registration process.

  4. Log in using third party credentials.

The instructions below assume that Annalist is installed for local access from the computer on which it is installed. If installed for shared access, the localhost domain name in the following steps must be replaced by the full domain name of the host on which it is installed.

Note that being logged in does not necessarily mean you have permissions to access Annalist data; it simply means that Annalist has an indication of who you are.

(@@NOTE: Currently, the authorization system is not fully implemented, and all authenticated users have full access to the Annalist data, but that will change before the first non-prototype software release. See Annalist issue 11)

Register Annalist service with Google

In order to use Google OAuth2/OpenID Connect authentication the installed Annalist service must be registered with Google (via https://cloud.google.com/console) and must be permitted to use the Google+ API, as shown:

Screenshot showing Google+ API enabled for project

As part of the registration process, the URLs to which the browser may be redirected following authentication (these will generally be something like https://annalist.example.net:8000/annalist/login_done/ and http://localhost:8000/annalist/login_done/) are specified. This will involve installing a file in the root of the server to prove control of the domain used for login redirects. Follow the instructions presented by Google's web pages, or go to Search Console and click the "Add a property button".

  • Create new project
  • Verify the domain the installation will use for redirects (under the "Domain verification" tab). The HTTPS proxy server (e.g., Apache) will need to be installed and running so that a small file provided by Google can be installed and served from this domain).
  • Under APIs & Auth > APIs, enable Google+ and disable all others
  • Under APIs & Auth > Credentials, Create new Client Id:
    • Select "Web application"
    • Authorized redirect URI is http://localhost:8000/annalist/login_done/ (don't omit the trailing "/").
    • Add an additional authorized redirect URIs using an actual host name if the application is to be accessible from other hosts; e.g. http://example.org:8000/annalist/login_done/. Additional redirect URIs need to be included also in the local configuration file (see below).
    • No authorized Javascript origins (yet)
    • Then click button "Create client ID"
  • Under APIs & Auth > Consent screen, fill in a name for the application
  • The window now displays client id and client secret values. The button "Download JSON" can be used to download a file that can be used to populate the file ~/.annalist/providers/google_oauth2_client_secrets.json, but note that Annalist also uses an additional field not populated by Google.

The JSON file provided by Google looks something like this:

{
  "web": {
    "client_id": "9876543210.apps.googleusercontent.com",
    "client_secret": "secret-12345678901234567890",
    "client_email": "[email protected]",
    "client_x509_cert_url": 
        "https://www.googleapis.com/robot/v1/metadata/x509/[email protected]",
    "redirect_uris": 
      [ "http://localhost:8000/annalist/login_done/", 
        "https://annalist.example.net:8000/annalist/login_done/"
      ],
    "auth_uri": "https://accounts.google.com/o/oauth2/auth",
    "token_uri": "https://accounts.google.com/o/oauth2/token",
    "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs"
  }
}

Create a local client secrets file

Annalist keeps authentication data in a location separate from the installed software. The default location is a directory called .annalist in the home directory of the user running the Annalist service.

A subdirectory called providers contains a client secrets file for each supported identity provider. Annalist reads the contehnt of this directory to build a list of identity providers that are offered on the initial login screen.

To configure Annalist to use the Google authentication service based on the service registration above:

  1. Edit the client secrets file returned by Google to add a provider name; e.g.

    {
  "web": {
    "provider": "Google",
    "client_id": "9876543210.apps.googleusercontent.com",
    "client_secret": "secret-12345678901234567890",
    "client_email": "[email protected]",
    "client_x509_cert_url": 
        "https://www.googleapis.com/robot/v1/metadata/x509/[email protected]",
    "redirect_uris": 
      [ "http://localhost:8000/annalist/login_done/", 
        "https://annalist.example.net:8000/annalist/login_done/"
      ],
    "auth_uri": "https://accounts.google.com/o/oauth2/auth",
    "token_uri": "https://accounts.google.com/o/oauth2/token",
    "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs"
  }
}

    This provider name is used to populate the dropdown box on Annalist's login page, so it should be a short string that will be recogizable to a user.

  2. Copy the modified client secrets file to ~/.annalist/providers/google_oauth2_client_secrets.json. (The exact filename is not critical, just its location and content)

  3. Restart the Annalist server if it is already running. (The client secrets are loaded and cached the first time a user logs in.) For local testing (using http://localhost:8000/annalist), environment variable OAUTHLIB_INSECURE_TRANSPORT should be set to "1". (See also file src/annalist_root/runserver.sh.)

Test log in with Google credentials

With environment variable OAUTHLIB_INSECURE_TRANSPORT should be set to "1", start the Annalist server.

Using the same computer, point a local browser at http://localhost:8000/annalist. Clicking on the login link should display a login screen with "Google" offered as a login service. Enter a user ID and click "Login" to invoke an OAuth2 authentication sequence with Google.

(Note: if using the "NoScript" browser plugin, this may trigger an XSS warning, and separately an ABE warning. Hopefully, NoScript will fix this. Meanwhile I added accounts.google.com as an exception from XSS sanitization, and disabled ABE checking, in NoScript.)