Incorrect documentation of /Groups/{groupId}/members (origin)

SECURITY NOTICE: If you have found a security problem in the UAA, please do not file a public github issue. Instead, please send an email to security@cloudfoundry.org

Thanks for taking the time to file an issue. You'll minimize back and forth and help us help you more effectively by answering all of the following questions as specifically and completely as you can.

What version of UAA are you running?

Version 76.5.0
https://docs.cloudfoundry.org/api/uaa/version/76.5.0/index.html#add-member

How are you deploying the UAA?

We are using the BOSH release: https://github.com/cloudfoundry/uaa-release/releases/tag/v76.5.0

What did you do?

We add users managed by an identity provider (origin=sap.ids in our case) to a group cloud_controller.v2_api_rate_limit_exempt.
E.g. POST /Groups/<groupId>/members with body {"origin":"sap.ids","type":"USER","value":"<user-guid>"}

What did you expect to see? What goal are you trying to achieve with the UAA?

When the user works with cf cli, the user shall have the the scope cloud_controller.v2_api_rate_limit_exempt so that it gets exempted from CF API v2 rate limiting. This is a CAPI specific functionality. The UAA client cf used by cf cli is properly configured to support the scope cloud_controller.v2_api_rate_limit_exempt. See also https://github.com/cloudfoundry/docs-running-cf/pull/109 (doc about CF API v2 rate limiting, not yet merged unfortunately).

What did you see instead?

The membership of an added user to the group cloud_controller.v2_api_rate_limit_exempt disappeared silently when the user authenticated (e.g. using cf login).

There were no related UAA logs (expected to see GroupModifiedEvent logs) -> #2189

After a discussion with UAA committers it turned out that the origin parameter of the POST /Groups/<groupId>/members is not the origin of the user but the origin of the membership. If set to sap.ids UAA tries to get group membership from the identity provider configured for sap.ids. Since it doesn't know any group cloud_controller.v2_api_rate_limit_exempt, the membership is removed from UAA.
If we set the origin parameter to uaa it works as expected and the membership remains when the user logs in.

However, https://docs.cloudfoundry.org/api/uaa/version/76.5.0/index.html#check-membership specifies the origin parameter as:

The originating IDP of the entity, or "uaa" for groups and internal users

With "entity" the user or group is meant that is added as member to a group (at least this is how I read the documentation). SInce we added an sap.ids user, we specified sap.ids as origin in the add-member call and bad things happened.

The documentation should be corrected.

Start at the UAA API documentation for version 76.5.0, especially the /Groups/{groupId}/members add-member and check-membership sections linked in the issue. Clarify that the origin parameter identifies the membership origin, not the user's identity-provider origin; done means the documentation no longer suggests using sap.ids for this membership.