python-comanage-api

为COmanage REST API v1提供有限的Python 3客户端实现（包装器）：https://spaces.at.internet2.edu/display/COmanage/REST+API+v1

在PyPi上可用：https://pypi.ac.cn/project/fabric-comanage-api/

免责声明：此处代码可能不是最新的，也可能不符合最新的包和安全通知。此代码的审查和更新频率仅基于支持其编写项目的生命周期，并且在该范围之外不积极维护。自行承担风险。

目录

• TL;DR
• API端点
  • CoOrgIdentityLink
  • CoPerson
  • CoPersonRole
  • Cou
  • EmailAddress
  • Identifier
  • Name
  • OrgIdentity
  • SshKey
• Usage
• COmanage中的SSH密钥认证插件
• 参考

TL;DR

从PyPi安装最新版本

pip install fabric-comanage-api

创建COmanage API连接

from comanage_api import ComanageApi

api = ComanageApi(
    co_api_url=COMANAGE_API_URL,
    co_api_user=COMANAGE_API_USER,
    co_api_pass=COMANAGE_API_PASS,
    co_api_org_id=COMANAGE_API_CO_ID,
    co_api_org_name=COMANAGE_API_CO_NAME,
    co_ssh_key_authenticator_id=COMANAGE_API_SSH_KEY_AUTHENTICATOR_ID
)

获取一些数据！（使用示例 cous_view_per_co()，它检索给定的CO连接的所有COU）

$ python
Python 3.9.6 (v3.9.6:db3ff76da1, Jun 28 2021, 11:49:53)
[Clang 6.0 (clang-600.0.57)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>>
>>> from comanage_api import ComanageApi
>>>
>>> api = ComanageApi(
...     co_api_url='https://FQDN_OF_REGISTRY',
...     co_api_user='co_123.api-user-name',
...     co_api_pass='xxxx-xxxx-xxxx-xxxx',
...     co_api_org_id='123',
...     co_api_org_name='RegistryName',
...     co_ssh_key_authenticator_id='123'
... )
>>>
>>> cous = api.cous_view_per_co()
>>>
>>> print(cous)
{'ResponseType': 'Cous', 'Version': '1.0', 'Cous': [{'Version': '1.0', 'Id': '38', 'CoId': '123', 'Name': 'enrollment-approval', 'Description': 'Enrollment Approval Personnel - can approve or deny new registry members', 'Lft': '66', 'Rght': '67', 'Created': '2021-09-10 14:33:11', 'Modified': '2021-09-10 14:33:11', 'Revision': '0', 'Deleted': False, 'ActorIdentifier': 'http://cilogon.org/serverA/users/242181'}, {'Version': '1.0', 'Id': '39', 'CoId': '123', 'Name': 'impact-users', 'Description': "ImPACT Users - Registering with the ImPACT site will add new user's to this group", 'Lft': '68', 'Rght': '69', 'Created': '2021-09-10 14:44:09', 'Modified': '2021-09-10 14:44:09', 'Revision': '0', 'Deleted': False, 'ActorIdentifier': 'http://cilogon.org/serverA/users/242181'}]}
>>>
>>> import json
>>> print(json.dumps(cous, indent=2))
{
  "ResponseType": "Cous",
  "Version": "1.0",
  "Cous": [
    {
      "Version": "1.0",
      "Id": "38",
      "CoId": "123",
      "Name": "enrollment-approval",
      "Description": "Enrollment Approval Personnel - can approve or deny new registry members",
      "Lft": "66",
      "Rght": "67",
      "Created": "2021-09-10 14:33:11",
      "Modified": "2021-09-10 14:33:11",
      "Revision": "0",
      "Deleted": false,
      "ActorIdentifier": "http://cilogon.org/serverA/users/242181"
    },
    {
      "Version": "1.0",
      "Id": "39",
      "CoId": "123",
      "Name": "impact-users",
      "Description": "ImPACT Users - Registering with the ImPACT site will add new user's to this group",
      "Lft": "68",
      "Rght": "69",
      "Created": "2021-09-10 14:44:09",
      "Modified": "2021-09-10 14:44:09",
      "Revision": "0",
      "Deleted": false,
      "ActorIdentifier": "http://cilogon.org/serverA/users/242181"
    }
  ]
}
>>>

API端点

返回类型基于包装API端点的实现状态

• 已实现
  • -> dict：数据作为Python 字典对象返回
  • -> bool：成功/失败作为Python 布尔对象返回
• 未实现（### NOT IMPLEMENTED ###）
  • -> dict：引发异常（HTTPError - 501 Server Error: Not Implemented for url: mock://not_implemented_501.local）
  • -> bool: 抛出异常 (HTTPError - 501 Server Error: Not Implemented for url: mock://not_implemented_501.local)

CoOrgIdentityLink API (COmanage v4.0.0+)

• coorg_identity_links_add() -> dict
  • ### 未实现 ###
  • 添加一个新的 CO 组织身份链接。
  • 在可以建立链接之前，个人必须有一个组织身份和 CO 人员记录。
  • 请注意，邀请是单独的操作。
• coorg_identity_links_delete() -> bool
  • ### 未实现 ###
  • 删除一个 CO 组织身份链接。
• coorg_identity_links_edit() -> bool
  • ### 未实现 ###
  • 编辑现有的 CO 身份链接。
• coorg_identity_links_view_all() -> dict
  • 检索所有现有的 CO 身份链接。
• coorg_identity_links_view_by_identity(identifier_id: int) -> dict
  • 检索 CO 人员或组织身份的所有现有 CO 身份链接。
• coorg_identity_links_view_one(org_identity_id: int) -> dict
  • 检索现有的 CO 身份链接。

注意：当提供时，有效的 identity_type 值如下

IDENTITY_OPTIONS = ['copersonid', 'orgidentityid']

CoPerson API (COmanage v3.3.0+)

• copeople_add() -> dict
  • ### 未实现 ###
  • 添加一个新的 CO 人员。在可以添加到 CO 之前，个人必须有一个 OrgIdentity。
  • 请注意，链接到 OrgIdentity 和邀请是单独的操作。
• copeople_delete() -> bool
  • ### 未实现 ###
  • 删除 CO 人员。此方法还将删除相关数据，例如 CoPersonRoles、EmailAddresses 和 Identifiers。
  • 在可以删除 OrgIdentity 记录之前，必须从任何 CO 中删除人员（必须删除 CoPerson 记录）。
• copeople_edit() -> bool
  • ### 未实现 ###
  • 编辑现有的 CO 人员。
• copeople_find() -> dict
  • ### 未实现 ###
  • 搜索现有的 CO 人员记录。
  • 当找到太多记录时，可能会返回一条消息而不是特定记录。
• copeople_match(given: str = None, family: str = None, mail: str = None, distinct_by_id: bool = True) -> dict
  • 尝试匹配现有的 CO 人员记录。
  • 请注意，对于小于 3 个字符的搜索条件或不符合语法的电子邮件地址，不执行匹配。
• copeople_view_all() -> dict
  • 检索所有现有的 CO 人员。
• copeople_view_per_co() -> dict
  • 检索指定 CO 的所有现有 CO 人员。
• copeople_view_per_identifier(identifier: str, distinct_by_id: bool = True) -> dict
  • 检索与指定标识符相关联的所有现有 CO 人员。
  • 请注意，指定的标识符必须与 CO 人员相关联，而不是与组织身份相关联。
• copeople_view_one(coperson_id: int) -> dict
  • 检索现有的 CO 人员。

CoPersonRole API (COmanage v3.3.0+)

• coperson_roles_add(coperson_id: int, cou_id: int, status: str = None, affiliation: str = None) -> dict
  • 添加一个新的 CO 人员角色。
• coperson_roles_delete(coperson_role_id: int) -> bool
  • 删除 CO 人员角色。
• coperson_roles_edit(coperson_role_id: int, coperson_id: int = None, cou_id: int = None, status: str = None, affiliation: str = None) -> bool
  • 编辑现有的 CO 人员角色。
• coperson_roles_view_all() -> dict
  • 检索所有现有的 CO 人员角色。
• coperson_roles_view_per_coperson(coperson_id: int) -> dict
  • 检索指定 CO 人员的所有现有 CO 人员角色。自注册版本 2.0.0 以来可用。
• coperson_roles_view_per_cou(cou_id: int) -> dict
  • 检索指定 COU 的所有现有 CO 人员角色。
• coperson_roles_view_one(coperson_role_id: int) -> dict
  • 检索现有的 CO 人员角色。

注意：当提供时，有效的 status 和 affiliation 值如下

STATUS_OPTIONS = ['Active', 'Approved', 'Confirmed', 'Declined', 'Deleted', 'Denied', 'Duplicate', 
'Expired', 'GracePeriod', 'Invited', 'Pending', 'PendingApproval', 'PendingConfirmation', 'Suspended']
AFFILIATION_OPTIONS = ['affiliate', 'alum', 'employee', 'faculty', 'member', 'staff', 'student']

COU API (COmanage v3.3.0+)

• cous_add(name: str, description: str, parent_id: int = None) -> dict
  • 添加一个新的 Cou。
• cous_delete(cou_id: int) -> bool
  • 删除一个 Cou。
• cous_edit(cou_id: int, name: str = None, description: str = None, parent_id: int = None) -> bool
  • 编辑现有的Cou。
• cous_view_all() -> dict
  • 检索所有现有的Cous。
• cous_view_per_co() -> dict
  • 检索与CO关联的Cou。
• cous_view_one(cou_id: int) -> dict
  • 检索现有的Cou。

注意：在cous_edit中，当设置parent_id=0时，将重置COU的parent_id值为None（没有父级）。

电子邮件地址API（COmanage v3.3.0+）

• email_addresses_add() -> dict
  • ### 未实现 ###
  • 添加新的电子邮件地址。
• email_addresses_delete() -> bool
  • ### 未实现 ###
  • 删除电子邮件地址。
• email_addresses_edit() -> bool
  • ### 未实现 ###
  • 编辑现有的电子邮件地址。
• email_addresses_view_all() -> dict
  • 检索所有现有的电子邮件地址。
• email_addresses_view_per_person(person_type: str, person_id: int) -> dict
  • 检索与CO部门、CO人员或组织标识关联的电子邮件地址。
• email_addresses_view_one(email_address_id: int) -> dict
  • 检索现有的电子邮件地址。

注意：当提供时，有效的person_type值如下

EMAILADDRESS_OPTIONS = ['codeptid', 'copersonid', 'organizationid', 'orgidentityid']

标识符API（COmanage v3.3.0+）

• identifiers_add() -> dict
  • ### 未实现 ###
  • 添加新的标识符。
• identifiers_assign() -> bool
  • ### 未实现 ###
  • 为CO人员分配标识符。
• identifiers_delete() -> bool
  • ### 未实现 ###
  • 删除标识符。
• identifiers_edit() -> bool
  • ### 未实现 ###
  • 编辑现有的标识符。
• identifiers_view_all() -> dict
  • 检索所有现有的标识符。
• identifiers_view_per_entity(entity_type: str, entity_id: int) -> dict
  • 检索与CO部门、Co组、CO人员或组织标识关联的标识符。
• identifiers_view_one(identifier_id: int) -> dict
  • 检索现有的标识符。

注意：当提供时，有效的entity_type值如下

ENTITY_OPTIONS = ['codeptid', 'cogroupid', 'copersonid', 'organizationid', 'orgidentityid']

名称API（COmanage v3.3.0+）

• names_add() -> dict
  • ### 未实现 ###
  • 添加新的名称。
• names_delete() -> bool
  • ### 未实现 ###
  • 删除名称。
• names_edit() -> bool
  • ### 未实现 ###
  • 编辑现有的名称。
• names_view_all() -> dict
  • 检索所有现有的名称。
• names_view_per_person(person_type: str, person_id: int) -> dict
  • 检索与CO人员或组织标识关联的名称。
• names_view_one(name_id: int) -> dict
  • 检索与CO人员或组织标识关联的名称。

注意：当提供时，有效的person_type值如下

PERSON_OPTIONS = ['copersonid', 'orgidentityid']

组织标识API（COmanage v3.3.0+）

• org_identities_add() -> dict
  • ### 未实现 ###
  • 添加新的组织标识。一个人必须有一个OrgIdentity才能被添加到CO中。
• org_identities_delete() -> bool
  • ### 未实现 ###
  • 删除组织标识。
  • 在删除组织标识记录之前，必须将该人员从任何CO（CoPerson）中删除。
  • 此方法还将删除相关数据，例如地址、电子邮件地址和电话号码。
• org_identities_edit() -> bool
  • ### 未实现 ###
  • 编辑现有的组织标识。
• org_identities_view_all() -> dict
  • 检索所有现有的组织标识。
• org_identities_view_per_co(person_type: str, person_id: int) -> dict
  • 检索指定CO的所有现有组织标识。
• org_identities_view_per_identifier(identifier_id: int) -> dict
  • 检索与指定标识符关联的所有现有组织标识。
  • 注意指定的标识符必须附加到组织标识，而不是CO人员。
• org_identities_view_one(org_identity_id: int) -> dict
  • 检索现有的组织标识。

SSH密钥API（COmanage v4.0.0+）

需要：管理CO人员的SSH公钥的SSH密钥验证插件。

• ssh_keys_add(coperson_id: int, ssh_key: str, key_type: str, comment: str = None, ssh_key_authenticator_id: int = None) -> dict
  • 添加新的SSH密钥。
• ssh_keys_delete(ssh_key_id: int) -> bool
  • 移除SSH密钥。
• ssh_keys_edit(ssh_key_id: int, coperson_id: int = None, ssh_key: str = None, key_type: str = None, comment: str = None, ssh_key_authenticator_id: int = None) -> bool
  • 编辑现有的SSH密钥。
• ssh_keys_view_all() -> dict
  • 检索所有现有的SSH密钥。
• ssh_keys_view_per_coperson(coperson_id: int) -> dict
  • 检索指定CO人员的所有现有SSH密钥。
• ssh_keys_view_one(ssh_key_id: int) -> dict
  • 检索现有的SSH密钥。

注意：当提供时，有效的ssh_key_type值如下

SSH_KEY_OPTIONS = ['ssh-dss', 'ecdsa-sha2-nistp256', 'ecdsa-sha2-nistp384', 
'ecdsa-sha2-nistp521', 'ssh-ed25519', 'ssh-rsa', 'ssh-rsa1']

用法

设置虚拟环境（以下示例中使用virtualenv）

virtualenv -p /usr/local/bin/python3 venv
source venv/bin/activate

安装支持包

从PyPi安装

pip install fabric-comanage-api

或

为本地开发安装

pip install -r requirements.txt

配置你的环境

如果你不想在代码中放置API凭证，请从提供的模板创建一个.env文件。示例代码使用了python-dotenv

cp template.env .env

根据你的COmanage注册表设置配置.env

# COmanage API user and pass
COMANAGE_API_USER=co_123.api-user-name
COMANAGE_API_PASS=xxxx-xxxx-xxxx-xxxx
# COmanage CO Information
COMANAGE_API_CO_NAME=RegistryName
COMANAGE_API_CO_ID=123
# COmanage registry URL
COMANAGE_API_URL=https://FQDN_OF_REGISTRY
# COmanage SshKeyAuthenticatorId (optional)
COMANAGE_API_SSH_KEY_AUTHENTICATOR_ID=123

示例代码

请参阅示例中的代码，了解如何使用每个端点

SSH密钥验证器插件

SSH密钥验证器插件管理CO人员的SSH公钥。

• SSH密钥验证器插件从注册表v3.3.0版本开始可用。在此版本之前，SSH密钥管理通过CO人员画布提供。

注册后，您可以在编辑验证器的URL中找到COMANAGE_API_SSH_KEY_AUTHENTICATOR_ID的值

• 在这个示例URL中为3： https://registry.cilogon.org/registry/authenticators/edit/3

注意:

• 实验性

  • SshKey API是通过SSH密钥验证器插件实现的。插件提供的REST API目前被视为实验性，因此此接口可能在较小版本之间不通知而更改。

• 实现说明

  • 仅支持JSON格式。不支持XML格式。
  • 注意，此API的URL使用插件语法。（路径中有额外组件。）
  • 如SshKey模式定义，请求中需要一个SSH密钥验证器ID。这指的是为CO实例化的验证器。
  • 锁定状态的验证器不能通过API进行管理。

在COmanage中添加新的SSH密钥验证器

要创建新的SSH密钥验证器，首先从COmanage配置页面选择“验证器”选项

然后选择“添加验证器”选项

填写必填字段，并将状态设置为“活动”和“添加”验证器

成功后，一个绿色的框表示已添加新的验证器

现在，当你从COmanage配置页面选择“验证器”选项时，你应该看到你新创建的验证器

点击“编辑”选项将显示验证器的字段及其URL中的SshKeyAuthenticatorId值（本例中为3）

参考

• COmanage REST API v1: https://spaces.at.internet2.edu/display/COmanage/REST+API+v1
• CoOrgIdentityLink API: https://spaces.at.internet2.edu/display/COmanage/CoOrgIdentityLink+API
• COU API: https://spaces.at.internet2.edu/display/COmanage/COU+API
• CoPerson API: https://spaces.at.internet2.edu/display/COmanage/CoPerson+API
• CoPersonRole API: https://spaces.at.internet2.edu/display/COmanage/CoPersonRole+API
• EmailAddress API: https://spaces.at.internet2.edu/display/COmanage/EmailAddress+API
• 标识符API: https://spaces.at.internet2.edu/display/COmanage/Identifier+API
• 名称API: https://spaces.at.internet2.edu/display/COmanage/Name+API
• 组织标识符API: https://spaces.at.internet2.edu/display/COmanage/OrgIdentity+API
• SSH密钥API: https://spaces.at.internet2.edu/display/COmanage/SshKey+API
• SSH密钥验证插件: https://spaces.at.internet2.edu/display/COmanage/SSH+Key+Authenticator+Plugin
• PyPi: https://pypi.ac.cn