IAM for service to service communication

The IBM Cloud Identity and Access Management (IAM) token service enables the ability to create service IDs and application programming interface (API) keys for service IDs. A service ID is similar to either a functional ID or an application ID and is used to authenticate services, and not to represent a user.

You can create service IDs and bind them to scope namespace such as an IBM Cloud account, a Cloud Foundry Enterprise Environment organization, or a Cloud Foundry Enterprise Environment space. However, for adopting IBM Cloud IAM, it is best to bind Service IDs to an IBM Cloud account. This binding is done to give the service ID a container to live in. This container also defines who can update and delete the service ID, and who can create, update, read, and delete API keys that are associated to that Service ID. It is important to note that a Service ID is not related to a user.

Consider an example where a content service, such as WebSphere Application Server (WAS), communicates with the metering service by using a service ID.

Metering service creates a service ID and an API key from a user with required privileges.
Metering service creates policies for the Service ID.
User shares or publishes the API key to WAS.
WAS calls the metering service APIs by using the API key.
Metering service gets an access token for the API Key.
Metering service introspects the token to get the service ID from IAM.
Metering service validates the service ID.
Metering service completes the API operation and returns a response to WAS.

Complete the following steps to enable service to service communication:

Create service ID and API key

There are four ways to create a service ID and an API key for any service.

Automated service ID and API Key creation by using Kubernetes secret annotations.
Create service ID and API key by using cloudctl. For more information, see Managing your cluster with cloudctl.
Create service ID and API key by using the console.
Create service ID and API key by using the APIs.

Automated service ID and API Key creation by using Kubernetes secret annotations

To generate a service ID and an API key for any service, you must create a Kubernetes secret with the following three annotations:

ibm.com/iam-service.name, which is a unique name of the service.
ibm.com/iam-service.id, which is a name of the key that is injected into this secret along with the service ID.
ibm.com/iam-service.api-key, which is the name of the key that is injected into this secret along with the API key.

To ensure that the namespace is authorized by the namespace scope operator, see Authorizing foundational services to perform operations on workloads in a namespace.

Following is an example template of a secret:

apiVersion: v1
kind: Secret
type: Opaque
metadata:
  name: myservice-secret
  namespace: mynamespace
  annotations:
    ibm.com/iam-service.name: "myservice-service"
    ibm.com/iam-service.id: "myservice-service-id"
    ibm.com/iam-service.api-key: "myservice-api-key"
data:
  ...

The myservice-secret is created with the annotations ibm.com/myservice-service.id, ibm.com/myservice-service.api-key, and ibm.com/myservice-service.name. The secret-watcher service updates the secret resource that contains these annotations, and injects the service ID and API key details into the data section of the secret.

Example output of the secret:

apiVersion: v1
kind: Secret
type: Opaque
metadata:
  name: myservice-secret
  namespace: mynamespace
  annotations:
    ibm.com/iam-service.id: "myservice-service-id"
    ibm.com/iam-service.api-key: "myservice-api-key"
    ibm.com/iam-service.name: "myservice-service"
data:
  myservice-service-id: cb0719e2-3480-11e9-b210-d663bd873d93
  myservice-api-key: 20346eed-8e01-47e8-b4f8-1efe6fec2408
  ...

Any service can now read the service ID and API Key from the secret.

Create service ID and API key by using cloudctl

Follow these steps to create the service ID and API key:

Create a service ID.

See cloudctl iam service-id-create.
Create an API key.

See cloudctl iam service-api-key-create.

Create service ID and API key by using the console

See Creating a service ID by using IBM Cloud Pak for Multicloud Management console.

Create service ID and API key by using the APIs

Follow these steps to create the service ID and API key:

Create service ID.

See Create a service ID.
Create an API key.

See Create an API key.

Create policies for service ID

There are three ways to create policies for service ID.

Create policies for service ID by using cloudctl
Create policies for service ID by using the console
Create policies for service ID by using the APIs

Get access token for the API Key

Use the following API to get a token for a service ID and API key:

Generate an OpenID Connect (OIDC) token.

Introspect the access token to get the service ID from IAM

Use the following API to introspect the access token:

Introspect an OIDC token

Service ID and teams

An application or a service uses a service ID to call the APIs of several micro services. The service ID can be granted access only to the set of services that are required by the application or service. Each application can have its own service ID and API key combination, which allows for easy rotation of one key without impacting other applications or users.

Cluster administrators can assign a service ID to a team and manage the service ID. Users with administrator role can create and delete API Keys, and can access policies that are assigned to a service ID. The service ID must be bound to at least one namespace. If you do not assign a namespace when you create a service ID, the service ID creation fails.

For information about how to assign a service ID to a team, see Creating a service ID by using IBM Cloud Pak for Multicloud Management console.