DID Auth SIOP OP Authenticator (Typescript)

---

Warning: This package still is in very early development. Breaking changes without notice will happen at this point!

---

A Veramo authentication plugin using the Self Issued OpenID Provider v2 (SIOP) authentication library for having clients / people conforming to the Self Issued OpenID Provider v2 (SIOPv2) and OpenID Connect for Verifiable Presentations (OIDC4VP) as specified in the OpenID Connect working group.

Self Issued OpenID Provider v2 (SIOP)

For more information about Self Issued OpenID Provider v2 (SIOP), see the documentation in the readme.

Requirements

For this plugin a DID resolver is also required. A DID resolver can be added to the agent as plugin as seen in the example below.

Available functions

• getSessionForSiop
• registerSessionForSiop
• removeSessionForSiop
• registerCustomApprovalForSiop
• removeCustomApprovalForSiop
• authenticateWithSiop
• getSiopAuthenticationRequestFromRP
• getSiopAuthenticationRequestDetails
• verifySiopAuthenticationRequestURI
• sendSiopAuthenticationResponse

The following functions can also be used on the session object without the need of a session id first.

• authenticateWithSiop
• getSiopAuthenticationRequestFromRP
• getSiopAuthenticationRequestDetails
• verifySiopAuthenticationRequestURI
• sendSiopAuthenticationResponse

Usage

Adding the plugin to an agent:

import { IDidAuthSiopOpAuthenticator } from '@sphereon/ssi-sdk-did-auth-siop-authenticator'
import { Resolver } from 'did-resolver'
import { getDidKeyResolver } from '@veramo/did-provider-key'
import { DIDResolverPlugin } from '@veramo/did-resolver'
import { getUniResolver } from '@sphereon/did-uni-client'

const agent = createAgent<IDidAuthSiopOpAuthenticator & IResolver>({
  plugins: [
    new DidAuthSiopOpAuthenticator(),
    new DIDResolverPlugin({
      resolver: new Resolver({
        ...getDidKeyResolver(),
        ...getUniResolver('lto', { resolveUrl: 'https://uniresolver.test.sphereon.io/1.0/identifiers' }),
        ...getUniResolver('factom', { resolveUrl: 'https://uniresolver.test.sphereon.io/1.0/identifiers' }),
      }),
    }),
  ],
})

Get an OP session:

const sessionId = 'example_session_id'
const opSession = await agent.getSessionForSiop({
  sessionId,
})

Register an OP session:

const sessionId = 'example_session_id'
const identifier = {
  did: 'did:ethr:0xb9c5714089478a327f09197987f16f9e5d936e8a',
  provider: 'example_provider',
  controllerKeyId: `did:ethr:0xb9c5714089478a327f09197987f16f9e5d936e8a#controller`,
  keys: [
    {
      kid: `did:ethr:0xb9c5714089478a327f09197987f16f9e5d936e8a#controller`,
      kms: 'example_kms',
      type: 'Ed25519' as const,
      publicKeyHex: '1e21e21e...',
      privateKeyHex: 'elfcvtswdbn...',
    },
  ],
  services: [],
}

const opSession = await agent.registerSessionForSiop({
  sessionId,
  identifier,
})

Remove an OP session:

const sessionId = 'example_session_id'
const opSession = await agent.removeSessionForSiop({
  sessionId,
})

Authenticate with DID auth SIOP:

It is possible to register custom approval functions as an extra confirmation before sending the authentication response. These functions can then be used as an optional parameter. It is also possible to directly provide a custom approval function.

These custom approval functions can also be provided at agent creation.

await agent.registerCustomApprovalForSiop({
  key: 'example_key',
  customApproval: (verifiedAuthenticationRequest: VerifiedAuthenticationRequestWithJWT) => Promise.resolve(),
})

const sessionId = 'example_session_id'
const stateId = 'example_state_id'
const redirectUrl = 'https://example.com'
const customApprovalKey = 'example_key'
const authenticationResponse = await agent.authenticateWithSiop({
  sessionId,
  stateId,
  redirectUrl,
  customApproval: customApprovalKey,
})

const authenticationResponse = await agent.authenticateWithSiop({
  sessionId,
  stateId,
  redirectUrl,
  customApproval: (verifiedAuthenticationRequest: VerifiedAuthenticationRequestWithJWT) => {
    return Promise.resolve()
  },
})

Get authentication request from the relying party:

For more detailed information see: Self Issued OpenID Provider v2 (SIOP)

const sessionId = 'example_session_id'
const stateId = 'example_state_id'
const redirectUrl = 'https://example.com'
const createAuthenticationResponse = await agent.getSiopAuthenticationRequestFromRP({
  sessionId,
  stateId,
  redirectUrl,
})

Get authentication request details:

For more detailed information see: Self Issued OpenID Provider v2 (SIOP)

const sessionId = 'example_session_id'
const authenticationRequestDetailsResponse = await agent.getSiopAuthenticationRequestDetails({
  sessionId,
  verifiedAuthenticationRequest: createAuthenticationResponse,
  verifiableCredentials: [credential],
})

Verify authentication request URI:

For more detailed information see: Self Issued OpenID Provider v2 (SIOP)

const sessionId = 'example_session_id'
const verifiedAuthenticationResponse = await agent.verifySiopAuthenticationRequestURI({
  sessionId,
  requestURI: createAuthenticationResponse,
})

Send authentication response:

For more detailed information see: Self Issued OpenID Provider v2 (SIOP)

const sessionId = 'example_session_id'
const authenticationResponse = await agent.sendSiopAuthenticationResponse({
  sessionId,
  verifiedAuthenticationRequest: verifiedAuthenticationResponse,
})

Installation

yarn add @sphereon/ssi-sdk-did-auth-siop-authenticator

Build

yarn build