Skip to main content

Hooks

Hooks allow duo-server to communicate authentication and authorization credentials (received from the user) to auth-svc and receive decisions back. Auth-svc must serve the following hooks with the specified request and response formats.

The hook endpoints are configured via setting env variables in duo-server environment.

info

See the crates/auth-svc readme for more details.
You can also check implementations of these hooks in the example auth-svc

DKG Setup Validation​

This hook is invoked when a device requests a new distributed key generation (DKG).

  • Auth-svc SHOULD verify that the device-id (token) is already registered
  • Auth-svc SHOULD cache the request with token as the ID to wait for the key-id notification
  • Auth-svc MAY use the other fields for additional access control

Environment Variable: AUTH_DKG_SETUP_VALIDATOR_URL=<url>

Request JSON:

{
  "token": "hex encoded public key",
  "setup": { 
    "user_tag_{i}": ["hex", "hex", "..."],
    "...": "additional user defined tags"
  }, 
  "instance": "32 byte hex string"
}
  • token: the device ID (hex-encoded verifying key) that's requesting the DKG setup
  • setup field contains tags used by duo-server, which may contain user-defined tags from the phone
  • instance: a unique identifier for this DKG setup request

Response JSON:

"ok" | "reject"

Key ID Notification​

This hook is invoked to notify auth-svc of the key-id, allowing auth-svc to store the key-id. Key id is the identifier for the distributed key generated via DKG.

  • Auth-svc SHOULD store the key-id against the device-id (token) that requested the DKG setup. This is done so that during signgen, it can be verified that the device has access to the requested key-id
info

Key id is the identifier for the distributed key generated via DKG. Each key-id is associated with a master key, ie, the ecdsa key for chain path m/. When a user will request a signature using DSG, the key-id will be used to identify which distributed key to use.

Environment Variable: AUTH_KEY_ID_NOTIFICATION_URL=<url>

Request JSON:

{
  "token": "hex verifying key",
  "key_id": "string"
}
  • token: the device ID (hex-encoded verifying key) that requested the DKG setup
  • key_id: the identifier for the distributed key generated via DKG

Response JSON:

"ok"

DSG Setup Validation​

This hook is invoked when a device requests a new distributed signature generation (DSG).

  • Auth-svc SHOULD verify that the device-id (token) is already registered
  • Auth-svc SHOULD verify that the token has access to the requested key-id
  • Auth-svc MAY use the other fields for additional access control

Environment Variable: AUTH_DSG_SETUP_VALIDATOR_URL=<url>

Request JSON:

{
  "token": "hex verifying key",
  "setup": { 
    "key_id": ["hex encoded key id"], 
    "message": ["message to-be-signed"],
    "user_tag_{i}": ["hex", "hex", "..."]
  },
  "instance": "hex32",
  "extra": "string"
}
  • token: the device ID (hex-encoded verifying key) that's requesting the DSG setup
  • setup.key_id: the key ID that the device wants to use for signing
  • setup.message: the message that the device wants to sign
  • setup.user_tag_{i}: any user-defined tags from the phone
  • instance: a unique identifier for this DSG setup request
  • extra: contains user-defined extra information in the keyshare, IF it was set during the keygen

Response JSON:

"ok" | "reject"

Coming Soon​

  • Allow sending arbitrary access token (JWT, OAuth, etc.) from phone SDK