Decentralized Identity Authentication via JOSE
did-auth-jose is a library that provides JOSE encryption, decryption, signing, and verifying capabilities through a key and algorithm extensible model, as well as two authentication flows for use with decentralized identities (DIDs).
$ npm install @decentralized-identity/did-auth-jose
OIDC Authentication Flow
OIDC Authentication is loosely based off of OpenID Connect Self-Issued ID Token Protocol. The
AuthenticationResponse objects are modeled after OIDC request and response objects. We have proposed an authentication protocol in this OIDC Authentication document.
DID Authentication uses two to three JSON Web Tokens (JWT) per request. The first is an outer JSON Web Encryption (JWE), and the second is an inner JSON Web Signature (JWS), both utilizing the public private key pair of each DID retrieved from their DID Document. An optional third JWT access token may be included in a JWS header. This format ensures the content is encrypted end to end and independently verifiable. Each JWS contains a nonce header to associate requests with responses.
Authentication is encapsilated in an Authentication containing private keys for decryption, cryptographic algorithms, and a Universal Resolver. Due to the extensible model, implementations for algorithms and a universal resolver must be passed in. A standard set of algorithms will be used by default. Currently RSA, AES, and Secp256k1 is supported.
DID Documents are retrieved by the Universal Resolver. All documents are expected to conform to the DID spec. An simple
http-resolver is included in the hub-node-core package, utilizing a remote Universal Resolver listening over http.
The flow can be invoked by three methods, starting with the sender:
async getAuthenticatedRequest ( content: string, privateKey: PrivateKey, recipient: string, accessToken?: string ): Promise<Buffer>
which takes the message content, the private key used for signing, the did this message is intended for, and optionally an access token JWT to include in the JWS header.
Upon receipt of the encrypted request, the receiver uses:
async getVerifiedRequest ( request: Buffer, accessTokenCheck: boolean = true ): Promise<VerifiedRequest | Buffer>
which decrypts the request using
Authentication's private keys, retrieves the sender's DID Document and signing key, and verifys the signature of the JWS. If
true, it will require the JWS contain an access token in the JWS header and verify the token. If no token was included, the returned
Promise will resolve to a
Buffer containing a message back to the sender with an appropriate access token. This behavior may change in the future upon defining a specific endpoint for recieving acces tokens. If successful, a
VerifiedRequest option is returned, containing the plaintext request in the
VerifiedRequest.request property, along with additional metadata.
The reciever may then respond to the message using the same keys with the
async getAuthenticatedResponse ( request: VerifiedRequest, response: string ): Promise<Buffer>
This method takes the original request for public key metadata, and the plaintext response, and returns a
Buffer using the same keys if possible.
The sender may decrypt the response using the same
getVerifiedRequest method with the
accessTokenCheck set to
The authentication flow is explained in greater detail in the Authentication document.
This package includes JWS and JWE classes (
JweToken respectively) which utilize an extensible cryptographic model,
CryptoFactory. This factory is constructed from
CryptoSuite which implement specific public private key pair generation, encryption, decryption, signing, and verifying algorithms. To add support for an algorithm, simply include the
CryptoSuite that implements that algorithm to the
JOSE extensions are explained in greater detail in the CryptoSuite document.