portier/portier-broker

Portier Broker reference implementation, written in Rust

Portier Broker

This is the Portier Broker reference implementation.

• Portier Broker on GitHub
• Portier main website
• Portier specification

How to run your own broker

Portier is specified such that everyone can run their own broker instance. You can point your Relying Parties at your own broker, so that you do not have to depend on the broker run by the Portier project.

Binaries for the broker can be found on the GitHub releases page. Docker images are also available on Docker Hub. Alternatively, you can build the broker yourself.

The broker can be configured using a configuration file or through environment variables. Both are documented in the example configuration file.

Once you've prepared the configuration, simply run the broker executable:

# From binaries:
./portier-broker[.exe] ./config.toml

# Using Docker:
docker run -v /srv/portier-broker:/data:ro portier/broker /data/config.toml

Some additional notes:

• If using environment variables only, don't specify a configuration file on the command line.

• Systemd units are also included with the Linux binaries.

• The broker only talks plain HTTP, and not HTTPS. Using HTTPS is strongly recommended, but you'll need to add a reverse proxy in front of the broker to do this. (Apache or Nginx can do this for you.)

portier-broker's Issues

Check Cargo.lock into the repo

We need to be absolutely certain that the binary is consistently built with the same dependent libraries to avoid inconsistencies and regressions on bugs like #28

README.md

The Broker needs a README that explains:

• Its exposed API surface (HTTP routes and methods)
• How to interact with it (which will likely form the basis of a future, general Using Portier doc on the main site)
• How to develop it locally
• How to deploy it in production

I'd especially love it if the document discussed deploying on Heroku or a similar PaaS's free tier, to facilitate hobbyists who want to self-host.

Send Cache-Control header in response

We should add the Cache-Control headers to our responses.

• Login routes: no-cache, no-store.
• Discovery document and other static resources: public, max-age=86400 (1 day)
• Keys document should be public, with a configurable age. This depends on how often keys are rotated.
• /.well-known, probably no-cache?

Lengthen and make case-insensitive email confirmation codes

If we're going to allow people to manually transcribe, being case insensitive is a huge usability win.

We should increase the length of the codes to compensate.

Sign our emails with DKIM, good SPF records, and other best practices

It's important that the mail we send hits inboxes. Part of that is having appropriate SPF records and signing the outgoing mail with DKIM, monitoring delivery / bounce rates, etc.

Providers like Postmark, SendGrid, or Mailgun are great for this.

Validate clients

Currently, we don't validate client_id and redirect_uri, but I'm worried about the security implications of this.

OpenID Connect also has a spec on dynamic registration, which opens up the same hole, and discussed the implications here: http://openid.net/specs/openid-connect-registration-1_0.html#Impersonation

How do we validate clients while still keeping an open system?

Check handling of GMail address variants

With dots and pluses. Ideally, it should not canonicalize?

Refactor to provider selection to be more modular

Our level of abstraction doesn't feel right yet. Our current code basically functions as:

1. If email.domain in providers:
   1. Get a redirect URL from the openid module
   2. Redirect the user
2. Else:
   1. Get a session ID from the email module
   2. Display the confirm email template to the user

I don't think this is the best solution in a few areas:

• It only switches on email domain. As per #44, we might want to switch on other attributes in the future.
• If two domains are serviced by the same provider, as is the case with gmail.com and googlemail.com we have to duplicate that in the configuration.
• General OIDC and Gmail-specific rules are commingled in src/oidc.rs
• This design presumes that all providers are OIDC providers.
• The returned values aren't unified: you get either a URL or a session ID.
• The redirect logic is split between the individual module and src/lib.rs.

I'm not sure how to best address this, but I think the answer might be along the lines of:

• All providers adhere to a common interface or implement a common trait
• Providers completely handle incoming requests and return a ready-to-use iron::Response
• Split the generic OIDC provider and the Gmail provider into separate modules. The Gmail one can, of course, rely on facilities offered by the generic one.
• Providers can return whether or not they can handle an address, either through a function returning bool, or by returning an Option<Iron::Response>.
• We keep a prioritized list of providers, and just iterate over it, trying each one until one succeeds.

Measure (and increase) test coverage

Analyze one-time code entropy. is it enough?

Brian Warner (@warner) had some interesting thoughts on this domain in his PyCon talk on Magic Wormhole around the 12 minute mark.

Right now we choose 6 characters from an array of 48 candidates.

48^6 = 12,230,590,464 combinations, or around 33.5 bits of entropy.

If we want to be case insensitive, we'd drop to just 26 possibilities:

26^6 = 308,915,776 combinations, or around 28.5 bits of entropy.

Is this enough?

Panic on invalid email address

If a request contains a login_hint without an @, the emailaddress crate causes a panic.

Upstream merged a pull request that fixed it, but hasn't made a release yet: https://github.com/pwoolcoc/emailaddress-rs/pull/5

I've requested the author make a release with this fix. We should upgrade when that happens.

Cache OIDC provider keys

Similar to #6, it could be helpful to cache the public key data from the OIDC providers for a while. Probably use the key ID in the store key to make things easy.

Set X-Frame-Options: Deny and/or Immediately Revoke Google Credentials

Problem: After completing the Gmail flow, future logins do not require any user interaction. This could be dangerous.

We tried using ?prompt=consent (#76) to require reconfirmation, but it shows an alarming message to users (#80), so we can't do that.

Stack Overflow suggests that we could solve this by immediately revoking our access immediately after validating a token (#84).

It seems like we have three options:

1. Prompt on every login by immediately revoking our access token (#84)
2. Prompt on every login in the broker, before redirecting back to the RP.
3. Do not prompt on every login

The second option seems like over-engineering for now. So, do we want to prompt on every login or not? What attack are we actually trying to protect against?

Cache OIDC provider metadata

Can cache the bits of the discovery document we use in Redis. Probably makes sense to just cache with a 3600s expiry, rather than doing complicated ETag and Last-Modified handling? The Google IdP sets timeout of an hour explicitly, though Microsoft doesn't send anything like it.

Bump DMARC policy to p=quarantine or p=reject

Right now our DMARC record is set to p=none. It looks like it's working, and I can't imagine anything else sending mail from our domain, so we should be able to bump it to a more restrictive policy soon.

Revisit in mid-November, once we have a few weeks of running the broker in production under our belts.

Handle requests for /favicon.ico, or provide an icon

Right now, we panic.

Achieve A+ in Qualys' SSL Labs test

See: https://www.ssllabs.com/ssltest/analyze.html?d=broker.portier.io

...if reasonably possible on AWS / Heroku

Are we formally compliant with OpenID Connect?

It'd be neat to get the broker certified as OpenID Connect compliant: http://openid.net/certification/

We should be able to achieve Implicit OpenID Provider and OpenID Provider Publishing Configuration Information. If it weren't for the dynamic registration and basic flow requirements, we'd be able to get Dynamic OpenID Provider. Oh well.

Allow setting SMTP credentials

We currently only support unauthenticated SMTP connections, which is fine if access control is done some other way. (E.g. mailserver only listens on localhost, or is strictly firewalled.)

For AWS SES or other cloud mail services, we need to provide credentials and support STARTTLS.

Create privacy policy / terms of service

We should have a proper PP / ToS, and add them to the Google API consent screen.

Make it aesthetically pleasing

The error pages, interstitials, emails, and such should look like a modern web application

Yes, this means HTML email. :(

Detect G Suite domains

Currently, it's possible to get the oidc flow for a G Suite domain by simply copying the provider section for gmail.com for each domain you want. It'd be neat if we could detect domains that run mail through G Suite.

Is checking MX records enough? This was on the backlog for Persona, so I'm not sure what their findings and experiences are, but that would be valuable to look into.

We need a common Google account for the broker

Currently:

This should probably go to some sort of mailing list (the project mailing list? a separate list for just the broker owners?)

We need an icon

Both for favicon and Google auth screen reasons. Compare:

---

Audit library licenses

We're claiming to license this program as MIT/Apache2. Can we actually do that? Are we sure none of our dependencies (or their dependencies) are GPL'd?

Support Heroku's app.json / "Deploy to Heroku" button

By specifying an app.json, we could have a one-click button that lets people set up their own Broker, even going so far as automatically adding-on Redis and SendGrid/Postmark/etc plans.

This would be a huge win for ease of self-hosting

Our startup error messages / handling are horrible

If you forget to specify a required parameter, all you get is thread 'main' panicked at 'calledOption::unwrap()on aNonevalue', ../src/libcore/option.rs:323

We should log something sane, here.

Reconsider degree of configurability

Do we really need:

• crypto.token_ttl
• redis.session_ttl
• redis.cache_ttl
• redis.cache_max_doc_size

The TTLs all seem like things we can/should take an opinionated stance on, and the max document size in the Redis cache seems of questionable utility.

Browser prefetch can trigger `/auth`

This is, of course, a direct result of: #16

But we need that for spec compliance. I'm hoping there's a way to be smart about this and detect prefetches.

Display form allowing for manual input of code when using email-based authentication

Clicking the link works fine, but the Broker needs to display an interstitial page that:

1. Tells the user to check their email
2. Allows them to manually type in the code

Move onto Heroku

We need to be on some kind of managed, horizontally-scalable PaaS before launch.

Enable continuous delivery on Heroku?

I'd like it if any merge to master automatically deployed to Heroku. I've set this up for the Demo RP, and it works great.

Environment variables persist across deployments and Redis is kept separate, so there's no other state we need to worry about preserving.

Add Clippy as a build hook

Clippy has nice lints. We should integrate it with our build process. We should be able to roll this into Travis.

Expose version metadata somewhere

We should be able to discover what version of our software the broker is running.

On Heroku, with Dyno Metadata enabled, we can use the HEROKU_SLUG_COMMIT envvar to get the hash for the running broker. We should expose that.

Integrate Travis CI to GitHub PR

We have Travis doing builds at https://travis-ci.org/portier/portier-broker, but it's not reporting back to GitHub for pull requests.

Generate ephemeral keys when none are provided

For local testing, it'd be great if the broker could just generate a temporary key when none are provided.

Allow for multiple keys in keytext configuration and envvar

Right now you can only specify one key via BROKER_KEYTEXT or crypto.keytext. It would be nice if we could specify multiple.

Allow for setting configuration and signing keys via environment variables

The only sane way to deploy configuration on a PaaS like Heroku is using env vars. See also: https://12factor.net/config

We need some way to pass configuration into the Broker without requiring a config.json and key.pem file on disk.

I'm particularly fond of a cascade of:

App-Specific Env Vars > Common Env Vars > Config Files > Defaults

The demo rp is configured in this way: settings.py, README.rst#Configuration

Improve logging and metrics

Right now we have almost no visibility into the ongoing health and failure rates of this service.

We should make heavy use of our logging facilities, consider setting up some kind of log aggregation and error reporting service, and get some sort of statsd-style metrics going.

Redirect GET / to something useful

If someone types https://broker.portier.io in their browser, we should show something meaningful.

Handle all unknown URLs by returning a 404

Right now we panic. We shouldn't panic.

Send reasonable security headers, including CSP, HSTS, and possibly HPKP

References:

• https://www.owasp.org/index.php/OWASP_Secure_Headers_Project#tab=Headers
• https://observatory.mozilla.org/

Set up auto-deploy pipeline for Heroku?

I'd like to automatically deploy to Heroku whenever we merge to master. Anyone opposed?

Enforce code style with rustfmt?

Many of the comments on our pull requests are concerned with code style (example). Rather than rely on falliable humans for this, let's just use rustfmt.

It's quite configurable, and we can set up Travis to ensure that PRs follow the code style.

Rate-limit login attempts

Dovetails with #69 -- how often should we allow a single email address + rp combo to request auth codes?

Use templates for the email message.

From a TODO in the code:

portier-broker/src/email.rs

Line 63 in 5631a7e

// on localhost. TODO: Use templates for the email message.

Compile-time or run-time?

Run-time of course means more files (right now just the binary and config), but also more configurability without a rebuild. For run-time, I'm leaning towards liquid.

But compile-time may be good enough for us, considering the primary goal is a central hosted service.

Handle errors and return them to the RP if possible

Implement support for Portier-native identity providers

Needs dynamic registration that's also stateless (modulo some caching).

Figure out binding between Portier RP and daemon

Can likely use the nonce parameter from OIDC's implicit flow.

Create BeforeMiddleware that redirects incoming requests to $BROKER_PUBLIC_URL

We need middleware that ensure that hitting any origin other than the configured public url should 307 redirect to the configured origin.

E.g., hitting http://portier-broker.herokuapp.com/foo?bar should send me to https://broker.portier.io/foo?bar