From 4fec2c18ff302c09f16c2c48436110abdf36d85a Mon Sep 17 00:00:00 2001 From: GitHub Action Bot Date: Thu, 2 Mar 2023 21:08:11 +0000 Subject: [PATCH] Automated commit 'IDNLANAI-8347: Add api-spec for role & access profile /v3 endpoints (#1188) * IDNLANAI-8347: Add api-spec for role & access profile /v3 endpoints * IDNLANAI-8347: Add api-spec for role & access profile /v3 endpoints * IDNLANAI-8347: Add api-spec for role & access profile /v3 endpoints * IDNLANAI-8347: Add api-spec for role & access profile /v3 endpoints * IDNLANAI-8347: Add api-spec for role & access profile /v3 endpoints * IDNLANAI-8347: Add api-spec for role & access profile /v3 endpoints * IDNLANAI-8347: Add api-spec for role & access profile /v3 endpoints * IDNLANAI-8347: Add api-spec for role & access profile /v3 endpoints' by github action: 4318248393 --- idn/sailpoint-api.v3.yaml | 89 ++++++++ idn/v3/paths/access-profile-bulk-delete.yaml | 85 ++++++++ idn/v3/paths/access-profile-entitlements.yaml | 90 ++++++++ idn/v3/paths/access-profile.yaml | 134 ++++++++++++ idn/v3/paths/access-profiles.yaml | 153 ++++++++++++++ idn/v3/paths/role-assigned-identities.yaml | 72 +++++++ idn/v3/paths/role.yaml | 195 ++++++++++++++++++ idn/v3/paths/roles.yaml | 139 +++++++++++++ idn/v3/schemas/Entitlement.yaml | 78 +++++++ idn/v3/schemas/PermissionDto.yaml | 16 ++ 10 files changed, 1051 insertions(+) create mode 100644 idn/v3/paths/access-profile-bulk-delete.yaml create mode 100644 idn/v3/paths/access-profile-entitlements.yaml create mode 100644 idn/v3/paths/access-profile.yaml create mode 100644 idn/v3/paths/access-profiles.yaml create mode 100644 idn/v3/paths/role-assigned-identities.yaml create mode 100644 idn/v3/paths/role.yaml create mode 100644 idn/v3/paths/roles.yaml create mode 100644 idn/v3/schemas/Entitlement.yaml create mode 100644 idn/v3/schemas/PermissionDto.yaml diff --git a/idn/sailpoint-api.v3.yaml b/idn/sailpoint-api.v3.yaml index ae1bf8f..f0bba64 100644 --- a/idn/sailpoint-api.v3.yaml +++ b/idn/sailpoint-api.v3.yaml @@ -25,6 +25,42 @@ servers: This is the name of your tenant, typically your company's name. tags: + - name: Access Profiles + description: | + Use this API to implement and customize access profile functionality. + With this functionality in place, administrators can create access profiles and configure them for use throughout IdentityNow, enabling users to get the access they need quickly and securely. + + Access profiles group entitlements, which represent access rights on sources. + + For example, an Active Directory source in IdentityNow can have multiple entitlements: the first, 'Employees,' may represent the access all employees have at the organization, and a second, 'Developers,' may represent the access all developers have at the organization. + + An administrator can then create a broader set of access in the form of an access profile, 'AD Developers' grouping the 'Employees' entitlement with the 'Developers' entitlement. + + When users only need Active Directory employee access, they can request access to the 'Employees' entitlement. + + When users need both Active Directory employee and developer access, they can request access to the 'AD Developers' access profile. + + Access profiles are the most important units of access in IdentityNow. IdentityNow uses access profiles in many features, including the following: + + - Provisioning: When you use the Provisioning Service, lifecycle states and roles both grant access to users in the form of access profiles. + + - Certifications: You can approve or revoke access profiles in certification campaigns, just like entitlements. + + - Access Requests: You can assign access profiles to applications, and when a user requests access to the app associated with an access profile and someone approves the request, access is granted to both the application and its associated access profile. + + - Roles: You can group one or more access profiles into a role to quickly assign access items based on an identity's role. + + In IdentityNow, administrators can use the Access drop-down menu and select Access Profiles to view, configure, and delete existing access profiles, as well as create new ones. + Administrators can enable and disable an access profile, and they can also make the following configurations: + + - Manage Entitlements: Manage the profile's access by adding and removing entitlements. + + - Access Requests: Configure access profiles to be requestable and establish an approval process for any requests that the access profile be granted or revoked. + Do not configure an access profile to be requestable without first establishing a secure access request approval process for the access profile. + + - Multiple Account Options: Define the logic IdentityNow uses to provision access to an identity with multiple accounts on the source. + + Refer to [Managing Access Profiles](https://documentation.sailpoint.com/saas/help/access/access-profiles.html) for more information about access profiles. - name: Access Request Approvals description: | Use this API to implement and customize access request approval functionality. @@ -319,6 +355,45 @@ tags: Use this API to implement requestable object functionality. With this functionality in place, administrators can determine which access items can be requested with the [Access Request APIs](https://developer.sailpoint.com/idn/api/v3/access-requests), along with their statuses. This can be helpful for administrators who are implementing and customizing access request functionality as a way of checking which items are requestable as they are created, assigned, and made available. + - name: Roles + description: | + Use this API to implement and customize role functionality. + With this functionality in place, administrators can create roles and configure them for use throughout IdentityNow. + IdentityNow can use established criteria to automatically assign the roles to qualified users. This enables users to get all the access they need quickly and securely and administrators to spend their time on other tasks. + + Entitlements represent the most granular level of access in IdentityNow. + Access profiles represent the next level and often group entitlements. + Roles represent the broadest level of access and often group access profiles. + + For example, an Active Directory source in IdentityNow can have multiple entitlements: the first, 'Employees,' may represent the access all employees have at the organization, and a second, 'Developers,' may represent the access all developers have at the organization. + + An administrator can then create a broader set of access in the form of an access profile, 'AD Developers' grouping the 'Employees' entitlement with the 'Developers' entitlement. + + An administrator can then create an even broader set of access in the form of a role grouping the 'AD Developers' access profile with another profile, 'GitHub Developers,' grouping entitlements for the GitHub source. + + When users only need Active Directory employee access, they can request access to the 'Employees' entitlement. + + When users need both Active Directory employee and developer access, they can request access to the 'AD Developers' access profile. + + When users need both the 'AD Developers' access profile and the 'GitHub Developers' access profile, they can request access to the role grouping both. + + Roles often represent positions within organizations. + For example, an organization's accountant can access all the tools the organization's accountants need with the 'Accountant' role. + If the accountant switches to engineering, a qualified member of the organization can quickly revoke the accountant's 'Accountant' access and grant access to the 'Engineer' role instead, granting access to all the tools the organization's engineers need. + + In IdentityNow, adminstrators can use the Access drop-down menu and select Roles to view, configure, and delete existing roles, as well as create new ones. + Administrators can enable and disable the role, and they can also make the following configurations: + + - Manage Access: Manage the role's access by adding or removing access profiles. + + - Define Assignment: Define the criteria IdentityNow uses to assign the role to identities. + Use the first option, 'Standard Criteria,' to provide specific criteria for assignment like specific account attributes, entitlements, or identity attributes. + Use the second, 'Identity List,' to specify the identities for assignment. + + - Access Requests: Configure roles to be requestable and establish an approval process for any requests that the role be granted or revoked. + Do not configure a role to be requestable without establishing a secure access request approval process for that role first. + + Refer to [Working with Roles](https://documentation.sailpoint.com/saas/help/provisioning/roles.html) for more information about roles. - name: Saved Search description: | Use this API to implement saved search functionality. @@ -495,6 +570,14 @@ tags: Refer to [Task Manager](https://documentation.sailpoint.com/saas/user-help/task_manager.html) for more information about work items, including the different types of work items users may need to complete. paths: + /access-profiles: + $ref: './v3/paths/access-profiles.yaml' + /access-profiles/{id}: + $ref: './v3/paths/access-profile.yaml' + /access-profiles/bulk-delete: + $ref: './v3/paths/access-profile-bulk-delete.yaml' + /access-profiles/{id}/entitlements: + $ref: './v3/paths/access-profile-entitlements.yaml' /access-requests: $ref: "./v3/paths/access-requests.yaml" /access-requests/cancel: @@ -621,6 +704,12 @@ paths: $ref: "./v3/paths/public-identities-config.yaml" /requestable-objects: $ref: "./v3/paths/requestable-object-list.yaml" + /roles: + $ref: './v3/paths/roles.yaml' + /roles/{id}: + $ref: './v3/paths/role.yaml' + /roles/{id}/assigned-identities: + $ref: './v3/paths/role-assigned-identities.yaml' /saved-searches: $ref: "./v3/paths/saved-searches.yaml" /saved-searches/{id}: diff --git a/idn/v3/paths/access-profile-bulk-delete.yaml b/idn/v3/paths/access-profile-bulk-delete.yaml new file mode 100644 index 0000000..d880221 --- /dev/null +++ b/idn/v3/paths/access-profile-bulk-delete.yaml @@ -0,0 +1,85 @@ +post: + operationId: deleteAccessProfilesInBulk + summary: Delete Access Profile(s) + tags: + - Access Profiles + description: >- + This API initiates a bulk deletion of one or more Access Profiles. + + + By default, if any of the indicated Access Profiles are in use, no deletions will be performed and the **inUse** + field of the response indicates the usages that must be removed first. If the request field **bestEffortOnly** is + **true**, however, usages are reported in the **inUse** response field but all other indicated Access Profiles will + be deleted. + + + A token with API, ORG_ADMIN, SOURCE_ADMIN, or SOURCE_SUBADMIN authority is required to call this API. In addition, + a SOURCE_SUBADMIN may only use this API to delete Access Profiles which are associated with Sources they are able + to administer. + requestBody: + required: true + content: + application/json: + schema: + $ref: '../../v3/schemas/access/AccessProfileBulkDeleteRequest.yaml' + example: + { + "bestEffortOnly": true, + "accessProfileIds": [ "2c91808876438bb2017668b91919ecca","2c91808876438ba801766e129f151816" ] + } + responses: + '200': + description: Returned only if **bestEffortOnly** is **false**, and one or more Access Profiles are in use. + content: + application/json: + schema: + $ref: '../../v3/schemas/access/AccessProfileBulkDeleteResponse.yaml' + example: + { + "pending": [], + "inUse": [ + { + "accessProfileId": "2c91808876438ba801766e129f151816", + "usages": [ + { + "type": "Role", + "id": "2c9180887643764201766e9f6e121518" + } + ] + } + ] + } + '202': + description: Returned if at least one deletion will be performed. + content: + application/json: + schema: + $ref: '../../v3/schemas/access/AccessProfileBulkDeleteResponse.yaml' + example: + { + "taskId":"2c91808a7813090a01781412a1119a20", + "pending":["2c91808a7813090a017813fe1919ecca"], + "inUse": [ + { + "accessProfileId": "2c91808876438ba801766e129f151816", + "usages": [ + { + "type": "Role", + "id": "2c9180887643764201766e9f6e121518" + } + ] + } + ] + } + '400': + $ref: '../../v3/responses/400.yaml' + '401': + $ref: '../../v3/responses/401.yaml' + '403': + $ref: '../../v3/responses/403.yaml' + '429': + $ref: '../../v3/responses/429.yaml' + '500': + $ref: '../../v3/responses/500.yaml' + security: + - oauth2: [idn:access-profile:manage] diff --git a/idn/v3/paths/access-profile-entitlements.yaml b/idn/v3/paths/access-profile-entitlements.yaml new file mode 100644 index 0000000..abb60b1 --- /dev/null +++ b/idn/v3/paths/access-profile-entitlements.yaml @@ -0,0 +1,90 @@ +get: + operationId: getAccessProfileEntitlements + tags: + - Access Profiles + summary: List Access Profile's Entitlements + description: >- + This API lists the Entitlements associated with a given Access Profile + + + A token with API, ORG_ADMIN, SOURCE_ADMIN, or SOURCE_SUBADMIN authority is required to invoke this API. In + addition, a token with SOURCE_SUBADMIN authority must have access to the Source associated with the given + Access Profile + parameters: + - name: id + in: path + description: ID of the containing Access Profile + required: true + schema: + type: string + example: 2c91808a7813090a017814121919ecca + - $ref: '../../v3/parameters/limit.yaml' + - $ref: '../../v3/parameters/offset.yaml' + - $ref: '../../v3/parameters/count.yaml' + - in: query + name: filters + schema: + type: string + description: >- + Filter results using the standard syntax described in [V3 API Standard Collection Parameters](https://developer.sailpoint.com/idn/api/standard-collection-parameters#filtering-results) + + + Filtering is supported for the following Entitlement fields and operators: + + **id**: *eq, in* + + + **name**: *eq, sw* + + + **attribute**: *eq, sw* + + + **value**: *eq, sw* + + + **created, modified**: *gt, lt, ge, le* + + + **owner.id**: *eq, in* + + + **source.id**: *eq, in* + example: attribute eq "memberOf" + required: false + - in: query + name: sorters + schema: + type: string + format: comma-separated + description: >- + Sort results using the standard syntax described in [V3 API Standard Collection Parameters](https://developer.sailpoint.com/idn/api/standard-collection-parameters#sorting-results) + + + Sorting is supported for the following fields: **name, attribute, value, created, modified** + example: name,-modified + required: false + responses: + '200': + description: List of Entitlements + content: + application/json: + schema: + type: array + items: + $ref: '../schemas/Entitlement.yaml' + '400': + $ref: '../../v3/responses/400.yaml' + '401': + $ref: '../../v3/responses/401.yaml' + '403': + $ref: '../../v3/responses/403.yaml' + '429': + $ref: '../../v3/responses/429.yaml' + '500': + $ref: '../../v3/responses/500.yaml' + security: + - oauth2: [idn:access-profile:read] + + + diff --git a/idn/v3/paths/access-profile.yaml b/idn/v3/paths/access-profile.yaml new file mode 100644 index 0000000..570fbb6 --- /dev/null +++ b/idn/v3/paths/access-profile.yaml @@ -0,0 +1,134 @@ +get: + operationId: getAccessProfile + tags: + - Access Profiles + summary: Get an Access Profile + description: >- + This API returns an Access Profile by its ID. + + + A token with API, ORG_ADMIN, ROLE_ADMIN, ROLE_SUBADMIN, SOURCE_ADMIN, or SOURCE_SUBADMIN authority is required to + call this API. + parameters: + - in: path + name: id + required: true + schema: + type: string + description: >- + ID of the Access Profile + example: 2c9180837ca6693d017ca8d097500149 + responses: + '200': + description: An AccessProfile + content: + application/json: + schema: + $ref: '../../v3/schemas/access/AccessProfile.yaml' + '400': + $ref: '../../v3/responses/400.yaml' + '401': + $ref: '../../v3/responses/401.yaml' + '403': + $ref: '../../v3/responses/403.yaml' + '429': + $ref: '../../v3/responses/429.yaml' + '500': + $ref: '../../v3/responses/500.yaml' + security: + - oauth2: [idn:access-profile:read] +patch: + operationId: patchAccessProfile + tags: + - Access Profiles + summary: Patch a specified Access Profile + description: >- + This API updates an existing Access Profile. The following fields are patchable: + + **name**, **description**, **enabled**, **owner**, **requestable**, + **accessRequestConfig**, **revokeRequestConfig**, **segments**, **entitlements**, **provisioningCriteria** + + A token with API, ORG_ADMIN, SOURCE_ADMIN, or SOURCE_SUBADMIN authority is required to call this API. In addition, a + SOURCE_SUBADMIN may only use this API to patch Access Profiles which are associated with Sources they are able to + administer. + + > The maximum supported length for the description field is 2000 characters. + Longer descriptions will be preserved for existing access profiles, however, any new access profiles as well as any updates to existing descriptions will be limited to 2000 characters. + + + > You can only add or replace **entitlements** that exist on the source that the access profile is attached to. + You can use the **list entitlements** endpoint with the **filters** query parameter to get a list of available entitlements on the access profile's source. + + + > Patching the value of the **requestable** field is only supported for customers enabled with the new Request + Center. Otherwise, attempting to modify this field results in a 400 error. + parameters: + - name: id + in: path + description: ID of the Access Profile to patch + required: true + schema: + type: string + example: 2c91808a7813090a017814121919ecca + requestBody: + content: + application/json-patch+json: + schema: + type: array + items: + $ref: '../schemas/JsonPatchOperation.yaml' + examples: + Add Entitlements: + description: Add one or more entitlements to the end of the list + value: + - op: add + path: /entitlements + value: + - id: 2c9180857725c14301772a93bb77242d + type: ENTITLEMENT + name: AD User Group + Insert Entitlement: + description: Add an entitlement at the beginning of the entitlement list + value: + - op: add + path: /entitlements/0 + value: + id: 2c9180857725c14301772a93bb77242d + type: ENTITLEMENT + name: AD User Group + Replace Entitlements: + description: Replace all entitlements with a new list of entitlements + value: + - op: replace + path: /entitlements + value: + - id: 2c9180857725c14301772a93bb77242d + type: ENTITLEMENT + name: AD User Group + Remove Entitlement: + description: Remove the first entitlement in the list + value: + - op: remove + path: /entitlements/0 + required: true + responses: + '200': + description: Responds with the Access Profile as updated. + content: + application/json: + schema: + $ref: '../../v3/schemas/access/AccessProfile.yaml' + '400': + $ref: '../../v3/responses/400.yaml' + '401': + $ref: '../../v3/responses/401.yaml' + '403': + $ref: '../../v3/responses/403.yaml' + '429': + $ref: '../../v3/responses/429.yaml' + '500': + $ref: '../../v3/responses/500.yaml' + security: + - oauth2: [idn:access-profile:manage] + + diff --git a/idn/v3/paths/access-profiles.yaml b/idn/v3/paths/access-profiles.yaml new file mode 100644 index 0000000..f56b294 --- /dev/null +++ b/idn/v3/paths/access-profiles.yaml @@ -0,0 +1,153 @@ +get: + operationId: listAccessProfiles + tags: + - Access Profiles + summary: List Access Profiles + description: >- + This API returns a list of Access Profiles. + + + A token with API, ORG_ADMIN, ROLE_ADMIN, ROLE_SUBADMIN, SOURCE_ADMIN, or SOURCE_SUBADMIN authority is required to + call this API. + parameters: + - in: query + name: for-subadmin + schema: + type: string + description: >- + If provided, filters the returned list according to what is visible to the indicated ROLE_SUBADMIN or + SOURCE_SUBADMIN Identity. The value of the parameter is either an Identity ID, or the special value **me**, + which is shorthand for the calling Identity's ID. + + + A 400 Bad Request error is returned if the **for-subadmin** parameter is specified for an Identity that is not + a subadmin. + example: 8c190e6787aa4ed9a90bd9d5344523fb + required: false + - $ref: '../../v3/parameters/limit50.yaml' + - $ref: '../../v3/parameters/offset.yaml' + - $ref: '../../v3/parameters/count.yaml' + - in: query + name: filters + schema: + type: string + description: >- + Filter results using the standard syntax described in [V3 API Standard Collection Parameters](https://developer.sailpoint.com/idn/api/standard-collection-parameters#filtering-results) + + + Filtering is supported for the following fields and operators: + + + **id**: *eq, in* + + + **name**: *eq, sw* + + + **created, modified**: *gt, lt, ge, le* + + + **owner.id**: *eq, in* + + + **requestable**: *eq* + + + **source.id**: *eq, in* + example: name eq "SailPoint Support" + required: false + - in: query + name: sorters + schema: + type: string + format: comma-separated + description: >- + Sort results using the standard syntax described in [V3 API Standard Collection Parameters](https://developer.sailpoint.com/idn/api/standard-collection-parameters#sorting-results) + + + Sorting is supported for the following fields: **name, created, modified** + example: name,-modified + required: false + - in: query + name: for-segment-ids + schema: + type: string + format: comma-separated + description: >- + If present and not empty, additionally filters Access Profiles to those which are assigned to the Segment(s) + with the specified IDs. + + + If segmentation is currently unavailable, specifying this parameter results in an error. + example: 0b5c9f25-83c6-4762-9073-e38f7bb2ae26,2e8d8180-24bc-4d21-91c6-7affdb473b0d + required: false + - in: query + name: include-unsegmented + schema: + type: boolean + default: true + description: >- + Whether or not the response list should contain unsegmented Access Profiles. + If *for-segment-ids* is absent or empty, specifying *include-unsegmented* as false results in an error. + example: false + required: false + responses: + '200': + description: List of Access Profiles + content: + application/json: + schema: + type: array + items: + $ref: '../../v3/schemas/access/AccessProfile.yaml' + '400': + $ref: '../../v3/responses/400.yaml' + '401': + $ref: '../../v3/responses/401.yaml' + '403': + $ref: '../../v3/responses/403.yaml' + '429': + $ref: '../../v3/responses/429.yaml' + '500': + $ref: '../../v3/responses/500.yaml' + security: + - oauth2: [idn:access-profile:read] +post: + operationId: createAccessProfile + tags: + - Access Profiles + summary: Create an Access Profile + description: >- + This API creates an Access Profile. + + A token with API, ORG_ADMIN, ROLE_ADMIN, ROLE_SUBADMIN, SOURCE_ADMIN, or SOURCE_SUBADMIN authority is required to + call this API. In addition, a token with only ROLE_SUBADMIN or SOURCE_SUBADMIN authority must be associated with the + Access Profile's Source. + + The maximum supported length for the description field is 2000 characters. + Longer descriptions will be preserved for existing access profiles, however, any new access profiles as well as any updates to existing descriptions will be limited to 2000 characters. + requestBody: + required: true + content: + application/json: + schema: + $ref: '../../v3/schemas/access/AccessProfile.yaml' + responses: + '201': + description: Access Profile created + content: + application/json: + schema: + $ref: '../../v3/schemas/access/AccessProfile.yaml' + '400': + $ref: '../../v3/responses/400.yaml' + '401': + $ref: '../../v3/responses/401.yaml' + '403': + $ref: '../../v3/responses/403.yaml' + '429': + $ref: '../../v3/responses/429.yaml' + '500': + $ref: '../../v3/responses/500.yaml' + security: + - oauth2: [idn:access-profile:manage] diff --git a/idn/v3/paths/role-assigned-identities.yaml b/idn/v3/paths/role-assigned-identities.yaml new file mode 100644 index 0000000..6382592 --- /dev/null +++ b/idn/v3/paths/role-assigned-identities.yaml @@ -0,0 +1,72 @@ +get: + operationId: getRoleAssignedIdentities + tags: + - Roles + summary: List Identities assigned a Role + parameters: + - in: path + name: id + schema: + type: string + description: >- + ID of the Role for which the assigned Identities are to be listed + example: 2c91808a7813090a017814121e121518 + required: true + - $ref: '../../v3/parameters/limit.yaml' + - $ref: '../../v3/parameters/offset.yaml' + - $ref: '../../v3/parameters/count.yaml' + - in: query + name: filters + schema: + type: string + description: >- + Filter results using the standard syntax described in [V3 API Standard Collection Parameters](https://developer.sailpoint.com/idn/api/standard-collection-parameters#filtering-results) + + + Filtering is supported for the following fields and operators: + + + **id**: *eq, in* + + + **aliasName**: *eq, sw* + + + **email**: *eq, sw* + + + **name**: *eq, sw, co* + example: name sw Joe + - in: query + name: sorters + schema: + type: string + format: comma-separated + description: >- + Sort results using the standard syntax described in [V3 API Standard Collection Parameters](https://developer.sailpoint.com/idn/api/standard-collection-parameters#sorting-results) + + + Sorting is supported for the following fields: **id**, **name**, **aliasName**, **email** + example: aliasName,name + responses: + '200': + description: List of Identities assigned the Role + content: + application/json: + schema: + type: array + items: + $ref: '../../v3/schemas/access/RoleIdentity.yaml' + '400': + $ref: '../../v3/responses/400.yaml' + '401': + $ref: '../../v3/responses/401.yaml' + '403': + $ref: '../../v3/responses/403.yaml' + '429': + $ref: '../../v3/responses/429.yaml' + '500': + $ref: '../../v3/responses/500.yaml' + security: + - oauth2: [idn:role:read,idn:role-checked:read] + diff --git a/idn/v3/paths/role.yaml b/idn/v3/paths/role.yaml new file mode 100644 index 0000000..aa38b70 --- /dev/null +++ b/idn/v3/paths/role.yaml @@ -0,0 +1,195 @@ +get: + operationId: getRole + tags: + - Roles + summary: Get a Role + description: >- + This API returns a Role by its ID. + + + A token with API, ORG_ADMIN, ROLE_ADMIN, or ROLE_SUBADMIN authority is required to call this API. In addition, a + token with ROLE_SUBADMIN authority may only call this API if all Access Profiles included in the Role are associated + to Sources with management workgroups of which the ROLE_SUBADMIN is a member. + parameters: + - in: path + name: id + required: true + schema: + type: string + description: >- + ID of the Role + example: 2c91808a7813090a017814121e121518 + responses: + '200': + description: List of all Roles + content: + application/json: + schema: + $ref: '../../v3/schemas/access/Role.yaml' + '400': + $ref: '../../v3/responses/400.yaml' + '401': + $ref: '../../v3/responses/401.yaml' + '403': + $ref: '../../v3/responses/403.yaml' + '429': + $ref: '../../v3/responses/429.yaml' + '500': + $ref: '../../v3/responses/500.yaml' + security: + - oauth2: [idn:role:read,idn:role-checked:read] +patch: + operationId: patchRole + tags: + - Roles + summary: Patch a specified Role + description: >- + This API updates an existing Role using [JSON Patch](https://tools.ietf.org/html/rfc6902) syntax. + + + The following fields are patchable: + **name**, **description**, **enabled**, **owner**, **accessProfiles**, **membership**, **requestable**, + **accessRequestConfig**, **revokeRequestConfig**, **segments** + + A token with API, ORG_ADMIN, ROLE_ADMIN, or ROLE_SUBADMIN authority is required to call this API. In addition, a + token with ROLE_SUBADMIN authority may only call this API if all Access Profiles included in the Role are associated + to Sources with management workgroups of which the ROLE_SUBADMIN is a member. + + The maximum supported length for the description field is 2000 characters. + Longer descriptions will be preserved for existing roles, however, any new roles as well as any updates to existing descriptions will be limited to 2000 characters. + parameters: + - name: id + in: path + description: ID of the Role to patch + required: true + schema: + type: string + example: 2c91808a7813090a017814121e121518 + requestBody: + content: + application/json-patch+json: + schema: + type: array + items: + $ref: '../schemas/JsonPatchOperation.yaml' + examples: + Make a Role Requestable and Enable it in One Call: + description: This example shows how multiple fields may be updated with a single patch call. + value: + [ + { + "op": "replace", + "path": "/requestable", + "value": true + }, + { + "op": "replace", + "path": "/enabled", + "value": true + } + ] + + Assign a Role to a Segment: + description: >- + This example illustrates the use of patch to assign a Role to a Segment by adding the Segment's ID to the + Role's segments array. + value: + [ + { + "op": "add", + "path": "/segments/-", + "value": "f7b1b8a3-5fed-4fd4-ad29-82014e137e19" + } + ] + + Set the Membership Selection Criteria to a List of Identities: + description: >- + This example shows how to define a Role's membershp by providing a list of Identities, referenced by their + IDs. + value: + [ + { + "op": "replace", + "path": "/membership", + "value": { + "type": "IDENTITY_LIST", + "identities": [ + { + "id": "2c91808973fe906c0174262092014ed9" + }, + { + "id": "2c918086262092014ed94fb8a47612f3" + } + ] + } + } + ] + + Set the Membership Selection Criteria to a Standard Expression: + description: >- + This example shows how to define a Role's membership using STANDARD criteria. In this case, the Role + will be granted to all Identities which have the *Engineering* attribute from the indicated Source. + value: + [ + { + "op": "replace", + "path": "/membership", + "value": { + "type": "STANDARD", + "criteria": { + "operation": "OR", + "children": [ + { + "operation": "EQUALS", + "key": { + "type": "ENTITLEMENT", + "property": "attribute.memberOf", + "sourceId": "2c9180887701fb2014213e122092014e" + }, + "stringValue": "Engineering" + } + ] + } + } + } + ] + + Add a New Clause as the Child of an Existing Standard Expression: + description: >- + This example shows how to add a child clause to an existing STANDARD criteria expression. + value: + [ + { + "op": "add", + "path": "/membership/criteria/children/-", + "value": { + "operation": "ENDS_WITH", + "key": { + "type": "IDENTITY", + "property": "attribute.email" + }, + "stringValue": "@identitynow.com" + } + } + ] + + required: true + responses: + '200': + description: Responds with the Role as updated. + content: + application/json: + schema: + $ref: '../../v3/schemas/access/Role.yaml' + '400': + $ref: '../../v3/responses/400.yaml' + '401': + $ref: '../../v3/responses/401.yaml' + '403': + $ref: '../../v3/responses/403.yaml' + '429': + $ref: '../../v3/responses/429.yaml' + '500': + $ref: '../../v3/responses/500.yaml' + security: + - oauth2: [idn:role:update,idn:role-checked:update] diff --git a/idn/v3/paths/roles.yaml b/idn/v3/paths/roles.yaml new file mode 100644 index 0000000..0b7ad23 --- /dev/null +++ b/idn/v3/paths/roles.yaml @@ -0,0 +1,139 @@ +get: + operationId: listRoles + tags: + - Roles + summary: List Roles + description: >- + This API returns a list of Roles. + + + A token with API, ORG_ADMIN, ROLE_ADMIN, or ROLE_SUBADMIN authority is required to + call this API. + parameters: + - in: query + name: for-subadmin + schema: + type: string + description: >- + If provided, filters the returned list according to what is visible to the indicated ROLE_SUBADMIN Identity. + The value of the parameter is either an Identity ID, or the special value **me**, + which is shorthand for the calling Identity's ID. + A 400 Bad Request error is returned if the **for-subadmin** parameter is specified for an Identity that is not + a subadmin. + example: 5168015d32f890ca15812c9180835d2e + required: false + - $ref: '../../v3/parameters/limit50.yaml' + - $ref: '../../v3/parameters/offset.yaml' + - $ref: '../../v3/parameters/count.yaml' + - in: query + name: filters + schema: + type: string + description: >- + Filter results using the standard syntax described in [V3 API Standard Collection Parameters](https://developer.sailpoint.com/idn/api/standard-collection-parameters#filtering-results) + Filtering is supported for the following fields and operators: + + **id**: *eq, in* + **name**: *eq, sw* + **created, modified**: *gt, lt, ge, le* + **owner.id**: *eq, in* + **requestable**: *eq* + example: requestable eq false + required: false + - in: query + name: sorters + schema: + type: string + format: comma-separated + description: >- + Sort results using the standard syntax described in [V3 API Standard Collection Parameters](https://developer.sailpoint.com/idn/api/standard-collection-parameters#sorting-results) + Sorting is supported for the following fields: **name, created, modified** + + example: name,-modified + required: false + - in: query + name: for-segment-ids + schema: + type: string + format: comma-separated + description: >- + If present and not empty, additionally filters Roles to those which are assigned to the Segment(s) + with the specified IDs. + + + If segmentation is currently unavailable, specifying this parameter results in an error. + + example: 0b5c9f25-83c6-4762-9073-e38f7bb2ae26,2e8d8180-24bc-4d21-91c6-7affdb473b0d + required: false + - in: query + name: include-unsegmented + schema: + type: boolean + default: true + description: >- + Whether or not the response list should contain unsegmented Roles. + If *for-segment-ids* is absent or empty, specifying *include-unsegmented* as false results in an error. + example: false + required: false + responses: + '200': + description: List of Roles + content: + application/json: + schema: + type: array + items: + $ref: '../../v3/schemas/access/Role.yaml' + '400': + $ref: '../../v3/responses/400.yaml' + '401': + $ref: '../../v3/responses/401.yaml' + '403': + $ref: '../../v3/responses/403.yaml' + '429': + $ref: '../../v3/responses/429.yaml' + '500': + $ref: '../../v3/responses/500.yaml' + security: + - oauth2: [idn:role:read,idn:role-checked:read] +post: + operationId: createRole + tags: + - Roles + summary: Create a Role + description: >- + This API creates a Role. + + There is a soft limit of 800 roles per org in IdentityNow. You will receive an error if you attempt to add more than 800 roles via the API or the UI. If you need to add roles above this limit, please create a support ticket. + + A token with API, ORG_ADMIN, ROLE_ADMIN, or ROLE_SUBADMIN authority is required to + call this API. In addition, a ROLE_SUBADMIN may not create a Role including an Access Profile if that Access Profile + is associated with a Source with which the ROLE_SUBADMIN is not themselves associated. + + The maximum supported length for the description field is 2000 characters. + Longer descriptions will be preserved for existing roles, however, any new roles as well as any updates to existing descriptions will be limited to 2000 characters. + requestBody: + required: true + content: + application/json: + schema: + $ref: '../../v3/schemas/access/Role.yaml' + responses: + '201': + description: Role created + content: + application/json: + schema: + $ref: '../../v3/schemas/access/Role.yaml' + '400': + $ref: '../../v3/responses/400.yaml' + '401': + $ref: '../../v3/responses/401.yaml' + '403': + $ref: '../../v3/responses/403.yaml' + '429': + $ref: '../../v3/responses/429.yaml' + '500': + $ref: '../../v3/responses/500.yaml' + security: + - oauth2: [idn:role:create,idn:role-checked:create] diff --git a/idn/v3/schemas/Entitlement.yaml b/idn/v3/schemas/Entitlement.yaml new file mode 100644 index 0000000..954f3be --- /dev/null +++ b/idn/v3/schemas/Entitlement.yaml @@ -0,0 +1,78 @@ +type: object +properties: + id: + type: string + description: The entitlement id + example: "2c91808874ff91550175097daaec161c" + name: + type: string + description: The entitlement name + example: "LauncherTestGroup2" + attribute: + type: string + description: The entitlement attribute name + example: "memberOf" + value: + type: string + description: The value of the entitlement + example: "CN=LauncherTestGroup2,OU=LauncherTestOrg,OU=slpt-automation,DC=TestAutomationAD,DC=local" + sourceSchemaObjectType: + type: string + description: The object type of the entitlement from the source schema + example: "group" + description: + type: string + description: The description of the entitlement + example: "CN=LauncherTestGroup2,OU=LauncherTestOrg,OU=slpt-automation,DC=TestAutomationAD,DC=local" + privileged: + type: boolean + description: True if the entitlement is privileged + example: true + cloudGoverned: + type: boolean + description: True if the entitlement is cloud governed + example: true + created: + type: string + description: Time when the entitlement was created + format: 'date-time' + example: "2020-10-08T18:33:52.029Z" + modified: + type: string + description: Time when the entitlement was last modified + format: 'date-time' + example: "2020-10-08T18:33:52.029Z" + source: + type: object + properties: + id: + type: string + description: The source ID + example: 2c9180827ca885d7017ca8ce28a000eb + type: + type: string + description: The source type, will always be "SOURCE" + example: SOURCE + name: + type: string + description: The source name + example: ODS-AD-Source + attributes: + type: object + description: A map of free-form key-value pairs from the source system + example: { "fieldName": "fieldValue"} + additionalProperties: true + segments: + type: array + items: + type: string + nullable: true + description: List of IDs of segments, if any, to which this Entitlement is assigned. + example: [ + "f7b1b8a3-5fed-4fd4-ad29-82014e137e19", + "29cb6c06-1da8-43ea-8be4-b3125f248f2a" + ] + directPermissions: + type: array + items: + $ref: './PermissionDto.yaml' \ No newline at end of file diff --git a/idn/v3/schemas/PermissionDto.yaml b/idn/v3/schemas/PermissionDto.yaml new file mode 100644 index 0000000..25eb8b8 --- /dev/null +++ b/idn/v3/schemas/PermissionDto.yaml @@ -0,0 +1,16 @@ +type: object +description: Simplified DTO for the Permission objects stored in SailPoint's database. The data is aggregated from + customer systems and is free-form, so its appearance can vary largely between different clients/customers. +properties: + rights: + type: array + description: All the rights (e.g. actions) that this permission allows on the target + readOnly: true + items: + type: string + example: SELECT + target: + type: string + description: The target the permission would grants rights on. + readOnly: true + example: SYS.GV_$TRANSACTION