Optionally send custom headers in authentication call

[f3ndot]

Complex systems that offer Two Factor Authentication with their OAuth 2.0 implementation need to send additional context via the HTTP headers. This pattern has been observed in the wild by such systems such as GitHub. Because of the restrictions of OAuth 2.0 RFC, only headers can be used for additional context, not request/response bodies.

This could be seen as a counterpart to #1012, where using both features allow bi-directional context enabling 2FA, brute force lockouts, etc.

---

An different approach that functions the same would be

authenticator.set('headers', { foo: 'bar' });
authenticator.authenticate('username', 'password');

Which is consistent with clientId but I feel like my approach may be more intuitive for the user.

[marcoow]

I'm actually not 100% familiar with the use cases for custom headers for OAuth 2.0. I think the main question is whether headers are actually static and would always has the same value for all requests the app makes (like clientId) in which case I think a property for setting them would be a better fit or whether they might be dynamic so that their value might not be known until calling the session's authenticate method in which case introducing an additional argument might be the better API choice indeed.

[f3ndot]

Ah! My bad for not explaining. The header contains a dynamic value, which is the One Time Pad code a user receives on their device:

Client: HTTP POST /api/oauth/tokens (username & password payload)
Server: HTTP 401 (response has header 'X-Vendor-OTP: required')
Client: HTTP POST /api/oauth/tokens (username & password payload, and 'X-Vendor-OTP: 123456' header)
Server: HTTP 200

In the context of 2FA, the headers in the response inform the user that their authentication is insufficient (although username & password succeeded) and additional information is required. The user then either receives their SMS code or opens their offline 2FA app to which they replay their credentials, but sending the 30 second challenge code or One Time Pad to the server for verification.

OTP values are:

• Generated from a unique secret to each user
• Are time based, expiring every 30 seconds

[marcoow]

Thanks for the explanation! I guess your idea would be to make the first POST in the example yourself (not using the session's authenticate method) and then for the second request pass the user's credentials as well as the 2FA code as a header to the session's authenticate method?

I wonder whether there's a way to somehow combine all of that in the authenticator so that you'd only have to invoke the session's authenticate method once with the user's credentials and the authenticator would handle the 2FA stuff, e.g. via calling a callback that would return the 2FA code or so…

[f3ndot]

@marcoow My idea would be two authenticate calls. The design of Two-Factor Auth is to not "show your hand" that an account has it enabled. For all intents and purposes, the first authentication call must be fully formed & valid except, if said account has 2FA-enabled, it's forced to reject despite valid authentication. This rejection, combined with context enabled by #1012, informs the Ember app that a subsequent authenticate call must be performed but requires an additional OTP code sent through the request header (this PR).

It is up to the developer, who wants to enable 2FA with your addon, to check the server's response headers, drive UX if present, then allow the user to trigger a second authentication attempt.

Not all accounts in a system would have 2FA, so the first call must be the regular ember-simple-auth code paths. It's the optional presence of headers that can require an additional request, which is so similar to the first (just additive request headers), so it makes sense to re-use ember-simple-auth again.

An example login controller would look like this, in my mind:

// A login controller of some sort

// ...
username: '',
password: '',
otpCode: '',
displayAdditonalOtpField: false,

actions: {
  login() {
    let headers;
    if (this.get('displayAdditonalOtpField')) {
      headers['X-Vendor-OTP-Code'] = this.get('otpCode');
    }

    this.get('session').authenticate('authenticator:oauth2', email, password, headers).then(() => {
      this.send('doSuccessfulLoginStuff');
    }, (xhrObject) => {
      if (xhrObject.getResponseHeader('X-Vendor-OTP') === 'required') {
        // User successfully authenticated, backend wants additional verification.
        // Shows verification code field for user to fill. They then can re-trigger `login` action
        this.set('displayAdditonalOtpField', true);
        return;
      }
      this.send('doFailedLoginStuff');
    });
  },
  // ...
}

[f3ndot]

I'm open to, but can't think of a way, for us to encapsulate this multiple authenticate call logic into the addon since it requires additional user input at the second stage and different developers will have different UX flows for controlling their 2FA experience.

The example I illustrated above is the cleanest way, in my opinion, with the ember-simple-auth authenticate call being written once and headers being set depending on the state of the app-- which is dictated by the backend failure context.

[marcoow]

Yeah, that makes sense.

[marcoow]

if (isEmpty(keys(options.headers))) {

[f3ndot]

@marcoow thank you so much. By you accepting these two enhancements, you've unblocked the ability for Ember developers to implement both Two-Factor Authentication and detecting Brute Force lockouts ❤️

[marcoow]

just one minor style comment