LBH Google Auth

This is a lightweight service written in Node.js that enables users to log in to the Google Hackney domain and generates a token to use on internal-facing Hackney services that also includes their group information.

Why?

Because Hackney would like to be able to manage which users can do what via the Google admin console. Simply logging in with the Google OAuth API would validate identity (authentication) but has no information about what the user is allowed to do (authorization). The applications themselves are expected to maintain a mapping between these groups and their permissions.

How do I use the service as a developer?

The application is quite simple to use from an application:

1. Point the user to the login URL with a parameter letting it know which URL to send the user back to. e.g.

https://auth.hackney.gov.uk/auth?redirect_uri=https://auth.hackney.gov.uk/auth/check_token

2. The user will then log in to Google and then be redirected back to the redirect URL you specified.
3. The JWT token will be set in the "hackneyToken" cookie and can be authenticated using the shared JWT secret. See below for the payload details.

How does it work?

1. The user is directed to this service from another application, with a redirect_uri parameter passed along with the request
2. We store the redirect_uri in a cookie and send the user to Google to log in
3. Google sends the user back to this service with an OAuth token which is then upgraded to a user token along with requesting the user profile details
4. We look up the groups for the user via the Google Admin API using an admin oAuth token
5. We generate a JWT token with the user information and set it in the "hackneyToken" cookie. The payload of the token has the following structure:

{
  "sub":"100518888746922116647",
  "email":"[email protected]",
  "iss":"Hackney",
  "name":"Hackney User",
  "groups":["group 1", "group 2"],
  "iat":1570462732
}

with the following meanings:

• sub: The internal Google ID for the user
• email: The Hackney email address for the user
• iss: The issuer (always Hackney)
• name: The name of the user
• groups: An array of the groups the user is a member of
• iat: The issued time of the token (to be used for expiry by the applications)

You can test logging in and inspect the token via the following URL:

https://auth.hackney.gov.uk/auth?redirect_url=http://auth.hackney.gov.uk/auth/check_token

How do I run it?

Set up the environment variables as in config-sample.env.sh and bring them in to your shell using . ./config.env.sh. Then run npm install to install the dependencies and finally node index.js to run the application. To run it against a real Google authentication backend you will need to set up the ADMIN_REFRESH_TOKEN as follows:

1. Make sure you have a Google user who has the permissions to read the groups API
2. visit /auth/admin
3. Log in as the admin user
4. Copy the refresh token that is displayed in the browser and put it in the ADMIN_REFRESH_TOKEN environment variable
5. Restart the application