Configuration guidelines

Edit online

Following are configuration guidelines when configuring the IBM® Verify Identity Access Digital Credentials environment.

  1. Server Trust Configuration: The IBM Verify Identity Access Digital Credentials service must be configured to trust the local server certificate for self-communication. This CA certificate must be supplied by using the general.tls.ca_key_file YAML configuration entry. The server certificate must be CA-signed certified and not self-signed.
  2. OAuth Provider Configuration: The default OAuth provider must be provisioned with an administrator user, who is specified by using the general.admin YAML configuration entries. The scope within the access token must contain the admin field for the service to recognize the user as an administrator.
  3. Holder Configuration: For a 'holder', the subject field from the access token is used as the agent name.
  4. Database Configuration: The IBM Verify Identity Access Digital Credentials service attempts to connect to the database (as defined by the general.wallet.name configuration entry) and create the required tables during initialization. If a PostgreSQL database server is being used the database is created if it does not exist. To create the database, the user must have access to the default postgres database and the authority to create new databases. For other database types the database must exist.

    If you are running the IBM Verify Identity Access Digital Credentials container on IBM Verify Identity Access Container Platform version 11.0.1.0 or later and using the internal runtime database access procedure, you must ensure that the general.wallet.name configuration matches the name of the user who is created for database access.

  5. Service URL: The general.url configuration option specifies the root service URL for the environment. This URL is reflected in did:web links in credentials such as those formatted as JSON-LD. If this value is changed, existing credential definitions and credentials referencing this did:web URL will no longer function unless appropriate external redirects are configured. A credential definition can be updated for future use by rotating the associated assertion key by using the appropriate PATCH API. For more information, see Rotating an assertion key.
  6. TLS listening configuration: By default, the service listens only on an HTTPS connection. The YAML specification provides a method to enable an HTTP listener. This option is intended only for testing and proof-of-concept purposes and must not be used in a production deployment.
  7. Encrypt YAML secrets: The YAML specification describes a mechanism for encrypting secrets that are required in the YAML configuration file. It is recommended that you use this option wherever possible.
  8. TLS backend service connections: Although YAML configuration options exist for connecting to backend services such as databases without TLS enabled, these options are intended only for testing and proof-of-concept purposes and must not be used in a production deployment.
  9. Database encryption: The Digital Credentials service provides application-level encryption for sensitive items (such as keys and digital credentials) stored in the configured database. However, it is recommended that you configure the database with encryption and security settings as recommended by your database vendor.
  10. Deploy behind an application security gateway: It is recommended that you deploy the Digital Credentials container service behind an IBM Application Gateway or a similar technology.
  11. Review applicability of endpoints for your use cases: To comply with various Digital Credentials open standards, the Digital Credentials container hosts several endpoints, including public and unauthenticated endpoints. It is recommended that you review these endpoints to determine which features you intend to use, allow access only from secure and trusted networks, and expose only those public, unauthenticated endpoints required for compliance. All other paths must be blocked by an application security gateway.
  12. Audit logging should be enabled: It is recommended that you consult the YAML specification document to enable audit logging for actions performed through the Digital Credentials container service.