huskarl 0.9.0

A modern OAuth2 client library. 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83

<!-- cargo-reedme: start -->

<!-- cargo-reedme: info-start

    Do not edit this region by hand
    ===============================

    This region was generated from Rust documentation comments by `cargo-reedme` using this command:

        cargo +nightly reedme

    for more info: https://github.com/nik-rev/cargo-reedme

cargo-reedme: info-end -->

Huskarl provides tools for implementing secure `OAuth2` clients in rust.

This library provides several grant implementations, each driven by grant-specific
parameters that define how the grant/workflow should progress.

The library also provides a caching layer for token responses; and a HTTP authorizer
that can be used to make authenticated requests to resource servers.

## The huskarl ecosystem

This crate is one of three that fit together. Each carries its own how-to guides
and explanation in a `_docs` module:

- **`huskarl`** (this crate) — `OAuth2` **clients**: grants, token caching, and
  the request authorizer.
- [`huskarl-resource-server`](https://docs.rs/huskarl-resource-server) —
  **resource servers**: access-token validation and request authorization.
- [`huskarl-core`](https://docs.rs/huskarl-core) — the shared **foundation** the
  other two build on.

## Conformance and interoperability

Huskarl’s client is verified against the official [`OpenID` conformance
suite](https://openid.net/certification/). It passes the `OpenID Connect` Core
*Basic client* certification plan, plus the **FAPI 2.0 Security Profile** and
**Message Signing** client plans — these adding `private_key_jwt` client
authentication, `DPoP` sender-constrained tokens, and signed authorization
requests (JAR). The grants are additionally run end-to-end against real
authorization servers — Keycloak, Dex, `node-oidc-provider`, and Okta — in CI.
See the [repository](https://github.com/huskarl-rs/huskarl) for the full provider
matrix and conformance plans.

## Grants

Each grant is driven by grant-specific parameters and exchanges them for a token
at the token endpoint. The simplest need only an `exchange` call; the workflow
grants add interactive steps first. Each has a [how-to guide](https://docs.rs/huskarl/latest/huskarl/_docs/guide/) with
setup and a worked example.

- [`ClientCredentialsGrant`](https://docs.rs/huskarl/latest/huskarl/grant/client_credentials/struct.ClientCredentialsGrant.html) — RFC 6749 §4.4
- [`RefreshGrant`](https://docs.rs/huskarl/latest/huskarl/grant/refresh/struct.RefreshGrant.html) — RFC 6749 §6
- [`AuthorizationCodeGrant`](https://docs.rs/huskarl/latest/huskarl/grant/authorization_code/grant/struct.AuthorizationCodeGrant.html) — RFC 6749 §4.1
- [`DeviceAuthorizationGrant`](https://docs.rs/huskarl/latest/huskarl/grant/device_authorization/grant/struct.DeviceAuthorizationGrant.html) — RFC 8628
- [`TokenExchangeGrant`](https://docs.rs/huskarl/latest/huskarl/grant/token_exchange/struct.TokenExchangeGrant.html) — RFC 8693
- [`JwtBearerGrant`](https://docs.rs/huskarl/latest/huskarl/grant/jwt_bearer/struct.JwtBearerGrant.html) — RFC 7523

Further grants — CIBA, provider-specific flows — can be implemented in this
crate or by external crates. The [`registration`](https://docs.rs/huskarl/latest/huskarl/registration/) module implements OAuth 2.0
Dynamic Client Registration (RFC 7591).

## Guides and explanation

The API items in this crate are the **reference** documentation. For
task-oriented how-to guides — setting up each grant, choosing [client
authentication](https://docs.rs/huskarl/latest/huskarl/_docs/guide/client_authentication/), sender-constraining
tokens with [`DPoP`](https://docs.rs/huskarl/latest/huskarl/_docs/guide/dpop/), caching tokens, and making
authenticated requests — and design explanation (error handling, sharing a
refresh token store, refresh timing), see the [`_docs`](https://docs.rs/huskarl/latest/huskarl/_docs/) module.

Most applications wrap a grant in an
[`InMemoryTokenCache`](https://docs.rs/huskarl/latest/huskarl/cache/in_memory/struct.InMemoryTokenCache.html) and an
[`HttpAuthorizer`](https://docs.rs/huskarl/latest/huskarl/authorizer/struct.HttpAuthorizer.html) for the request path; every
operation returns the one concrete [`Error`](https://docs.rs/huskarl_core/latest/huskarl_core/error/struct.Error.html) type, which embeds
in your own error enum. See [caching tokens and wiring an
authorizer](https://docs.rs/huskarl/latest/huskarl/_docs/guide/caching/) and [error
handling](https://docs.rs/huskarl/latest/huskarl/_docs/explanation/error_handling/).

<!-- cargo-reedme: end -->