Team management APIs

APIs to manage teams.

Base path: https://<cluster_address>/idmgmt/identity/api/v1/teams

Where, <cluster_address> is defined in Foundational service endpoint

Create a team

API version

1.0.0

API URI components

Scheme

HTTPS

Host IP

Cluster Master Host

Port number

Cluster Master API Port

Path

idmgmt/identity/api/v1/teams

Command

POST

Command output format

application/json

The sample curl command resembles the following code:

 curl -k -X POST --header 'Content-Type: application/json' --header "Authorization: bearer $ACCESS_TOKEN" -d '{"teamId":"test-team","name":"test-team","users":[],"usergroups":[],"serviceids":[]}' https://<cluster_address>/idmgmt/identity/api/v1/teams

The output resembles the following code:

{
    "teamId": "test-team",
    "name": "test-team",
    "users": [],
    "usergroups": [],
    "serviceids": [],
    "accountId": "id-mycluster-account",
    "type": "Custom",
    "directoryList": []
}

Assign users and user groups to a team by providing the team payload

Provide the entire team payload in the curl command to add users and user groups to a team.

Note: You must import users and user groups from your LDAP server before you add them to a team. For the APIs to import users and user groups, see Import users from your LDAP directory and Import user groups from your LDAP directory.

Note: You cannot add an AccountAdministrator to a team by using the team management APIs. You must use the multitenancy account management API to add an AccountAdministrator to a team. See Add users to an account.

API version

1.0.0

API URI components

Scheme

HTTPS

Host IP

Cluster Master Host

Port number

Cluster Master API Port

Path

idmgmt/identity/api/v1/teams/{team-ID}

Command

PUT

Command output format

application/json

The sample curl command resembles the following code:

curl -k -X PUT --header "Authorization: Bearer $ACCESS_TOKEN" --header 'Content-Type: application/json' --header 'Accept: application/json' -d '{"teamId":"test-team","name":"Test Team","users":[{"userId":"testuser","userBaseDN":"uid=testuser,ou=people,dc=ibm,dc=com","roles":[{"id":"crn:v1:icp:private:iam::::role:Operator"}]}],"usergroups":[{"name":"security","userGroupDN":"cn=security,cn=platform,ou=cloud,ou=isl,ou=groups,dc=ibm,dc=com","roles":[{"id":"crn:v1:icp:private:iam::::role:Operator"}]}]}' "https://<cluster_address>/idmgmt/identity/api/v1/teams/test-team"

The response resembles the following code:

{
    "teamId": "test-team",
    "name": "Test Team",
    "users": [
        {
            "userId": "testuser",
            "userBaseDN": "uid=testuser,ou=people,dc=ibm,dc=com",
            "roles": [
                {
                    "id": "crn:v1:icp:private:iam::::role:Operator"
                }
            ]
        }
    ],
    "usergroups": [
        {
            "name": "security",
            "userGroupDN": "cn=security,cn=platform,ou=cloud,ou=isl,ou=groups,dc=ibm,dc=com",
            "roles": [
                {
                    "id": "crn:v1:icp:private:iam::::role:Operator"
                }
            ]
        }
    ],
    "serviceids": [],
    "accountId": "id-mycluster-account",
    "type": "Custom",
    "directoryList": [
        "d77de310-ca65-11e9-9c54-5bd9ecf04530"
    ]
}

Assign users to a team by providing the user information

Provide only the user-related data to add users to a team.

Note: You must import the user from your LDAP server before you add the user to a team. For the API to import users, see Import users from your LDAP directory.

Note: You cannot add an AccountAdministrator to a team by using the team management APIs. You must use the multitenancy account management API to add an AccountAdministrator to a team. See Add users to an account.

API version

1.0.0

API URI components

Scheme

HTTPS

Host IP

Cluster Master Host

Port number

Cluster Master API Port

Path

idmgmt/identity/api/v1/teams/{team-ID}

Command

POST

Command output format

application/json

The sample curl command resembles the following code:

Note: To get the baseDN, use the API to Search for users in your LDAP directory.

curl --location --request POST 'https://<cluster_address>/idmgmt/identity/api/v1/teams/test-team/users' \
--header 'Authorization: Bearer $ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
    "users": [
        {
            "baseDN": "uid=testuser@in.ibm.com,ou=People,dc=ibm,dc=com",
            "directoryId": "acae8550-fc3b-11ea-99f3-018edd55e9a4",
            "roles": [
                {
                    "id": "crn:v1:icp:private:iam::::role:Viewer"
                }
            ]
        }
    ]
}

Following is a sample response:

{"teamId":"test-team","name":"test-team","users":[{"userId":"kubeadmin","directoryId":"ROKS","userBaseDN":"kubeadmin","baseDN":"kubeadmin","firstName":"kubeadmin","lastName":"","email":"","roles":[{"id":"crn:v1:icp:private:iam::::role:ClusterAdministrator"}]},{"userId":"anna","firstName":"anna","lastName":"","email":"","userBaseDN":"anna","directoryId":"acae8550-fc3b-11ea-99f3-018edd55e9a4","roles":[{"id":"crn:v1:icp:private:iam::::role:Administrator"}]}],"usergroups":[],"serviceids":[],"accountId":"id-mycluster-account","type":"System","directoryList":["ROKS"]}

Note: If you try to add a user who is already added to the team, you see the following 409 error:

  User already exists in team and role update is not supported

Assign resources to a team

API version

1.0.0

API URI components

Scheme

HTTPS

Host IP

Cluster Master Host

Port number

Cluster Master API Port

Path

idmgmt/identity/api/v1/teams

Command

POST

Command output format

application/json

The sample curl command resembles the following code:

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header "Authorization: bearer $ACCESS_TOKEN" -d '{"crn": "crn:v1:icp:private:k8:mycluster.icp:n/default:::"}' 'https://<cluster_address>/idmgmt/identity/api/v1/teams/<team-ID>/resources' --insecure

The format of the resource that you are assigning to the team is "crn:v1:icp:private:k8:mycluster:n/default:::", where mycluster is the cluster name. In the sample command, the default namespace is assigned to the team.

Note: You should not use the default namespace in the production environment.

The response resembles the following code:

{
    "crn": "crn:v1:icp:private:k8:mycluster:n/default:::",
    "serviceName": "k8",
    "region": "mycluster",
    "namespaceId": "default",
    "scope": "namespace"
}

Using wildcard characters in the CRN attribute resource value

You can use wildcard characters in the value of the CRN attribute resource. See the following sample curl command:

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header "Authorization: bearer $ACCESS_TOKEN" -d '
{"crn":"crn:v1:icp:private:eventstreams:mycluster:n/kube-system:r/kafka2:topic:topic*"}' <--- Wildcard character asterisk \
"https://<cluster_address>/idmgmt/identity/api/v1/teams/team-$i/resources" --insecure

In the sample command, an asterisk is used. All CRNs with resource name that starts with topic are accessible, if all the CRN attributes match the access policy definition, and the user has the required permissions.

Following is a sample authorization check:

curl -k -X POST \
  https://<cluster_address>/iam-pdp/v1/authz \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "action": "action.read",
  "subject": {
    "id": "",
    "type": ""
  },
  "resource": {
    "crn": "crn:v1:icp:private:eventstreams:mycluster:n/kube-system:r/kafka2:topic:topic1",
    "attributes": {
      "serviceName": "",
      "accountId": ""
    }
  }
}'

Following is a sample output:

{"decision":"Permit","obligations":[{"actions":["action.read"],"crns":["crn:v1:icp:private:eventstreams:mycluster:n/kube-system:r/kafka2:topic:topic1"],"decision":"Permit","max-age":86400,"obligationId":"bf69c79fbe636dc8"}]}

Add Helm chart resources to a team

API version

1.0.0

API URI components

Scheme

HTTPS

Host IP

cluster_lb_address

Path

/helm-api/api/v2/releasesCRNs

/helm-api/api/v2/charts

/helm-api/api/v2/repos

Command

POST

Command output format

application/json

The sample curl command resembles the following code:

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header "Authorization: bearer $ACCESS_TOKEN" -d '{"crn":"crn:v1:icp:private:helm-catalog:mycluster:r/local-charts::helm-repos:"}' "https://mycluster.icp:8443/idmgmt/identity/api/v1/teams/team-$i/resources" --insecure

The format of the resource that you are assigning to the team is "crn:v1:icp:private:helm-catalog:mycluster:r/local-charts::helm-repos:". In the sample command, the local-charts repository is assigned to the team.

The response resembles the following code:

{"crn":"crn:v1:icp:private:helm-catalog:mycluster.icp:r/local-charts:::","serviceName":"k8","region":"mycluster.icp","repository":"local-charts","scope":"helm-repos"}

Get information about a team

API version

1.0.0

API URI components

Scheme

HTTPS

Host IP

Cluster Master Host

Port number

Cluster Master API Port

Path

idmgmt/identity/api/v1/teams/{id}

Command

GET

Command output format

application/json

The sample curl command resembles the following code:

curl -k -X GET --header "Authorization: Bearer $ACCESS_TOKEN" 'https://<cluster_address>/idmgmt/identity/api/v1/teams/test-team'

The output resembles the following code:

{"teamId":"test-team","name":"Test Team","users":[{"userId":"testuser","userBaseDN":"uid=testuser,ou=people,dc=ibm,dc=com","roles":[{"id":"crn:v1:icp:private:iam::::role:Operator"}]}],"usergroups":[{"name":"security","userGroupDN":"cn=security,cn=platform,ou=cloud,ou=isl,ou=groups,dc=ibm,dc=com","roles":[{"id":"crn:v1:icp:private:iam::::role:Operator"}]}]}

Get information about all teams

API version

1.0.0

API URI components

Scheme

HTTPS

Host IP

Cluster Master Host

Port number

Cluster Master API Port

Path

idmgmt/identity/api/v1/teams

Command

GET

Command output format

application/json

The sample curl command resembles the following code:

curl -k -X GET --header "Authorization: Bearer $ACCESS_TOKEN" 'https://<cluster_address>/idmgmt/identity/api/v1/teams'

The output resembles the following code:

 {
    "teamId": "test-team",
    "name": "test-team",
    "users": [
        {
            "userId": "mark",
            "directoryId": "d77de310-ca65-11e9-9c54-5bd9ecf04530",
            "firstName": "Mark",
            "lastName": "",
            "email": "mark@ibm.com",
            "lastLogin": "",
            "userBaseDN": "uid=mark,ou=people,dc=ibm,dc=com",
            "type": "LDAP",
            "directoryName": "openldap",
            "roles": [
                {
                    "id": "crn:v1:icp:private:iam::::role:Viewer"
                }
            ]
        }
    ],
    "usergroups": [],
    "serviceids": [],
    "accountId": "110a-6bdb",
    "type": "Custom",
    "directoryList": [
        "d77de310-ca65-11e9-9c54-5bd9ecf04530"
    ]
}

Get resources that are assigned to a team

API version

1.0.0

API URI components

Scheme

HTTPS

Host IP

Cluster Master Host

Port number

Cluster Master API Port

Path

idmgmt/identity/api/v1/teams/{id}/resources

Command

GET

Command output format

application/json

The sample curl command resembles the following code:

curl -k -X GET --header "Authorization: Bearer $ACCESS_TOKEN" 'https://<cluster_address>/idmgmt/identity/api/v1/teams/{id}/resources'

The output resembles the following code:

[{"crn":"crn:v1:icp:private:k8:mycluster:n/default:::","serviceName":"k8","region":"mycluster","namespaceId":"default","scope":"namespace"}]

Update a team

API version

1.0.0

API URI components

Scheme

HTTPS

Host IP

Cluster Master Host

Port number

Cluster Master API Port

Path

idmgmt/identity/api/v1/teams

Command

PUT

Command output format

application/json

The sample curl command resembles the following code:

curl -k -X PUT --header 'Content-Type: application/json' --header "Authorization: bearer $ACCESS_TOKEN" -d '{"teamId":"test-team","name":"Test Team","users":[{"userId":"aaa","roles":[{"id":"crn:v1:icp:private:iam::::role:Administrator"}]},{"userId":"bbb","roles":[{"id":"crn:v1:icp:private:iam::::role:Editor"}]},{"userId":"ccc","roles":[{"id":"crn:v1:icp:private:iam::::role:Editor"}]},{"userId":"ddd","roles":[{"id":"crn:v1:icp:private:iam::::role:Viewer"}]}]}' 'https://<cluster_address>/idmgmt/identity/api/v1/teams/test-team'

The output resembles the following code:

{"teamId":"test-team","name":"Test Team","users":[{"userId":"aaa","roles":[{"id":"crn:v1:icp:private:iam::::role:Administrator"}]},{"userId":"bbb","roles":[{"id":"crn:v1:icp:private:iam::::role:Editor"}]},{"userId":"ccc","roles":[{"id":"crn:v1:icp:private:iam::::role:Editor"}]},{"userId":"ddd","roles":[{"id":"crn:v1:icp:private:iam::::role:Viewer"}]}],"usergroups":[],"_rev":"2-9238053d5bc6a27237a444e0a2e2cc5b","_id":"f-122","loopback__model__name":"Team"}

Delete a resource from a team

API version

1.0.0

API URI components

Scheme

HTTPS

Host IP

Cluster Master Host

Port number

Cluster Master API Port

Path

idmgmt/identity/api/v1/teams/{id}

Command

DELETE

Command output format

application/json

To delete a resource from a team, you must first get all the resources for the team (platform) so that you can retrieve the CRN. The sample curl command resembles the following code:

curl -k -X GET --header "Authorization: Bearer $ACCESS_TOKEN" 'https://<cluster_address>/idmgmt/identity/api/v1/teams/platform/resources'

The output resembles the following code:

[
{"crn":"crn:v1:icp:private:k8:mycluster:n/kube-system:::","serviceName":"k8","region":"mycluster","namespaceId":"kube-system"},
{"crn":"crn:v1:icp:private:k8:mycluster:n/default:::","serviceName":"k8","region":"mycluster","namespaceId":"default"}
]

Next, you must encode the CRN. You can use the urlencode command (on Ubuntu), as shown in the following sample code, or you can use a Python script.

urlencode 'crn:v1:icp:private:k8:mycluster:n/default:::'

The output resembles the following code:

crn%3Av1%3Aicp%3Aprivate%3Ak8%3Amycluster%3An%2Fdefault%3A%3A%3A

Finally, you can delete the resource from the team (platform) by using the encoded CRN. The sample curl command resembles the following code:

curl -k -X DELETE --header "Authorization: Bearer $ACCESS_TOKEN" --header "Content-Type: application/json" --header "Accept: application/json" 'https://<cluster_address>/idmgmt/identity/api/v1/teams/platform/resources/rel/crn%3Av1%3Aicp%3Aprivate%3Ak8%3Amycluster%3An%2Fdefault%3A%3A%3A'

If needed, you can get the list of resources to confirm that the resource is removed. The sample curl command resembles the following code:

curl -k -X GET --header "Authorization: Bearer $ACCESS_TOKEN" 'https://<cluster_address>/idmgmt/identity/api/v1/teams/platform/resources'

The output resembles the following code:

[
{"crn":"crn:v1:icp:private:k8:mycluster:n/kube-system:::","serviceName":"k8","region":"mycluster","namespaceId":"kube-system"}
]

Remove a user from a team

API version

1.0.0

API URI components

Scheme

HTTPS

Host IP

Cluster Master Host

Port number

Cluster Master API Port

Path

idmgmt/identity/api/v1/teams/{team-id}

Command

DELETE

Command output format

application/json

The sample curl command resembles the following code:

Note: To get the userID, use the API to Get information about a team.

curl --location --request DELETE 'https://<cluster_address>/idmgmt/identity/api/v1/teams/test-team/users' \
--header 'Authorization: Bearer $ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
    "users": [
        {
            "userId": "testuser@in.ibm.com"
        }
    ]
}'

The output of the curl command is 204 status code.

Note: If you try to remove a user who is not in the team, you see the following 404 error:

  User not found in team, nothing to delete

Delete a team

API version

1.0.0

API URI components

Scheme

HTTPS

Host IP

Cluster Master Host

Port number

Cluster Master API Port

Path

idmgmt/identity/api/v1/teams/{id}

Command

DELETE

Command output format

application/json

The sample curl command resembles the following code:

curl -k -X DELETE --header "Authorization: Bearer $ACCESS_TOKEN" 'https://<cluster_address>/idmgmt/identity/api/v1/teams/a-1'

The output resembles the following code:

{"count":1}