IAM for IBM Cloud Private platform users

Identity and Access Management (IAM) for platform users includes authentication that includes OIDC and SAML, and authorization that includes role-based access control, users management, and Cloud Resource Naming (CRN).

Authentication

IBM® Cloud Private uses WebSphere Liberty OpenID Connect (OIDC) 1.0 for authentication. It calls the standard OIDC endpoints /authorize and /token to initiate an OAuth dance. OpenID in Liberty can be configured with Lightweight Directory Access Protocol (LDAP), after which an LDAP user can authenticate to IBM Cloud Private by using the same OpenID endpoints. For single sign-on (SSO) based authentication, OIDC is configured with Security Assertion Markup Language (SAML) to interact with your enterprise identity source.

Authentication protocols supported

IBM Cloud Private supports the following two authentication protocols:

OIDC-based authentication
SAML-based federated authentication

OIDC and SAML are both used for SSO with IBM Cloud Private, but for different purposes.

IBM Cloud Private is an OIDC identity provider that provides authentication and authorization services to the IBM Cloud Private management console and APIs. It works in conjunction with one or more LDAP providers to authenticate the user ID and password with the LDAP service, and to provide an access token for subsequent requests to IBM Cloud Private services. IBM Cloud Private is an identity provider through LDAP.

IBM Cloud Private can be configured as a SAML service provider, which allows federated authentication with an external SAML 2.0 identity provider. When you configure SSO, IBM Cloud Private redirects your management console browser to the third-party login page, and OIDC issues you a bearer token.

The OIDC-based authentication service is the default authentication service in IBM Cloud Private. If required, you can configure a SAML server to provide federated authentication.

OIDC-based authentication

You must configure and connect an LDAP directory with your IBM Cloud Private cluster, and provide cluster administrator or administrator access level. For more information, see Configuring LDAP connection. You must set up the LDAP connection before you create a team and add users to the team. Only LDAP users who are assigned to a team can log in to the management console.

For more information about creating a team, see Create teams. For more information about adding users to a team, see Add users to a team.

Authorization endpoint

If you want your application to call the IBM Cloud Private management console login page, you must use the following endpoint:

https://<Cluster Master Host>:<Cluster Master API Port>/idprovider/v1/auth/authorize?client_id=client_id&scope=openid&redirect_uri=redirect_uri&response_type=code&state=state

Token endpoint APIs

There are two token endpoints:

https://<Cluster Master Host>:<Cluster Master API Port>/idprovider/v1/auth/token: This returns an encrypted token and does more IBM Cloud Private-specific operations before making a call to the second endpoint. After the call, it encrypts the token before returning it. The <Cluster Master Host> and <Cluster Master API Port> parameters are defined in Master endpoints.
https://<Cluster Master Host>:<Cluster Master API Port>/idauth/oidc/endpoint/OP/token: This is the OOTB Liberty OIDC token endpoint.

Ingresses are available for both endpoints, however, using the prefix is recommended. Using the prefix is also recommended for the following endpoints: https://<Cluster Master Host>:<Cluster Master API Port>/oidc/endpoint/OP/token and https://<Cluster Master Host>:<Cluster Master API Port>/idauth/oidc/endpoint/OP/token.

Note: The number 1 endpoint is recommended because it returns the encrypted token and works across all the IBM Cloud Private APIs. The decrypted token that is returned by /oidc/endpoint/OP/token won't work with IBM Cloud Private APIs. It can be used by a content service for authentication or by one that requires an OOTB OIDC provider.

SAML-Based authentication

IBM Cloud Private can be configured to use SAML-based authentication from an enterprise SAML server. For more information, see Configuring single sign-on.

Note:

IBM Cloud Private does not support SSO login by using the CLI.
After you configure SAML, you can log in as either the default admin user or as an LDAP user who is added to a team.

Lightweight Directory Access Protocol (LDAP) support

IBM Cloud Private can be configured with a single or multiple LDAP servers for the authentication and authorization. IBM Cloud Private supports the following LDAP types:

IBM Tivoli Directory Server
IBM Lotus Domino
IBM SecureWay Directory Server
Novell eDirectory
Sun Java™ System Directory Server
Netscape Directory Server
Microsoft Active Directory
Custom

Configuring single sign-on

For more information, see Configuring single sign-on.

Configuring LDAPs

With IBM Cloud Private, you are able to authenticate across multiple LDAPs. You can add multiple directory entries to the LDAP config in the server.xml file. Liberty automatically resolves the domain name from the login and authenticates against the targeted LDAP directory. IBM Cloud Private users and user groups are associated with an enterprise directory during the time of the user and user group onboarding via import. When the new LDAP directory entry is created, the domain name also gets added as a new entry. At the time of login, you can specify the domain against which his authentication should be validated.

It is possible to have a mix of directory types, for example AD, Tivoli, and OpenLDAP. Role-based access control (RBAC) is enforced on the LDAP domain. Cluster administrators have access to all LDAP domains whereas team administrators are restricted to only those domain(s) they are authorized to.

For more information, see Configuring LDAP connection.

Troubleshooting LDAP

For more information, see LDAP troubleshooting.

LDAP over SSL

For more information, see Configuring LDAP connection.

Authorization

Check the following topics for more information on authorization for platform users:

IBM Cloud Private and Kubernetes role-based access control (RBAC)

RBAC is enforced in IBM Cloud Private through teams. A team is an entity that groups users and resources. The resources can be Kubernetes type resources (like namespace, pod, and broker) or non-Kubernetes type, such as Helm chart, DB instance, and cloud connection. The assignment of the resources to the team happens through the resource CRNs. The responsible services have to expose the resource CRNs through an API so that they become available on the team's Add Resource dialogue. The Kubernetes resources, such as the namespaces, are exposed through the https://<Cluster Master Host>:<Cluster Master API Port>/idmgmt/identity/api/v1/teams/resources?resourceType=namespace API. It's possible to fetch the resources that are attached to a specific user through their teams by using the https://<Cluster Master Host>:<Cluster Master API Port>/idmgmt/identity/api/v1/teams/resources API.

For more information, see role-based access control and teams.

CRN specification

IBM Cloud Private follows the CRN convention: crn:version:cname:ctype:service-name:region:scope:service-instance:resource-type:resource-instance.

The following CRN attribute definitions are specific to IBM Cloud Private platform services:

cname: icp
ctype: private
service-name: An IAM registered service, for example: k8, security, iam.
region: The cluster-id of the cluster set during install time. This set to the cluster_name parameter from the config.yaml configuration file. The default, when not specified is mycluster. This value does not change for the life of the cluster.

Other attributes are service-specific.

IBM Cloud Private defines the following constructs for applications based on:

Kubernetes platform
Workloads
Cloud Foundry Enterprise Environment platform

CRNs for Kubernetes resources

The region / cluster-id is set to the cluster_name parameter from the config.yaml configuration file. The default, when not specified is `mycluster'.

crn:v1:icp:private:k8:mycluster::::
crn:v1:icp:private:k8:mycluster:n/namespace-id:::
crn:v1:icp:private:k8:cluster-id:n/namespace-id::deployment:deployment-name
crn:v1:icp:private:k8:cluster-id:n/namespace-id::pod:pod-name
crn:v1:icp:private:k8:cluster-id:n/namespace-id::service:service-name
crn:v1:icp:private:k8:cluster-id:::persistent-volume:volume-name

CRNs for service catalog resources

crn:v1:icp:private:k8:mycluster:::clusterservicebroker:csb123
crn:v1:icp:private:k8:mycluster:::clusterserviceclass:csc123 (to be changed to: crn:v1:icp:private:k8:mycluster:sc/csc123::::)
crn:v1:icp:private:k8:mycluster:sc/csc123::clusterserviceplan:csp123
crn:v1:icp:private:k8:cluster-id:n/namespace-id::serviceinstance:instanceid
crn:v1:icp:private:k8:cluster-id:n/namespace-id::servicebinding:bindingid

crn:v1:icp:private:security:mycluster::User:userId
crn:v1:icp:private:security:mycluster::Directory:directoryId
crn:v1:icp:private:security:mycluster::UserGroup:groupId
crn:v1:icp:private:security:mycluster::Team:teamId

CRNs for IBM Cloud Private IAM roles

crn:v1:icp:private:iam::::role:ClusterAdministrator
crn:v1:icp:private:iam::::role:Administrator
crn:v1:icp:private:iam::::role:Operator
crn:v1:icp:private:iam::::role:Editor
crn:v1:icp:private:iam::::role:Viewer

CRNs for logging and monitoring resources

crn:v1:icp:private:logging:mycluster::xxxx:yyyy
crn:v1:icp:private:monitoring:mycluster::xxxx:yyyy

CRNs for Helm resources

crn:v1:icp:private:helm-catalog:cluster-id:c/chart-name:::
crn:v1:icp:private:helm-catalog:cluster-id:c/chart-name::DBaaS
crn:v1:icp:private:helm-catalog:cluster-id:r/repo-name::repoid
crn:v1:icp:private:helm-catalog:cluster-id:r/repo-name::repo-name
crn:v1:icp:private:k8:cluster-id:n/namespace-id::release:release-name

Event streams

crn:v1:icp:private:eventstreams:cluster-id:n/namespace-id:::
crn:v1:icp:private:eventstreams:cluster-id:n/namespace-id:r/eventstream-instanceid::
crn:v1:icp:private:eventstreams:cluster-id:n/namespace-id:r/eventstream-instanceid:resourceType:
crn:v1:icp:private:eventstreams:cluster-id:n/namespace-id:r/eventstream-instanceid:resourceType:resourceId

CRNs for user defined workloads

crn:v1:icp:private:user-defined:cluster-id:u/mongoaaS-id:MongoDB:Mongodb-id
crn:v1:icp:private:user-defined:cluster-id:u/mySQLaaS-id:MySQLDB:Mysqldb-id

CRNs for Key Management Service

crn:v1:icp:private:kms:cluster-id:n/kube-system:::
crn:v1:icp:private:kms:cluster-id:n/kube-system::key:key-id
crn:v1:icp:private:kms:cluster-id:n/kube-system:instance-id::
crn:v1:icp:private:kms:cluster-id:n/kube-system:instance-id:key:
crn:v1:icp:private:kms:cluster-id:n/kube-system:instance-id:key:key-id

CRN examples for workloads hosted on the IBM Cloud Private platform

- crn:version:cname:ctype:service-name:region:scope:service-instance:resource-type:resource-instance
- scope - repo, pod, user-defined

An Operator configures a repository behind monocular and discovers Helm charts, some of which are brokers, such as DBaaS: crn:v1:icp:private:helm-catalog:cluster-id:r/repo-name:helm-charts:DBaaS
There are two scenarios with Helm:
1. Deploying a typical middleware chart (not X-aaS model), which then creates a release. A release is an artifact running on the platform: crn:v1:icp:private:k8:cluster-id:n/namespace-id::release:release-name
2. Deploying a chart can create services. An operator deploys a DBaaS chart, which then creates MongoaaS and MySQLaaS in the service catalog:
```
crn:v1:icp:private:user-defined:cluster-id::u/mongo-aas::
crn:v1:icp:private:user-defined:cluster-id::u/mysql-aas::
```

When a Developer logs in, they sees those services:

rn:v1:icp:private:helm-catalog::r/repo-name:catalog-name:mongoaaS:mongoaaS-id
crn:v1:icp:private:helm-catalog::r/repo-name:catalog-name:mySQLaaS:mySQLaaS-id

When a Developer can deploy a MongoDB from the service and use it:

crn:v1:icp:private:user-defined:cluster-id:u/mongoaaS-id:MongoDB:Mongodb-id
crn:v1:icp:private:user-defined:cluster-id:u/mySQLaaS-id:MySQLDB:Mysqldb-id

CRN for application that is hosted on the Cloud Foundry Enterprise Environment platform

crn:version:cname:ctype:service-name:region:scope:service-instance:resource-type:resource-instance
scope - account, org, space