Skip to main content

Crate wizepass

Crate wizepass 

Source
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:

FeatureDefaultEffect
env-configoffAdds Client::from_env(), reading WIZEPASS_API_URL, WIZEPASS_INSTANCE_ID, WIZEPASS_CERT_PATH and WIZEPASS_API_KEY.
danger-accept-invalid-certsoffDisables 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 -nodes

Certificates 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 Client and on each request type.

§Examples

cargo run --example authenticate
cargo run --example enrol

Both 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§

pub use chrono;
pub use semver;
pub use uuid;

Modules§

deeplink
WizePass app deeplinks.

Structs§

AuthenticationId
Identifies one authentication operation.
AuthenticationRequest
Body for POST /rp/auth/initiate.
AuthenticationResult
The outcome of a completed authentication.
AuthenticationStatusResponse
Response to POST /rp/auth/status.
BasicProfile
A user’s given name and surname.
CertInfo
Certificate metadata.
Client
A client for the WizePass v2 API.
ClientBuilder
Builds a Client.
EnrolmentId
Identifies one enrolment operation.
EnrolmentRequest
Body for POST /es/enrol/initiate.
EnrolmentResponse
Response to POST /es/enrol/initiate.
EnrolmentServiceInfo
Response to GET /es/info/{esId} — one configured enrolment service.
EnrolmentStatusResponse
Response to POST /es/enrol/status.
EsId
Identifies an enrolment service.
InfoResponse
Response to GET /rp/info and GET /es/info — which service, which version.
InitiateAuthenticationResponse
Response to POST /rp/auth/initiate.
InitiateSigningResponse
Response to POST /rp/sign/initiate.
LicenceResponse
Response to GET /es/licence.
Page
Which page of results to fetch, and how big.
RequestedAttributes
Attribute values returned by the app.
RevokeRequest
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.
ServiceError
The body WizePass returns with a non-2xx response.
SignatureId
Identifies one signing operation.
SigningRequest
Body for POST /rp/sign/initiate.
SigningResult
The outcome of a completed signing operation.
SigningStatusResponse
Response to POST /rp/sign/status.
Tag
A key/value pair attached to a WizePass.
Wizepass
An issued WizePass.
WizepassId
Identifies a single issued WizePass.

Enums§

AttributeSource
Where a Tag’s value comes from.
EnrolmentStatus
Lifecycle of an enrolment operation.
Error
Anything that can go wrong talking to WizePass.
Platform
The kind of device a Wizepass lives on.
RequestAttribute
An attribute the WizePass app should return alongside a signature.
RequestContent
Extra content the WizePass app should return.
SearchAttribute
Which field Client::search_wizepasses searches on.
Status
Lifecycle of an authentication or signing operation.
UserIdentifierAttribute
Which certificate attribute identifies a user.
WizepassState
Lifecycle state of an issued Wizepass.

Type Aliases§

Result
A Result whose error is this crate’s Error.
UserAttributes
Attributes to write into an issued certificate.