Authentication

The runtime APIs exposed by all blockchain nodes and services in Kaleido are secured with strongly generated credentials.

We call these Application Credentials, and they should be generated and managed for each application that accesses your runtime infrastructure.

Per Member, Per Environment

Application credentials (similar to nodes and services) are directly bound to one of your memberships within the consortium, and they exist and function solely within the environment where they were created. Think of them as security resource objects that are explicitly scoped to a specific environment within your business network.

• Membership Org1s app credential will NOT work against membership Org2s resources
• The same app credential WILL work against Node 1, Node 2 and HD Wallet 1 in the same environment, as long as they are owned by the same Org1 membership
• An app credential created by Org1 for environment Env1 will NOT work for a resource in Env2

Generating App Credentials

Application credentials can be created and managed within the Manage Resources section of the Kaleido console.

• Navigate to an environment within your business network
• Expand the Security section
• Select the App Creds tab

• Click the New App Cred button at the bottom of the screen
• Choose the membership to bind the application credential to
• Supply an arbitrary name for the key pair
• Click Create to generate the key pair or click Cancel to return to the Security landing page

Once generated, you will be redirected to the App Cred Details page. On this page you will be shown:

• ID - username for the key pair
• Password - secret for the key pair
• Basic auth - key pair string represented as username:password
• Auth header - base 64 encoded authorization header
• Owner - membership bound to the cred
• App Cred Settings - panel to change name or delete key pair

IMPORTANT: Your app cred password will ONLY be shown a single time after creation. Kaleido does not store these plaintext security tokens and it is YOUR responsibility to secure the password and/or cycle the key pairs. Make sure to copy down the username/password or authorization header.

Supplying Application Credentials in API Calls

Application credentials are supplied base64 encoded using a standard called "HTTP Basic Auth".

This standard has the wide support in client libraries and web browsers.

Postman example

The following shows how you can specify the application credentials in Postman on a simple REST API call, in this case to a HD Wallet.

Raw HTTP API examples

Different libraries require you to specify the authentication in different ways. In all cases the end result is taking the strong generated username/password combination, base64 encoding them and then passing them to the API over an Authorization: Basic XYZ header.

Let's look at three different ways you can pass the same information to CURL. These represent the three most common options that client API libraries, such as Swagger/OpenAPI clients, or bespoke client libraries, allow.

1. Using a username/password special option

curl -v --user e0f0pbkxfu:iFFjRbgFDjpqR99fHMudOPCSgCFFh6QociYCLem-VPA https://e0ftkb2ckc-e0w1f5ani1-hdwallet.de0-aws.kaleido.io/api/v1/wallets
...
> Authorization: Basic ZTBmMHBia3hmdTppRkZqUmJnRkRqcHFSOTlmSE11ZE9QQ1NnQ0ZGaDZRb2NpWUNMZW0tVlBB

2. Embedding the username/password into the URL

curl -v https://e0f0pbkxfu:iFFjRbgFDjpqR99fHMudOPCSgCFFh6QociYCLem-VPA@e0ftkb2ckc-e0w1f5ani1-hdwallet.de0-aws.kaleido.io/api/v1/wallets
...
> Authorization: Basic ZTBmMHBia3hmdTppRkZqUmJnRkRqcHFSOTlmSE11ZE9QQ1NnQ0ZGaDZRb2NpWUNMZW0tVlBB

3. Supplying a raw pre-encoded base64 header

B64AUTH=$(echo -n 'e0f0pbkxfu:iFFjRbgFDjpqR99fHMudOPCSgCFFh6QociYCLem-VPA' | base64)
curl -v -H "Authorization: Basic $B64AUTH" https://@e0ftkb2ckc-e0w1f5ani1-hdwallet.de0-aws.kaleido.io/api/v1/wallets
...
> Authorization: Basic ZTBmMHBia3hmdTppRkZqUmJnRkRqcHFSOTlmSE11ZE9QQ1NnQ0ZGaDZRb2NpWUNMZW0tVlBB