The Vanadium Identity Service generates blessings. It uses an OAuth2 identity provider to get the email address of a user and then issues a blessing with that email address. For example, after determining that the user is alice@university.edu
(using OAuth2), this service will issue the blessing dev.v.io/u/alice@university.edu
(where dev.v.io
is the namespace for which the public key of the identity service is considered authoriative). The blessing may also contain specific caveats per the user's request.
Broadly, this identity service consists of two main components:
One additional service enables revocation of the blessings granted by the blessing service:
All three services are exposed by a single binary - identityd
. In order to save users from talking to two different services (the HTTP service and the Blessing service) and managing macaroons, we also provide a command-line tool - principal
- that talks to both of the services and obtains a blessing for the principal that the tool is running as.
Before diving into the details of identityd
's design, some prerequisites:
k
defines a macaroon for a state as: Macaroonk(state) = HMAC(k, state) The name “cookie” or “token” could have been used instead, but the term macaroon was an allusion to this paper.The HTTPS Authentication Service runs at https://dev.v.io/auth and uses the Google OAuth2 web service flow for authenticating users. It has a specific OAuth2 ClientID and ClientSecret obtained from the Google Developer Console. It supports the following routes:
Route | Purpose |
---|---|
/google/seekblessings | Receive blessing requests |
/google/caveats | Display a form for selecting caveats to be added to a blessing |
/google/sendmacaroon | Receive a POST request from the caveat selection form |
/google/listblessings | Enumerate all blessings made by a particular user |
/google/revoke | Receive revocation requests |
The blessing service is a Vanadium RPC service reachable via the name /ns.dev.v.io:8101/identity/dev.v.io/u/google
and presents the MacaroonBlesser
interface:
type MacaroonBlesser interface { // Bless uses the provided macaroon (which contains email and caveats) // to return a blessing for the client. Bless(macaroon string) (blessing security.WireBlessings | error) }
The principal
command-line tool is used to orchestrate the process of obtaining a macaroon from the HTTPS Authentication Service and exchanging it for a blessing from the Vanadium Blessing Service. The following sequence diagram lists the network requests involved in this process:
Steps 1 thru 4 in the sequence diagram above result in the principal
tool invocation obtaining a macaroon.
Steps 5 and 6 exchange that macaroon for a blessing.
The tool generates a random state parameter toolState
and starts an HTTP server on localhost
for receiving the macaroon. toolURI
denotes the URI of this server (e.g., http://127.0.0.1:14141
), and toolPublicKey
denotes the public key of the principal running the tool. It then directs the web browser on the machine to the HTTP Authentication Service while informing it of toolURI
, toolPublicKey
and the toolState
parameters. For example, it might redirect to: https://dev.v.io/auth/google/seekblessings?redirect_uri=<toolURI>&state=<toolState>&public_key=<toolPublicKey>
The HTTP Authentication Service extracts toolURI
, toolState
and toolPublicKey
and redirects the browser to the Google OAuth2 endpoint (using the web service flow). The redirect_uri
provided to this endpoint is set to the page that presents a form to control caveats on the final blessing and the state
parameter is set to: oauthstate = Macaroonk(toolURI + toolState + toolPublicKey + serverCookie) where serverCookie
is a cookie set by the HTTP Authentication Service in the user‘s browser. This leads the user’s browser to a URL like: https://accounts.google.com/o/oauth2/auth?client_id=...&redirect_uri=https://dev.v.io/auth/google/caveat&state=oauthstate
The Google OAuth2 endpoint asks the user to login and grant access to email address to the Vanadium Identity Server, after which it redirect the browser back to: https://dev.v.io/auth/google/caveats?code=<authcode>&state=<oauthstate>
The caveats page at the HTTP Authentication Service receives authcode
and oauthstate
. It then:
oauthstate
is a valid macaroon generated by step 2.toolURI
, toolState
, toolPublicKey
and serverCookie
from the macaroon.serverCookie
matches the cookie presented by the browserauthcode
for an email address (via an identity token) using the OAuth2 client-secret.principal
tool started in step 1. Embedded in this form is formstate = Macaroon<sub>k</sub>(toolURI + toolState + toolPublicKey + email + serverCookie)
.When the user submits the form rendered in step 3, the browser sends the form contents to https://dev.v.io/auth/google/sendmacaroon
which performs the following steps:
formstate
is a valid macaroon.toolURI
, toolState
, toolPublicKey
, email
and serverCookie
encapsulated in the macaroon.serverCookie
matches the cookie presented by the browser.toolURI
is a localhost URI.https://<toolURI>/macaroon?state=<toolState>&macaroon=M&root_key=publicKey
where publicKey
is the blessing root of the identity service.The principal
tool receives the macaroon M
, toolState
and the blessing root via the HTTP redirect in step 4. It then:
toolState
obtained here matches the one created in step 1.Bless
RPC on the blessing service passing it M
as an argument. It only sends this request if the the RPC server proves that it's public key is publicKey
via the authentication protocol used in RPCs.The Vanadium Blessing Service that receives this RPC performs the following steps:
email
, toolPublicKey
and caveats
from it.toolPublicKey
. This check ensures that the macaroon can only be used by the principal tool that requested it in the first place. It protects against impersonation attacks wherein an attacker steals the macaroon handed out in step 5 and then tries to obtain a blessing for the email address encapsulated in the macaroon.dev.v.io/u/<email>
and the caveats extracted from the macaroon. This blessing is bound to the public key of the principal making the RPC request (i.e., toolPublicKey
).https://dev.v.io/auth/google/listblessings
.The caveat addition form presented to the user in step 4 supports a few types of caveats:
The revocation caveat that is (at the user's request) added to the blessing is a third-party caveat with a unique 16-byte ID and the object name of the discharging service. Each time a revocation caveat is created, the blessing service stores the corresponding ID and the revocation status in a SQL database.
The discharge service run by identityd
extracts the ID from the caveat and looks it up in the database. If the database suggests that blessing should be revoked, it refuses to issue a discharge.
This is implemented in services/identity/internal/revocation.
Revocation can be triggered by clicking buttons on https://dev.v.io/auth/google/listblessings.