Overview
As a part of Bring Your Own Wallet (BYOW) efforts within the Catena-X to decentralize the wallet ecosystem in the network, it is necessary for some of the Tractus-X components (i.e., Portal Backend, ssi-credential-issuer) to foster this movement.
Currently the ssi-credential-issuer requires clientID and secret for the individual wallet tenants within the SAP DIV Wallet, which is offered as a Core Service B from the operating company. This approach has several issues:
- There are third-party components (i.e. ssi-credential-issuer) that must know the clientID and secret that is meant for the owner of the wallet; the best practice is to ensure that the clientID and secrets are not shared between organizations, let alone services.
- It is a custom solution and there are no specifications or protocols around it. Furthermore, it was thought as a temporary solution.
The solution is to implement a secure credential exchange protocol to make sure that components and services running in different domains / organizations can issue / store credential in a secure manner.
To address this issue, the Decentralized Claims Protocol (DCP) issuance flow is proposed to be the Catena-X Standard for issuing Verifiable Credentials (VC).
The ssi-credential-issuer is to be adapted with the capabilities of the DCP Issuance Flow. There are two issuance flows - credential request flow, initiated by the holder wallet and the credential offer flow, initiated by the issuer wallet. In the scope of 25.09 release the credential request flow will be implemented. The credential offer flow may be implemented, should there be enough time to implement and run the integration tests. Otherwise, the credential offer flow will be a part of the 25.12 release.
Note: Issuer Service is an abstract component which consists of the ssi-credential-issuer and the issuer wallet
Onboarding Process
The decentralization of the wallet and different offerings, such as self-hosted wallets (aka Bring your own Wallet, BYOW), it is required to implement different flows for the onboarding process. It will be necessary to make the necessary changes in the portal backend and frontend components. During the onboarding process the onboarding company will be given an option to use a white-label wallet as a service, offered by the Core Service Provider, or provide the DID of the wallet which they host in their infrastructure.
For 25.09 release, there are no wallet as an enablement service or wallet migration services (from white-label to BYOW) planned. These features may be a part of future releases.
Explain the topic in 2 sentences
Current issuance flow within Catena-X has flaws due to security reasons mentioned in Overview.
It is to be replaced by the DCP issuance flow
Replacement is to be done by changing how the credentials are written in the holder wallets (shift from shared clientID / secret to DCP issuance flow)
Onboarding Processes must be adapted for portal backend and frontend
What's the benefit?
Security
- Enabling the decentralization of the wallets within the Catena-X network
- Avoiding clientID / secret sharing between organizations (Operating Company and Network Participant)
What are the Risks/Dependencies ?
Interface Partners are the Portal backend and the Wallet (SAP DIV Wallet, Wallet-stub)
Potential API changes that comes from on-boarding, issuance, re-issuance, key rotation, off-boarding features to portal backend
Detailed explanation
Current implementation
The onboarding / issuance flow:
- Wallet creation using the wallet-integration-layer (non TX component)
- The wallet information, including the clientID and secret to access the wallet is communicated with the Portal backend
- When a credential is to be signed, issued, and stored, the ssi-credential-issuer requires the same clientID and secret from the Portal backend to store the VC in the corresponding wallet
Proposed improvements
DCP issuance flow:
- The wallet owner creates an ID token with an access token in it to write VC into the wallet
- The ID token is sent to the issuer service
- The issuer service authenticates the ID token, extracts the access token to use it to store VCs in the wallet
Wallet Options:
Offering onboarding company two options:
- Bring your own Wallet
- Use White-label wallet solution from Core Service Provider
Feature Team
Contributor
Committer
User Stories
see sub-issues
To be refined
Acceptance Criteria
Test Cases
Test Case 1: Company Registration with Own Wallet and Valid DID
Preconditions:
The client has received an invitation to register.
The client already possesses a valid decentralized identifier (DID) and their own identity wallet.
Test Steps:
Invite a company to register.
Client initiates the company registration process.
Client signs the companyRoleAgreementConsents form.
Client uploads the required documents.
System prompts: “Do you have your own wallet?”
Client selects "Yes".
Client enters a valid DID.
System validates the provided DID.
Registration submit.
Admin manually verifies the registration.
System checks for the Business Partner Number (BPN):
If BPN does not exist, the system creates a new BPN.
System skips wallet creation, as the client has their own wallet.
Verify Wallet process successful with own wallet
Expected Result:
The provided DID is validated successfully.
The system does not create a new wallet.
Wallet process successful with own wallet
Test Case 2: Company Registration – System Creates Wallet and DID
Precondition:
The client does not have an identity wallet or DID.
Test Steps:
Invite a company to register.
Client initiates the company registration process.
Client signs the companyRoleAgreementConsents form.
Client uploads the required documents.
System prompts: “Do you have your own wallet?”
Client selects "No".
Client skips DID input.
Client submit Registration form.
Admin manually verifies the registration.
System checks for the Business Partner Number (BPN):
If BPN does not exist, system creates a new BPN.
System creates a new identity wallet and DID for the company.
Verify Wallet created successfully.
Expected Result:
Registration process completes successfully.
The system automatically creates a new wallet and DID for the company.
Test Case 3: BYOW – Invalid DID Validation Check
Precondition:
The client claims to have their own wallet and attempts to register using a manually entered DID.
Test Steps:
Invite a company to register.
Client initiates the company registration process.
Client signs the companyRoleAgreementConsents form.
Client uploads the required documents.
System prompts: “Do you have your own wallet?”
Client selects "Yes".
Client enters an invalid DID (e.g., malformed format, non-resolvable, or incorrect DID method).
Verify system gives "BAD Request"
Expected Result:
The system responds with:
HTTP Status Code: 400 Bad Request
Error Message: "Invalid DID"
Test Case 4: BYOW – Prevent Technical User Creation for BYOW Wallet
Precondition:
The company (byow-test-company) is registered using the Bring Your Own Wallet (BYOW) flow.
A valid user is logged in under this company.
Test Steps:
Log in as a valid user under the byow-test-company.
Navigate to the Technical User Management section.
Select the option to create a new technical user.
Attempt to create a technical user with the name: "dim-WalletTestUser".
verify System gives error "Not allowed to create technical user for BYOW"
Expected Result:
System returns:
HTTP Status Code: 500 Internal Server Error
Error Message: "Not allowed to create technical user"
Test Case 5: Issue Membership Credential for BYOW
Precondition:
The company (byow-test-company) is registered using the Bring Your Own Wallet (BYOW) flow.
A valid user is logged in under this company.
Test Steps:
Obtain a valid access token from DCP (Digital Credential Provider).
Make a request to issue a Membership Credential for the company.
Verify that the credential is created successfully and a response ID is returned.
Expected Result:
System returns:
HTTP Status Code: 201 Created
Response Message: Membership credential issued successfully.
Response Body: Contains a credential request ID.
Test Case 6: Issue BPN Credential for BYOW
Precondition:
The company (byow-test-company) is registered using the Bring Your Own Wallet (BYOW) flow.
A valid user is logged in under this company.
Test Steps:
Obtain a valid access token from DCP.
Make a request to issue a BPN Credential for the company.
Verify that the credential is created successfully and a response ID is returned.
Expected Result:
System returns:
HTTP Status Code: 201 Created
Response Message: BPN credential issued successfully.
Response Body: Contains a credential request ID.
Architectural Relevance
The following items are ensured (answer: yes) after this issue is implemented.
In the context of the standards 126 and 127, typically only one is applicable, depending on the specific use case. Please cross out one of the two standards that does not apply.
Justification: (Fill this out, if at least one of the checkboxes above cannot be ticked. Contact the Architecture Management Committee to get an approval for the justification)
Additional information
To be created sub-issues
Overview
As a part of Bring Your Own Wallet (BYOW) efforts within the Catena-X to decentralize the wallet ecosystem in the network, it is necessary for some of the Tractus-X components (i.e., Portal Backend, ssi-credential-issuer) to foster this movement.
Currently the ssi-credential-issuer requires clientID and secret for the individual wallet tenants within the SAP DIV Wallet, which is offered as a Core Service B from the operating company. This approach has several issues:
The solution is to implement a secure credential exchange protocol to make sure that components and services running in different domains / organizations can issue / store credential in a secure manner.
To address this issue, the Decentralized Claims Protocol (DCP) issuance flow is proposed to be the Catena-X Standard for issuing Verifiable Credentials (VC).
The ssi-credential-issuer is to be adapted with the capabilities of the DCP Issuance Flow. There are two issuance flows - credential request flow, initiated by the holder wallet and the credential offer flow, initiated by the issuer wallet. In the scope of 25.09 release the credential request flow will be implemented. The credential offer flow may be implemented, should there be enough time to implement and run the integration tests. Otherwise, the credential offer flow will be a part of the 25.12 release.
Note: Issuer Service is an abstract component which consists of the ssi-credential-issuer and the issuer wallet
Onboarding Process
The decentralization of the wallet and different offerings, such as self-hosted wallets (aka Bring your own Wallet, BYOW), it is required to implement different flows for the onboarding process. It will be necessary to make the necessary changes in the portal backend and frontend components. During the onboarding process the onboarding company will be given an option to use a white-label wallet as a service, offered by the Core Service Provider, or provide the DID of the wallet which they host in their infrastructure.
For 25.09 release, there are no wallet as an enablement service or wallet migration services (from white-label to BYOW) planned. These features may be a part of future releases.
Explain the topic in 2 sentences
Current issuance flow within Catena-X has flaws due to security reasons mentioned in Overview.
It is to be replaced by the DCP issuance flow
Replacement is to be done by changing how the credentials are written in the holder wallets (shift from shared clientID / secret to DCP issuance flow)
Onboarding Processes must be adapted for portal backend and frontend
What's the benefit?
Security
What are the Risks/Dependencies ?
Interface Partners are the Portal backend and the Wallet (SAP DIV Wallet, Wallet-stub)
Potential API changes that comes from on-boarding, issuance, re-issuance, key rotation, off-boarding features to portal backend
Detailed explanation
Current implementation
The onboarding / issuance flow:
Proposed improvements
DCP issuance flow:
Wallet Options:
Offering onboarding company two options:
Feature Team
Contributor
Committer
User Stories
see sub-issues
To be refined
Acceptance Criteria
Test Cases
Test Case 1: Company Registration with Own Wallet and Valid DID
Preconditions:
The client has received an invitation to register.
The client already possesses a valid decentralized identifier (DID) and their own identity wallet.
Test Steps:
Invite a company to register.
Client initiates the company registration process.
Client signs the companyRoleAgreementConsents form.
Client uploads the required documents.
System prompts: “Do you have your own wallet?”
Client selects "Yes".
Client enters a valid DID.
System validates the provided DID.
Registration submit.
Admin manually verifies the registration.
System checks for the Business Partner Number (BPN):
If BPN does not exist, the system creates a new BPN.
System skips wallet creation, as the client has their own wallet.
Verify Wallet process successful with own wallet
Expected Result:
The provided DID is validated successfully.
The system does not create a new wallet.
Wallet process successful with own wallet
Test Case 2: Company Registration – System Creates Wallet and DID
Precondition:
The client does not have an identity wallet or DID.
Test Steps:
Invite a company to register.
Client initiates the company registration process.
Client signs the companyRoleAgreementConsents form.
Client uploads the required documents.
System prompts: “Do you have your own wallet?”
Client selects "No".
Client skips DID input.
Client submit Registration form.
Admin manually verifies the registration.
System checks for the Business Partner Number (BPN):
If BPN does not exist, system creates a new BPN.
System creates a new identity wallet and DID for the company.
Verify Wallet created successfully.
Expected Result:
Registration process completes successfully.
The system automatically creates a new wallet and DID for the company.
Test Case 3: BYOW – Invalid DID Validation Check
Precondition:
The client claims to have their own wallet and attempts to register using a manually entered DID.
Test Steps:
Invite a company to register.
Client initiates the company registration process.
Client signs the companyRoleAgreementConsents form.
Client uploads the required documents.
System prompts: “Do you have your own wallet?”
Client selects "Yes".
Client enters an invalid DID (e.g., malformed format, non-resolvable, or incorrect DID method).
Verify system gives "BAD Request"
Expected Result:
The system responds with:
HTTP Status Code: 400 Bad Request
Error Message: "Invalid DID"
Test Case 4: BYOW – Prevent Technical User Creation for BYOW Wallet
Precondition:
The company (byow-test-company) is registered using the Bring Your Own Wallet (BYOW) flow.
A valid user is logged in under this company.
Test Steps:
Log in as a valid user under the byow-test-company.
Navigate to the Technical User Management section.
Select the option to create a new technical user.
Attempt to create a technical user with the name: "dim-WalletTestUser".
verify System gives error "Not allowed to create technical user for BYOW"
Expected Result:
System returns:
HTTP Status Code: 500 Internal Server Error
Error Message: "Not allowed to create technical user"
Test Case 5: Issue Membership Credential for BYOW
Precondition:
The company (byow-test-company) is registered using the Bring Your Own Wallet (BYOW) flow.
A valid user is logged in under this company.
Test Steps:
Obtain a valid access token from DCP (Digital Credential Provider).
Make a request to issue a Membership Credential for the company.
Verify that the credential is created successfully and a response ID is returned.
Expected Result:
System returns:
HTTP Status Code: 201 Created
Response Message: Membership credential issued successfully.
Response Body: Contains a credential request ID.
Test Case 6: Issue BPN Credential for BYOW
Precondition:
The company (byow-test-company) is registered using the Bring Your Own Wallet (BYOW) flow.
A valid user is logged in under this company.
Test Steps:
Obtain a valid access token from DCP.
Make a request to issue a BPN Credential for the company.
Verify that the credential is created successfully and a response ID is returned.
Expected Result:
System returns:
HTTP Status Code: 201 Created
Response Message: BPN credential issued successfully.
Response Body: Contains a credential request ID.
Architectural Relevance
The following items are ensured (answer: yes) after this issue is implemented.
In the context of the standards 126 and 127, typically only one is applicable, depending on the specific use case. Please cross out one of the two standards that does not apply.
Justification: (Fill this out, if at least one of the checkboxes above cannot be ticked. Contact the Architecture Management Committee to get an approval for the justification)
Additional information
To be created sub-issues