Binding service credentials to actions and packages is a much better approach to handling authentication credentials in IBM Cloud Functions, than manually updating (and maintaining) default parameters 🔐.
IBM Cloud Functions supports binding credentials from IAM-based and Cloud Foundry provisioned services.
Documentation and blog posts demonstrating service binding focuses on traditional platform services, created using the Cloud Foundry service broker. As IBM Cloud integrates IAM across the platform, more platform services will migrate to use the IAM service for managing authentication credentials.
How do we bind credentials for IAM-based services to IBM Cloud Functions? 🤔
Binding IAM-based services to IBM Cloud Functions works the same as traditional platform services, but has some differences in how to retrieve details needed for the service bind command.
Let’s look at how this works…
Binding IAM Credentials
Requirements
Before binding an IAM-based service to IBM Cloud Functions, the following conditions must be met.
You will need the following information to bind a service credentials.
- Service name.
- (Optional) Instance name.
- (Optional) Credentials identifier.
Using the CLI
Use the ibmcloud wsk service bind command to bind service credentials to actions or packages.
bx wsk service bind <SERVICE_NAME> <ACTION|PACKAGE> --instance <INSTANCE> --keyname <KEY>
This command supports the following (optional) flags: --instance and --keyname.
If the instance and/or key names are not specified, the CLI uses the first instance and credentials returned from the system for the service identifier.
Accessing from actions
Credentials are stored as default parameters on the action or package.
The command uses a special parameter name (__bx_creds) to store all credentials. Individual service credentials are indexed using the service name.
{
"__bx_creds":{
"service-name":{
"apikey":"<API_KEY>",
...
}
}
}
Default parameters are automatically merged into the request parameters during invocations.
Common Questions
How can I tell whether a service instance uses IAM-based authentication?
Running the ibmcloud resource service-instances command will return the IAM-based service instances provisioned.
Cloud Foundry provisioned services are available using a different command: ibmcloud service list.
Both service types can be bound using the CLI but the commands to retrieve the necessary details are different.
How can I find the service name for an IAM-based service instance?
Run the ibmcloud resource service-instance <INSTANCE_NAME> command.
Service names are shown as the Service Name: field value.
How can I list available service credentials for an IAM-based service instance?
Use the ibmcloud resource service-keys --instance-name <NAME> command.
Replace the <NAME> value with the service instance returned from the ibmcloud service list command.
How can I manually retrieve IAM-based credentials for an instance?
Use the ibmcloud resource service-key <CREDENTIALS_NAME> command.
Replace the <CREDENTIALS_NAME> value with credential names returned from the ibmcloud service service-keys command.
How can I create new service credentials?
Credentials can be created through the service management page on IBM Cloud.
You can also use the CLI to create credentials using the ibmcloud resource service-key-create command. This command needs a name for the credentials, IAM role and service instance identifier.
Example - Cloud Object Storage
Having explained how to bind IAM-based services to IBM Cloud Functions, let’s look at an example….
Cloud Object Storage is the service used to manage files for serverless applications on IBM Cloud. This service supports the newer IAM-based authentication service.
Let’s look at how to bind authentication credentials for an instance of this service to an action.
Using the CLI, we can check an instance of this service is available…
$ ibmcloud resource service-instances
Retrieving service instances in resource group default..
OK
Name Location State Type Tags
my-cos-storage global active service_instance
In this example, we have a single instance of IBM Cloud Object Storage provisioned as my-cos-storage.
Retrieving instance details will show us the service name to use in the service binding command.
$ ibmcloud resource service-instance my-cos-storage
Retrieving service instance my-cos-storage in resource group default..
OK
Name: my-cos-storage
ID: crn:v1:bluemix:public:cloud-object-storage:global:<GUID>:
GUID: <GUID>
Location: global
Service Name: cloud-object-storage
Service Plan Name: lite
Resource Group Name: default
State: active
Type: service_instance
Tags:
The IBM Cloud Object Storage service name is cloud-object-storage.
Before we can bind service credentials, we need to verify service credentials are available for this instance.
$ ibmcloud resource service-keys --instance-name my-cos-storage
Retrieving service keys in resource group default...
OK
Name State Created At
serverless-credentials active Tue Jun 5 09:11:06 UTC 2018
This instance has a single service key available, named serverless-credentials.
Retrieving the service key details shows us the API secret for this credential.
$ ibmcloud resource service-key serverless-credentials
Retrieving service key serverless-credentials in resource group default...
OK
Name: serverless-credentials
ID: <ID>
Created At: Tue Jun 5 09:11:06 UTC 2018
State: active
Credentials:
...
apikey: <SECRET_API_KEY_VALUE>
apikey denotes the secret API key used to authenticate calls to the service API.
Having retrieved the service name, instance identifier and available credentials, we can use these values to bind credentials to an action.
$ bx wsk service bind cloud-object-storage params --instance my-cos-storage --keyname serverless-credentials
Credentials 'serverless-credentials' from 'cloud-object-storage' service instance 'my-cos-storage' bound to 'params'.
Retrieving action details shows default parameters bound to an action. These will now include the API key for the Cloud Object Storage service.
$ bx wsk action get params
ok: got action params
{
...
"parameters": [{
"key": "__bx_creds",
"value": {
"cloud-object-storage": {
"apikey": "<API_KEY_SECRET>",
...
}
}
}]
}
Under the __bx_creds default parameter, there is a cloud-object-storage property with the API key amongst other service credential values.