Skip to main content

Configuring Wallet Provider Backend

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 provider backend handles wallet attestations, app integrity verification, app version lifecycle, and more.

Configuration​

Any parameter below can be placed under params.public or params.private. The only difference is visibility: public values are returned when you fetch the provider's config via the API; private values are not.

walletProvider:
  PROCIVIS_ONE:                            # Instance name (choose any identifier)
    type: PROCIVIS_ONE                     # Must be exactly "PROCIVIS_ONE"
    display: walletProvider.procivisOne
    params:
      public:
        walletName: "Example Wallet"
        walletLink: "https://example.com"
        walletClientId: "eudiw-example"
        walletRegistration: OPTIONAL

        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

        walletInstanceAttestation:
          expirationSeconds: 86400
          revocationMethod: TOKENSTATUSLIST
          statusPeriodSeconds: 2678400

        walletKeyAttestation:
          expirationSeconds: 2678400
          revocationMethod: TOKENSTATUSLIST
          statusPeriodSeconds: 2678400

        eudiWalletInfo:
          providerName: "Example Provider"
          solutionId: "EXAMPLE_PROVIDER"
          solutionVersion: "1"
          solutionCertificationInformation: "https://example.com/certification"
          wscdType: HYBRID

        walletCertification: "https://example.com/certification"

        signerIdentifierTypes: ["CERTIFICATE"]

        deviceAuthLeewaySeconds: 60

        appVersion:
          minimum: "v1.50.0"
          minimumRecommended: "v1.60.0"
          reject:
            - "v1.51.3"
          updateScreen:
            link: "https://example.com/update"

        featureFlags:
          ecosystemsEnabled: true
          ecosystemsEnforcementEnabled: false
          refreshCredentialBatchEnabled: true
          documentSigningEnabled: true

        documentSigners:
          - SIGN8

Wallet identity and registration​

  • walletName — display name for the wallet.
  • walletLink — URL associated with the wallet, shown to end users.
  • walletClientId — static client ID used for WIA issuance.
  • walletRegistration — registration policy for wallet units (for example, OPTIONAL).

App integrity and attestation​

App integrity verification​

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

integrityCheck applies once, to the wallet app as a whole. If it's configured, a wallet unit must pass it before it can register and receive attestations. It is not currently enforced for the WEB wallet type (the Business Wallet).

This is enabled by default. If you set integrityCheck.enabled to false, wallets can register and request and receive attestations freely.

Wallet Instance Attestation (WIA)​

walletInstanceAttestation:
  expirationSeconds: 86400            # Attestation validity
  revocationMethod: TOKENSTATUSLIST   # Must match a revocation provider of type TOKENSTATUSLIST
  statusPeriodSeconds: 2678400        # Revocation status maintenance period

WIAs verify the integrity and authenticity of the wallet application.

expirationSeconds and statusPeriodSeconds control two separate expiry claims inside the WIA. For the full definitions, see the Wallet Unit Attestation specification (TS3), Section 2.4 — in short:

  • expirationSeconds sets the WIA's own token-level expiry: the point after which the WIA itself is no longer valid to present to an issuer. An issuer receiving an expired WIA should reject it.
  • statusPeriodSeconds sets a second, nested expiry carried inside the WIA (in the client_status claim). This advertises how long the Wallet Provider is committing to keep that WIA's revocation status current on the status list. The ARF requires this nested expiry to be at least 31 days past the token-level expiry at the moment the WIA is presented, so in practice statusPeriodSeconds should be set to at least 31 days (2678400): worst case, a WIA is presented right as it hits expirationSeconds, and the status commitment still needs 31 days of runway from that point.
    • At least for PIDs, this caps what the issuer can responsibly do downstream. A credential issued off the back of this WIA should not have a validity period that outlives the status commitment, since the issuer can no longer rely on fresh revocation information once it does.

Without revocationMethod configured, there is nothing to check the WIA against — it cannot be revoked and remains valid until it expires.

Revocation: when a wallet unit is revoked, the system updates the status of every WIA issued to that unit that is still within its status maintenance period — not just the WIA currently in use. Anything whose statusPeriodSeconds window has not lapsed yet gets its status flagged.

Wallet Key Attestation (KA)​

walletKeyAttestation:
  expirationSeconds: 2678400
  revocationMethod: TOKENSTATUSLIST
  statusPeriodSeconds: 2678400

Key Attestation verifies cryptographic keys generated by wallet instances. This was previously configured under walletUnitAttestation — the parameter is now named walletKeyAttestation to match current ARF terminology.

The same expirationSeconds / statusPeriodSeconds logic described above for the WIA applies here — the nested expiry lives in the KA's key_storage_status claim instead of client_status, but the same 31-day minimum and the same revocation behavior on wallet unit revocation apply.

EUDI Wallet metadata and certification​

eudiWalletInfo:
  providerName: "Example Provider"
  solutionId: "EXAMPLE_PROVIDER"
  solutionVersion: "1"
  solutionCertificationInformation: "https://example.com/certification"
  wscdType: HYBRID

walletCertification: "https://example.com/certification"

These fields supply the certification-related information Procivis One includes in your wallet's attestation claims — solution-level certification via eudiWalletInfo, and certification of the wallet's key storage (WSCD/keystore) via walletCertification.

Signer identifier types​

signerIdentifierTypes: ["CERTIFICATE"]

Identifies the type used to sign attestations issued to wallet units. Currently only CERTIFICATE is supported.

Device authentication​

deviceAuthLeewaySeconds: 60

Leeway, in seconds, allowed for clock skew when validating device authentication.

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"
  updateScreen:
    link: "https://example.com/update"   # URL for version update information

Feature flags​

featureFlags:
  ecosystemsEnabled: true
  ecosystemsEnforcementEnabled: false
  refreshCredentialBatchEnabled: true
  documentSigningEnabled: true
  • ecosystemsEnabled — enables trust ecosystem functionality for wallet app users, including trust collection subscriptions and the wallet's ability to restrict interactions to trusted entities. This is also what governs the trust list syncing described in Automated syncing above. See the Ecosystem Enforcement overview for the concept, or the wallet and verifier provider's own ecosystem enforcement doc for the provider-specific view.
  • ecosystemsEnforcementEnabled — enables setting configuration.enforceEcosystemAsHolder on organizations. See the ecosystem enforcement doc linked above.
  • refreshCredentialBatchEnabled — enables wallet app users to request a new batch of a credential. See the wallet's batch credential logic in Wallets.
  • documentSigningEnabled — enables wallet app users to sign documents using configured QES providers. See Document signing below.

Document signing​

documentSigners:
  - SIGN8

Enables Qualified Electronic Signature (QES) document signing via Sign8. See Wallet-Centric Approach for details.

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 ecosystemSchemaId, the managed instance will not 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

Usage​

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

Next steps​