Prior to this commit, individual providers did not handle
redirect-uri. They would set the field to `Nothing` and then
this library would build a callback using the app's url-renderer.
This means that apps had to use approot static, because such
redirect-uri's have to be absolute.
This minor change just respects any redirect-uri a provider has
set already. That mean that apps that must use a relative
approot can now use our library as long as they use a provider that
handles redirect-uri for them (ensuring it's absolute by whatever
means it can) ahead of our own callback construction.
The only breaking change seems to be the error type, which we were
already wrapping in `CPP` and our own `Errors` synonym for 2.7. All this
change does is add a 2.9 case and move some thing around so it's
syntactically nicer.
This is the same as the `AzureAD` plugin except:
1. It uses tenant-specific `microsoftonline.com` v2 OAuth2 endpoints
(hence the name), which means accepting a new Tenant Id argument
2. It uses a space instead of `,` as the scopes separator
Users of multi-tenant apps can provide a Tenant Id of `"common"`. I'm
also not certain if the space-vs-comma scopes separator represents a bug
in the `AzureAD` plugin, or just a difference in the actual v2 APIs.
This inherits the behavior of using email address as the `credIdent`
although this is definitely an `id` field in the User Response. I'm not
sure if there are trade-offs one way or another. Using `id` could mean
transparently handling Azure users changing their email, but I suspect
your identity is implicitly tied to email within Azure anyway, so that
would not be a case we'll ever see.
In the future, we can deprecate the `AzureAD` plugin and suggest users
migrate to this one.
This required a lot of CPP refactoring and extension. I plan to shift
our lower bound and target only the newer hoauth2 soon, but I'd like to
get out a compatible version first, which this aims to do.
The comments in Compat.hs try to explain the gymnastics we have to
endure to get there. I'm sorry, it's not ideal.
The new major version improves the naming of the fields of the OAuth2
record type. This type is central to this library and we leak it freely.
Users who make their own plugins are expected to construct values of
this type to pass into our functions, this makes the new version
disruptive to our code and our users'.
We have two options:
1. Update and release our own new major version
The major downside is that the current LTS resolver will then not
update beyond our currently-released version. We have no immediate
plans for new features in this library, but if we have bugs reported
to be fixed we would either have to manage a complex backporting or
ask our Stack users to wait for the next major LTS, which has
historically been many months.
Users who wish to use our new version would need to also bring in
hoauth2, and who knows what else.
2. Release a fully-compatible update
As mentioned, we leak OAuth2(..) through this library's interface. In
order to be truly backwards-compatible, we would have to use CCP to
define an "old style" OAuth2 and use that throughout, such that
in-the-wild OAuth2 values continue to work as-is.
This would not be a good long-term solution as it introduces a fair
amount of naming confusion and will lead to import conflicts for any
users who also import hoauth2-2.0 modules in the same project.
3. Release a mostly-compatible update
This is the path this commit explores. We can update our own code to
be hoauth2-2.0 compatible and use CPP to define the hoauth2-2.0-like
OAuth2 if we're still on hoauth2-1.x.
This gets us compiling in either case and "forward functional", with
the exception of users who define their own plugins (which is rare).
Because of that use-case, this should technically be a major version
bump for ourselves (though I'm open to the argument we could treat
the local-provider use-case differently), however it is still better
than Option 1 in a few ways:
- We still compile with hoauth2-1.x, so can be brought in easily as
an isolated extra-dep
- If there is a reported bug that we decide to only fix in the newer
versions, the path for the user is better: they can pull us as an
extra-dep and likely need no changes. Even if they're doing a
custom plugin, the required changes are minor
Prior to this commit, some errors would be thrown (missing parameter,
invalid state, incorrect approot) while others would be handled via the
set-message-redirect approach (handshake failure, fetch-token failure,
etc).
This commit consolidates all of these cases into a single DispatchError
type, and then uses MonadError (concretely ExceptT) to capture them all
and handle them in one place ourselves.
It then updates that handling to:
- Use onErrorHtml
onErrorHtml will, by default, set-message-redirect. That make this
behavior neutral for users running defaults. For users that have
customized this, it will be an improvement that all our error cases
now respect it.
- Provided a JSON representation of errors
- Attach a random correlation identifier
The last two were just nice-to-haves that were cheap to add once the
code was in this state.
Note that the use of MonadError requires a potentially "bad" orphan
MonadUnliftIO instance for ExceptT, but I'd like to see that instance
become a reality and think it needs some real-world experimentation to
get there, so here I am.
When the state token is sent to an OAuth2 provider, it undergoes
%-encoding as a URL parameter. Presumably, the OAuth2 provider decodes
it as part of handling things (because it would take work to prevent
their own web frameworks from doing so), and then re-%-encodes it coming
back to us again as a callback parameter.
For us, and all existing providers, + is not a %-encoded character, so
it's sent as-is and sent back as-is. So far so good.
ClassLink, though, chooses to decode + to space. I'm not aware of the
actual spec or if this is a reasonable thing to do, but they do. This
results in them sending %20 back to us, which doesn't match and we fail.
We can't predict or prescribe what providers do in this area, so our
options are:
- Look for a match in our Session as-is OR with spaces replaced by +
This is harder than it sounds: a token could contain +'s or spaces,
and we'd be getting back only spaces. To succeed, we'd actually have
to check every permutation of space/+ substitution.
- Filter + from our tokens
The only downside is we may generate slightly fewer than 30
characters, and so produce slightly less secure tokens.
I chose this option.
- Generate tokens without + to begin with
This would be ideal, but I'm just not familiar enough with
Crypto.Random. I would happily accept a PR to use this option.
hoauth2's fetchAccessToken provides credentials in the Authorization
header, while fetchAccessToken2 provides them in that header but also
the POST body.
It was discovered that some providers only support one or the other, so
using fetchAccessToken2 would be preferred since it should work with
either. This happened in #129.
However, we discovered at least one provider (Okta) that actively
rejects requests unless they're supplying credentials in exactly one
place:
Cannot supply multiple client credentials. Use one of the following:
credentials in the Authorization header, credentials in the post
body, or a client_assertion in the post body."
This patch reverts back to fetchAccessToken, but makes it possible to
for client to use fetchAccessToken2 if necessary via alternative
functions.
- Update to ghc-8.8 / lts-16.0
- Update to hoauth2 >= 1.11.0
- authGetBS has pre-encoded errors a v1.9
- oauthClientSecret is Maybe at v1.11
- Tweak non-default Resolvers as required
Previously:
- System.Random, which seeds from system time (possible attack)
- 30 characters, a-z (low entropy)
Now:
- Crypto.Random, accepted as "cryptographically secure"
- 64 random bytes, Base64-encoded
cryptonite was already a transitive dependency, so there is really no
downside to this.
Fixes#132.
