Expand description
Rust client for the WizePass API, version 2.
WizePass is a passwordless authentication and identity management platform.
This crate talks to the relying-party (/rp) and enrolment (/es) services
over mutual TLS and covers four areas:
- Authentication — prove a user’s identity with the WizePass app.
- Signing — have a user cryptographically sign a piece of text.
- Enrolment — issue a new WizePass to a user.
- WizePass management — list, search, revoke, and inspect licences.
§Scope
This crate speaks API v2 exclusively. There is no v1 support and no
version negotiation: the version is a constant in the request path. A future
v3 would arrive as a new major version of this crate rather than as
…RequestV3 types living alongside v2 ones.
§Quick start
The README’s example follows, compiled as a doctest so it cannot go stale.
§wizepass-rs
Rust client for the WizePass API, version 2.
WizePass is a passwordless authentication and identity management platform. This crate covers authentication, signing, enrolment, and WizePass management over mutual TLS.
use std::time::Duration;
use wizepass::{AuthenticationRequest, Client, RequestAttribute};
use wizepass::deeplink::{Operation, Scheme};
let client = Client::builder()
.api_url("https://api.wizepass.com")
.client_certificate_pem_file("rp-client.pem")?
.build()?;
let request = AuthenticationRequest::builder()
.rp_id(rp_id)
// Who is asking, for the audit trail. Required on every v2 call.
.initiator("svc-login")
.visible_tbs("Sign in to Example Corp")
.requested_attributes([RequestAttribute::CommonName])
.build();
let session = client.initiate_authentication(&request).await?;
// Show this to the user as a link or a QR code.
println!("{}", client.deeplink(&session.token, Operation::Authentication, Scheme::Custom, None));
// The argument is the total budget; the crate paces the polls within it.
let status = client
.wait_for_authentication(&session.token, "svc-login", Duration::from_secs(120))
.await?;
if status.status.is_success() {
let attributes = status.result.and_then(|r| r.requested_attributes).unwrap_or_default();
println!("signed in: {:?}", attributes.common_name);
}§Scope
This crate speaks API v2 exclusively. There is no v1 support and no version
negotiation — the version is a constant in the request path. A future v3 would
arrive as a new major version of this crate rather than as …RequestV3 types
sitting alongside v2 ones.
§Installation
[dependencies]
wizepass-rs = "1"
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }The library is named wizepass, so imports read use wizepass::Client;.
Optional features:
| Feature | Default | Effect |
|---|---|---|
env-config | off | Adds Client::from_env(), reading WIZEPASS_API_URL, WIZEPASS_INSTANCE_ID, WIZEPASS_CERT_PATH and WIZEPASS_API_KEY. |
danger-accept-invalid-certs | off | Disables TLS verification. Testing only. |
The crate is async-only and rustls-only, on aws-lc-rs — rustls’s default crypto provider,
preferring post-quantum hybrid key exchange (X25519MLKEM768). No OpenSSL is linked; aws-lc
is built from source, so building needs a C compiler. Blocking callers can
wrap it in Runtime::block_on — three lines, shown in the
Client documentation.
§mTLS
The transport is mutual TLS. You need a PEM file holding both the private key and its certificate chain.
Migrating from wizepass-java? It takes a PKCS#12 bundle; convert it once:
openssl pkcs12 -in client.p12 -out client.pem -nodesCertificates expire, so they can be rotated in place — no rebuild, no restart, and a bad PEM leaves the previous one serving traffic:
client.set_client_certificate_pem_file("rp-client.pem")?;§API keys
Some deployments also require an API key, sent as X-Api-Key. It is issued per
WizePass Setup and binds the call to that Setup’s relying parties and enrolment
services, so an application serving more than one Setup needs one client per Setup:
let client = wizepass::Client::builder()
.api_url("https://api.wizepass.com")
.client_certificate_pem_file("rp-client.pem")?
.api_key(api_key)
.build()?;Pass it exactly as issued. Keys are revocable, so one can be replaced in place like
a certificate, with client.set_api_key(...). A rejected key gives 401 with error
code invalid_api_key; a key belonging to a different Setup gives 403
api_key_setup_mismatch. Neither is worth retrying. See
Configuration.
§Documentation
- API reference — every type and method, with
worked examples on
Clientand on each request type.
§Examples
cargo run --example authenticate
cargo run --example enrolBoth read configuration from WIZEPASS_API_URL, WIZEPASS_CERT_PATH, and
WIZEPASS_RP_ID / WIZEPASS_ES_ID, plus WIZEPASS_API_KEY if the deployment
requires one.
§Development
Uses Nix/devenv:
devenv shell # or `direnv allow` once
ci # fmt + clippy + tests + docs§License
MIT. See the LICENSE file, which ships in the crate.
Note this covers the client library only. The WizePass platform and its applications are separately licensed.
Re-exports§
Modules§
- deeplink
- WizePass app deeplinks.
Structs§
- Authentication
Id - Identifies one authentication operation.
- Authentication
Request - Body for
POST /rp/auth/initiate. - Authentication
Result - The outcome of a completed authentication.
- Authentication
Status Response - Response to
POST /rp/auth/status. - Basic
Profile - A user’s given name and surname.
- Cert
Info - Certificate metadata.
- Client
- A client for the WizePass v2 API.
- Client
Builder - Builds a
Client. - Enrolment
Id - Identifies one enrolment operation.
- Enrolment
Request - Body for
POST /es/enrol/initiate. - Enrolment
Response - Response to
POST /es/enrol/initiate. - Enrolment
Service Info - Response to
GET /es/info/{esId}— one configured enrolment service. - Enrolment
Status Response - Response to
POST /es/enrol/status. - EsId
- Identifies an enrolment service.
- Info
Response - Response to
GET /rp/infoandGET /es/info— which service, which version. - Initiate
Authentication Response - Response to
POST /rp/auth/initiate. - Initiate
Signing Response - Response to
POST /rp/sign/initiate. - Licence
Response - Response to
GET /es/licence. - Page
- Which page of results to fetch, and how big.
- Requested
Attributes - Attribute values returned by the app.
- Revoke
Request - Body for
POST /es/wizepass/{esId}/revoke. - RpId
- Identifies a relying party. Supplied by WizePass when the RP is configured.
- Secret
- A value that must not reach a log: an operation token, an HMAC secret, or a push-notification token.
- Service
Error - The body WizePass returns with a non-2xx response.
- Signature
Id - Identifies one signing operation.
- Signing
Request - Body for
POST /rp/sign/initiate. - Signing
Result - The outcome of a completed signing operation.
- Signing
Status Response - Response to
POST /rp/sign/status. - Tag
- A key/value pair attached to a WizePass.
- Wizepass
- An issued WizePass.
- Wizepass
Id - Identifies a single issued WizePass.
Enums§
- Attribute
Source - Where a
Tag’s value comes from. - Enrolment
Status - Lifecycle of an enrolment operation.
- Error
- Anything that can go wrong talking to WizePass.
- Platform
- The kind of device a
Wizepasslives on. - Request
Attribute - An attribute the WizePass app should return alongside a signature.
- Request
Content - Extra content the WizePass app should return.
- Search
Attribute - Which field
Client::search_wizepassessearches on. - Status
- Lifecycle of an authentication or signing operation.
- User
Identifier Attribute - Which certificate attribute identifies a user.
- Wizepass
State - Lifecycle state of an issued
Wizepass.
Type Aliases§
- Result
- A
Resultwhose error is this crate’sError. - User
Attributes - Attributes to write into an issued certificate.