nuid.sdk.api.auth — nuid/sdk 0.3.0

The auth namespace provides an interface to simplify communicating with the NuID Auth API. You will need an API Key from the NuID Developer Portal in order to make authenticated calls to the Auth API.

NOTE: You will need to configure this HTTP client with your API Key. See merge-opts! for configuration instructions.

-get clj

(-get path)

Perform a GET request against the Auth API.

-parse-body clj

(-parse-body body)

-post clj

(-post path data)

Perform a POST request against the Auth API.

-url clj

(-url path)

Construct a URL from the given path and the ::host set in default-opts.

challenge-get clj

(challenge-get credential)

Get a credential challenge from the API, usually during login flow. The returned challenge can be used to generate a proof from the user's secret. Used in conjunction with credential-get to retrieve the credential and challenge-verify to verify the challenge with the proof generated client-side. credential must conform to the :nuid/credential spec.

The successful response body will contain the following string keys:

• "nuid.credential.challenge/jwt" - JWT containing the challenge claims.

Non-200 responses will throw an exception.

(try
  (let [user           (db/fetch-user :email email-address)
        credential-res (auth/credential-get (:nuid user))
        credential     (get-in credential-res [:body "nuid/credential"])
        challenge-res  (auth/challenge-get credential)
        challenge-jwt  (get-in challenge-res [:body "nuid.credential.challenge/jwt"])]
   ;; Return challenge-jwt to user so they can generate a proof
  )
  (catch Exception ex
    ;; challenge get failed))

challenge-verify clj

(challenge-verify challenge-jwt proof)

Verify a credential challenge with a proof generated from the challenge-jwt claims and the user's secret. This proof is generated by calling Zk.proofFromSecretAndChallenge(secret, challenge) (available in the npm package @nuid/zk).

proof must conform to the :nuid.credential/proof spec.

The successful response body will by empty, if the response is 200 then the user has been authenticated succesfully and you can issue your user session. (= 200 (:status res))

Non-200 responses will throw an exception.

(try
  (auth/credential-create verified-credential)
  ;; ... issue session ...
  (catch Exception ex
  ;; verification failed))

See @nuid/zk See @nuid/cli

credential-create clj

(credential-create verified-credential)

Create a credential from a verified credential (meaning a credential generated from the user's secret), usually during user registration. The response body contains the new Credential and the user's unique NuID which should be used as a reference to the user's credential for later authentication attempts.

Credential must conform to the :nuid.credential/verified spec and can be obtained by calling Zk.verifiableFromSecret(secret) (available in the npm package @nuid/zk).

The successful response body will contain the following string keys:

• "nu/id" - The unique NuID representing the credential.
• "nuid/credential" - The newly minted credential.

Non-200 responses will throw an exception.

(try
  (let [res        (auth/credential-create verified-credential)
        nuid       (get-in res [:body "nu/id"])
        credential (get-in res [:body "nuid/credential"])]
  ;; store nuid along with user record
  )
  (catch Exception ex
    ;; credential create failed))

See @nuid/zk See @nuid/cli

credential-get clj

(credential-get nuid)

Fetch a credential by it's unique nuid which can be extracted from the response to credential-create. Credential will conform to the :nuid/credential spec.

The successful response body will contain the following string keys:

• "nuid/credential" - The fetched credential.

Non-200 responses will throw an exception.

(try
  (let [user       (db/fetch-user :email email-address)
        res        (auth/credential-get (:nuid user))
        credential (get-in res [:body "nuid/credential"])]
  ;; fetch a credential challenge perhaps?
  )
  (catch Exception ex
    ;; credential create failed))

Generally you will end up storing the NuID with your user record during registration. Later during login use the NuID to fetch the credential using this method, passing the returned credential from the response body to challenge-get.

default-opts clj

Default options for communicating with the NuID Auth API. Currently supported keywords are ::api-key and ::host.

merge-opts! clj

(merge-opts! opts)

Merge opts with default-opts. Currently only supported keywords are ::api-key and ::host.

NOTE: You must set the ::api-key or all HTTP requests will fail.

;; during env/server setup
(auth/merge-opts! {::auth/api-key "my api key"})

;; All handlers are now configured to talk to the API
;; with the correct Host and API Key
(auth/credential-get some-nuid)