IAM for your product 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

Your product 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 your product 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

Your product supports the following two authentication protocols:

OIDC-based authentication
SAML-based federated authentication

OIDC and SAML are both used for SSO with your product but for different purposes.

Your product is an OIDC identity provider that provides authentication and authorization services to your product console and APIs. It works along 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 your product services. Your product is an identity provider through LDAP.

Your product can be configured as a SAML service provider, which allows federated authentication with an external SAML 2.0 identity provider. When you configure SSO, your product redirects your 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 your product. 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 product cluster, and provide cluster administrator, Cloud Pak 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 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 console login page, you must use the following endpoint:

https://<cluster_address>/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_address>/idprovider/v1/auth/token: This returns an encrypted token and does more cluster-specific operations before making a call to the second endpoint. After the call, it encrypts the token before returning it. The <cluster_address> is defined in Foundational service endpoint.
https://<cluster_address>/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_address>/oidc/endpoint/OP/token and https://<cluster_address>/idauth/oidc/endpoint/OP/token.

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

SAML-Based authentication

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

Note: Your product 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.

Configuring LDAP is not necessary for SAML authentication for IBM Cloud Pak foundational services version 3.11.0 and later.
If you do not have the Platform UI console and first time you log in by using SAML, you can access the dashboard of your product. You can use the cloudctl CLI to manage the roles for the users with SAML authentication. By default, the users are assigned the Viewer role. For more information, see Role-based access control (RBAC) for clusters.

If you have the Platform UI console and first time you log in by using SAML, you cannot access the dashboard of your product. Administrator must search the SAML users in SCIM (System for Cross-domain Identity Management) and add them in Platform UI console.

Lightweight Directory Access Protocol (LDAP) support

Your product can be configured with a single or multiple LDAP servers for the authentication and authorization. Your product 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 your product, you can 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. Your product 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 the 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 and Cloud Pak 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:

Your product and Kubernetes role-based access control (RBAC)

RBAC is enforced in your product 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_address>/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_address>/idmgmt/identity/api/v1/teams/resources API.

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

CRN specification

Your product 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 your product 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 installation time. This set to the cluster_name parameter. The default, when not specified is mycluster. This value does not change for the life of the cluster.

Other attributes are service-specific.

Your product 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. 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 your product IAM roles

crn:v1:icp:private:iam::::role:ClusterAdministrator
crn:v1:icp:private:iam::::role:CloudPakAdministrator
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 your product 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