blob: cbd0c8c8955cd2bc464fdea0f1654f54aecc3987 [file] [log] [blame]
// Copyright 2021 The LUCI Authors.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
// Package encryptedcookies implements authentication using encrypted cookies.
//
// A session cookie contains a session ID and a per-session encryption key.
// The session cookie is itself encrypted (using an AEAD scheme) with the
// server-global primary encryption key. The session ID points to a session
// entity in a database that contains information about the user as well as
// various OAuth2 tokens established during the login flow when the session
// was created. Tokens are encrypted (again using an AEAD scheme) with the
// per-session encryption key from the cookie.
//
// One of the stored tokens is an OAuth2 refresh token. Periodically, during the
// session validation process, it is used to refresh other stored tokens
// (in particular an OAuth2 access token and an OpenID Connect ID token). This
// procedure fails if the user revoked access to their accounts via the ID
// provider or if the user's account is not longer active (from the ID
// provider's point of view). That way the state of the session is tied to the
// state of the user account at the ID provider which fully offloads user
// accounts management to the ID provider.
//
// Configuration
//
// To use this module you'll need to create an encryption key and to register
// an OAuth2 client with the ID provider. Instructions below assume you are
// using the Google Accounts ID provider and the created encryption key will be
// used as the server primary encryption key (i.e. it will be used to encrypt
// not only cookies but also any other secrets that the server may wish to
// encrypt).
//
// Start by creating two Google Secret Manager secrets (with no values) named
// `tink-aead-primary` and `oauth-client-secret` in the cloud project that
// the server is running in (referred to as `<cloud-project>` below). Make sure
// the server account has "Secret Manager Secret Accessor" role in them.
//
// Initialize `tink-aead-primary` key by using
// http://go.chromium.org/luci/server/cmd/tink-aead-key tool:
//
// cd server/cmd/tink-aead-key
// go run main.go login
// go run main.go create sm://<cloud-project>/tink-aead-primary
//
// This secret now contains a serialized Tink keyset with the primary encryption
// key. If necessary it can be rotated using the same `tink-aead-key` tool:
//
// cd server/cmd/tink-aead-key
// go run main.go rotate sm://<cloud-project>/tink-aead-primary
//
// This will add a new active key to the keyset. It will be used to encrypt
// new cookies, but the old key will still be recognized when decrypting
// existing cookies.
//
// Next, create a new OAuth2 client ID that will represent your server. Follow
// instructions on https://support.google.com/cloud/answer/6158849?hl=en and
// pick the application type "Web application". Add an authorized redirect URI
// equal to "https://<your-server-host>/auth/openid/callback". Do not add any
// authorized JavaScript origins.
//
// After creating the OAuth2 client, note the client ID (usually looks like
// "<number>-<gibberish>.apps.googleusercontent.com") and the client secret
// (just a random looking string). Put the value of the secret into a new
// version of `oauth-client-secret` Google Secret Manager secret.
//
// All prerequisites are done. Pass the following flags to the server binary to
// instruct it to use the generated secrets and the OAuth2 client:
//
// server \
// ...
// -primary-tink-aead-key sm://tink-aead-primary \
// -encrypted-cookies-client-id <number>-<gibberish>.apps.googleusercontent.com \
// -encrypted-cookies-client-secret sm://oauth-client-secret \
// -encrypted-cookies-redirect-url https://<your-server-host>/auth/openid/callback
//
// Note that the value of `-encrypted-cookies-redirect-url` must match exactly
// what you specified when creating the OAuth2 client (e.g. if you used some
// custom DNS domain name there, specify it in the `-encrypted-cookies-redirect-url`
// as well).
//
// If you want to use a dedicated key set for encrypting cookies specifically,
// replace `-primary-tink-aead-key` with `-encrypted-cookies-tink-aead-key`
// (and perhaps use some different name for the secret).
//
// Session store
//
// The module needs to know where and how to store user sessions. Link to
// a concrete implementation (e.g. Cloud Datastore) by using the following
// blank import line in the main.go:
//
// import (
// ...
// // Store auth sessions in the datastore.
// _ "go.chromium.org/luci/server/encryptedcookies/session/datastore"
// )
//
// Exposed routes
//
// The module exposes 3 routes involved in the login/logout process:
// `/auth/openid/login`, `/auth/openid/logout` and `/auth/openid/callback`. When
// configuring your load balancer (or dispatch.yaml on Appengine), make sure
// `/auth/openid/*` requests are routed appropriately.
//
// Note that cookies established by one server process can be validated by
// another, as long as they are both configured identically (i.e. all CLI flags
// mentioned above are passed to both binaries). For example, you can configure
// the load balancer to pass all `/auth/openid/*` requests to a dedicated server
// responsible for the login/logout, but then validate user cookies on another
// server.
//
// Note also that the server that only validates cookies still needs write
// access to the session store, to be able to refresh encrypted tokens stored
// there. It means if there are some caching layers in front of the datastore,
// they must be configured identically across all servers as well.
//
// Running locally
//
// If the server is starting in the development mode (no `-prod` flag is
// passed), and the `-encrypted-cookies-client-id` flag is not set, the module
// switches to use fake cookies that have a similar semantics to the real
// encrypted cookies, but require no extra configuration. They are absolutely
// insecure and must never be used outside of local runs. They exist only to
// simplify the local development of servers that use LoginURL/LogoutURL APIs.
package encryptedcookies