Skip to main content

Configure Wallet Provider

Procivis One supports operating as a wallet provider: an organization that issues and manages wallet apps for end users. This is a defined role in the EU Digital Identity (EUDI) regulatory framework, but the configuration applies equally to non-EUDI deployments. The settings below control how the system handles wallet attestations, app integrity verification, and app version lifecycle management.

To enable wallet providing, you must configure a wallet provider instance with three required sections: wallet instance attestation, key attestation, and wallet registration policy.

Minimal configuration​

Here's a minimal configuration to enable wallet provider functionality:

walletProvider:
  PROCIVIS_ONE:            # Instance name (choose any name)
    type: PROCIVIS_ONE     # Must be exactly "PROCIVIS_ONE"
    display: walletProvider.procivisOne
    params:
      public:
        walletName: "My Wallet"
        walletLink: "https://example.com"
        walletRegistration: OPTIONAL
        walletInstanceAttestation:
          expirationSeconds: 86400
          integrityCheck:
            android:
              bundleId: com.example.wallet
              signingCertificateFingerprints:
                - "FA:C6:17:..."
              trustedAttestationCAs:
                - "-----BEGIN CERTIFICATE-----\n..."
            ios:
              bundleId: com.example.wallet
              trustedAttestationCAs:
                - "-----BEGIN CERTIFICATE-----\n..."
              enforceProductionBuild: false
        walletUnitAttestation:
          expirationSeconds: 2678400
        deviceAuthLeewaySeconds: 60

The instance name (PROCIVIS_ONE in this example) can be any identifier you choose. However, the type field must be exactly PROCIVIS_ONE to invoke the correct provider implementation.

Wallet instance attestation (WIA)​

WIAs verify the integrity and authenticity of the wallet application.

Required fields:

walletInstanceAttestation:
  expirationSeconds: 86400
  integrityCheck:
    android:
      bundleId: com.example.wallet
      signingCertificateFingerprints:
        - "FA:C6:17:..."
      trustedAttestationCAs:
        - "-----BEGIN CERTIFICATE-----\n..."
    ios:
      bundleId: com.example.wallet
      trustedAttestationCAs:
        - "-----BEGIN CERTIFICATE-----\n..."
      enforceProductionBuild: false
note

"Wallet Instance Attestation" (WIA) was previously called "Wallet App Attestation" (WAA) in the EU Architecture Reference Framework (ARF). Our code interfaces have been updated to reflect this terminology change.

When WIA is configured, the system validates:

  • Certificate changes against trusted platform certificate authorities
  • App bundle identifiers match configured values
  • (iOS) Apps are production builds if enforceProductionBuild is true

Key Attestation (KA)​

Key Attestation verifies cryptographic keys generated by wallet instances.

note

Key Attestation (KA) was previously covered under the umbrella term "Wallet Unit Attestation" (WUA). WUA is now used more broadly to represent all of a wallet unit's attestations (both KA and WIA). Our config schema has not yet been updated to reflect this — the walletUnitAttestation parameter below configures what the ecosystem now calls Key Attestation (KA).

Required fields:

walletUnitAttestation:
  expirationSeconds: 2678400          # Attestation validity

Revocation support​

To enable attestation revocation:

walletUnitAttestation:
  expirationSeconds: 2678400
  revocationMethod: TOKENSTATUSLIST  # Must match the name of a revocation provider with type `TOKENSTATUSLIST`

Without a revocation method configured, key attestations cannot be revoked and are valid until they expire.

Automated syncing​

You can automatically provision certain assets to managed instances. All syncing described below occurs when performing the ecosystem sync task:

POST /api/task/v1/run

{
  "name": "ECOSYSTEM_SYNC",
}

or the corresponding runTask mobile method.

Enabling​

Setting up automated syncing follows a general pattern:

  • Enable the ecosystem for the providing organization
  • Associate the item with the corresponding ecosystem (described below)
  • Any instances which enable that ecosystem will automatically get new assets provisioned to them when running the ecosystem syncing task

Trust lists​

When creating trust collections, each collection must be associated with an ecosystem. All managed instances which enable an ecosystem automatically get the trust lists associated with that ecosystem.

Limitations with trust list syncing:

  • The Core's remote resource fetching size limit applies; this is set in globalSettings.httpClient.maxResponseSize. Any trust list larger than your configured limit can not be synced.
  • For any managed instance with local trust lists, local lists take precedence over synced lists when list names clash. This currently only applies to managed instances of the Desk (server).

Schemas​

When creating credential schemas and proof schemas, you can include the ecosystem parameter to associate the schema with an ecosystem. All managed instances which enable an ecosystem get the schemas associated with that ecosystem.

Limitations with schema syncing:

  • If the provider deletes a schema and recreates it with different content but the same schemaId, the managed instance does not know to re-import the new schema.

User authentication and notifications​

You can extend wallet unit onboarding to include account creation with an identity provider, then use the Notification Service to communicate with end users.

walletProvider:
  PROCIVIS_ONE:
    type: PROCIVIS_ONE
    display: walletProvider.procivisOne
    params:
      public:
        ...
        userAuthentication:
          required: true              # If true, users must complete account creation to activate the wallet unit
          identityProvider: keycloak  # Configure an ID provider
          clientId: one-wallet
          redirectUri: https://wallet.example.com/auth/callback
          tokenValidation:
            aud: one-wallet
            iss: https://keycloak.example.com/realms/one
            jwksUri: https://keycloak.example.com/realms/one/protocol/openid-connect/certs

Other configurations​

Client ID​

Set a static client ID for WIA issuance:

walletClientId: "eudiw-abca"

EUDI Wallet metadata​

Include general_info according to EUDI Wallet technical specifications:

eudiWalletInfo:
  providerName: "Example Provider"
  solutionId: "EXAMPLE_PROVIDER"
  solutionVersion: "1"
  wscdType: HYBRID

App version requirements​

Enforce minimum app versions and block specific releases:

appVersion:
  minimum: "v1.50.0"                     # Required minimum version. Earlier versions are blocked
  minimumRecommended: "v1.60.0"          # Recommended minimum version. End users are suggested to update the app
  reject:                                # Explicitly blocked versions
    - "v1.51.3"
    - "v1.51.4"
  updateScreen:
    link: "https://example.com/update"   # URL for version update information

The wallet app retrieves this information from /ssi/wallet-provider/v1/{walletProvider} to enforce version requirements and recommendations.

Complete configuration example​

Here's a fully configured wallet provider:

walletProvider:
  PROCIVIS_ONE:
    type: PROCIVIS_ONE
    display: walletProvider.procivisOne
    params:
      public:
        walletName: "Example Wallet"
        walletLink: "https://example.com"
        walletClientId: ""
        walletRegistration: OPTIONAL
        walletInstanceAttestation:
          expirationSeconds: 86400
          integrityCheck:
            android:
              bundleId: com.example.wallet
              signingCertificateFingerprints:
                - "FA:C6:17:45:DC:50:D6:..."
              trustedAttestationCAs:
                - "-----BEGIN CERTIFICATE-----\n..."
            ios:
              bundleId: com.example.wallet
              trustedAttestationCAs:
                - "-----BEGIN CERTIFICATE-----\n..."
              enforceProductionBuild: true
        walletUnitAttestation:
          expirationSeconds: 2678400
          revocationMethod: TOKENSTATUSLIST
        deviceAuthLeewaySeconds: 60
        appVersion:
          minimum: "v1.50.0"
          minimumRecommended: "v1.60.0"
          reject:
            - "v1.51.3"
          updateScreen:
            link: "https://example.com/update"
        eudiWalletInfo:
          providerName: "Example Provider"
          solutionId: "EXAMPLE_PROVIDER"
          solutionVersion: "1"
          wscdType: HYBRID
        featureFlags:
          trustEcosystemsEnabled: true
        trustCollections:
          - id: 00000000-0000-0000-0000-000000000000
            logo: "https://example.com/trust-collection-logo.png"
            displayName:
              en: "Example Trust Ecosystem"
            description:
              en: "Credentials issued by members of this ecosystem meet Example's trust requirements."

Next steps​