Merge branch 'main' into fix/ambassadorsLink

This commit is contained in:
darrell-thobe-sp
2024-03-05 15:06:14 -05:00
455 changed files with 5299 additions and 1263 deletions

44
.github/bot.yml vendored
View File

@@ -2,42 +2,46 @@
# Enable "labeler" for your PR that would add labels to PRs based on the paths that are modified in the PR.
labelPRBasedOnFilePath:
Images:
- products/**/*.png
- products/**/*.svg
- products/**/*.jpg
- products/**/*.jpeg
- docs/**/*.png
- docs/**/*.svg
- docs/**/*.jpg
- docs/**/*.jpeg
Docs:
- products/**/*.md*
- docs/**/*.md*
Tools:
- products/idn/docs/identity-now/tools/**/*
- docs/tools/**/*
CLI Docs:
- products/idn/docs/identity-now/tools/cli/**/*
- docs/tools/cli/**/*
SDK Docs:
- products/idn/docs/identity-now/tools/sdk/**/*
- docs/tools/sdk/**/*
Rule Development Kit Docs:
- products/idn/docs/identity-now/tools/rule-development-kit/**/*
- docs/tools/rule-development-kit/**/*
IdentityNow:
- products/idn/**/*
- docs/extensibility/**/*
- docs/connectivity/**/*
- docs/api/**/*
- docs/guides/**/*
- docs/reporting/**/*
NERM:
- products/nerm/**/*
- docs/nerm/**/*
IdentityIQ:
- products/iiq/**/*
- docs/iiq/**/*
Event Trigger Docs:
- products/idn/docs/identity-now/event-triggers/**/*
- docs/extensibility/event-triggers/**/*
SaaS Connectivity Docs:
- products/idn/docs/identity-now/saas-connectivity/**/*
- docs/connectivity/saas-connectivity/**/*
Secure Data Share (SDS):
- products/idn/docs/identity-now/secure-data-share/**/*
- docs/reporting/secure-data-share/**/*
Access Intelligence Center (AIC):
- products/idn/docs/identity-now/access-intelligence-center/**/*
- docs/reporting/access-intelligence-center/**/*
Transform Docs:
- products/idn/docs/identity-now/transforms/**/*
- docs/extensibility/transforms/**/*
Rules Docs:
- products/idn/docs/identity-now/rules/**/*
- docs/extensibility/rules/**/*
SaaS Configuration Docs:
- products/idn/docs/identity-now/saas-configuration.md*
- docs/extensibility/configuration-management/saas-configuration.md*
Introduction Doc:
- products/idn/docs/identity-now/index.md*
- docs/index.md*
Pages:
- src/pages/**/*
Static Files:

View File

@@ -76,6 +76,7 @@ jobs:
- name: Build Developer Community site
run: |
echo "CMS_APP_API_ENDPOINT=$API_GATEWAY_URL" >> .env
echo ${{ secrets.NPM_FONTAWESOME_CONFIG }} | base64 -d >> .npmrc
export NODE_OPTIONS="--max_old_space_size=4096"
npm ci --legacy-peer-deps
npm run gen-api-docs-all

8
.gitignore vendored
View File

@@ -28,6 +28,14 @@ yarn.lock
/products/iiq/api
/products/nerm/api
/docs/api/v3
/docs/api/beta
/docs/api/iiq
/docs/api/nerm/*
!/docs/api/nerm/authentication.md
!/docs/api/nerm/pagination-metadata-filtering.md
!/docs/api/nerm/getting-started.md
#Alogolia env file
/algolia/.env

View File

@@ -2,74 +2,74 @@
"index_name": "prod_DEVELOPER_SAILPOINT_COM",
"start_urls": [
{
"url": "https://developer.sailpoint.com/idn/docs/transforms",
"url": "https://developer.sailpoint.com/docs/extensibility/transforms",
"tags": ["IDN Documentation", "Transforms"]
},
{
"url": "https://developer.sailpoint.com/idn/docs/rules",
"url": "https://developer.sailpoint.com/docs/extensibility/rules",
"tags": ["IDN Documentation", "Rules"]
},
{
"url": "https://developer.sailpoint.com/idn/docs/event-triggers",
"url": "https://developer.sailpoint.com/docs/extensibility/event-triggers",
"tags": ["IDN Documentation", "Event Triggers"]
},
{
"url": "https://developer.sailpoint.com/idn/docs/saas-configuration",
"url": "https://developer.sailpoint.com/docs/extensibility/configuration-management/saas-configuration",
"tags": ["IDN Documentation", "SaaS Configuration"]
},
{
"url": "https://developer.sailpoint.com/idn/docs/saas-connectivity",
"url": "https://developer.sailpoint.com/docs/connectivity/saas-connectivity",
"tags": ["IDN Documentation", "SaaS Connectivity"]
},
{
"url": "https://developer.sailpoint.com/idn/docs/",
"url": "https://developer.sailpoint.com/docs/",
"tags": ["IDN Documentation"]
},
{
"url": "https://developer.sailpoint.com/idn/tools/cli",
"url": "https://developer.sailpoint.com/docs/tools/cli",
"tags": ["IDN Tools", "CLI"],
"selectors_key": "tools"
},
{
"url": "https://developer.sailpoint.com/idn/tools/sdk",
"url": "https://developer.sailpoint.com/docs/tools/sdk",
"tags": ["IDN Tools", "SDKs"],
"selectors_key": "tools"
},
{
"url": "https://developer.sailpoint.com/idn/api/getting-started",
"url": "https://developer.sailpoint.com/docs/api/getting-started",
"selectors_key": "api_v3",
"tags": ["IDN API Documenation"]
},
{
"url": "https://developer.sailpoint.com/idn/api/authentication",
"url": "https://developer.sailpoint.com/docs/api/authentication",
"selectors_key": "api_v3",
"tags": ["IDN API Documenation"]
},
{
"url": "https://developer.sailpoint.com/idn/api/standard-collection-parameters",
"url": "https://developer.sailpoint.com/docs/api/standard-collection-parameters",
"selectors_key": "api_v3",
"tags": ["IDN API Documenation"]
},
{
"url": "https://developer.sailpoint.com/idn/api/rate-limit",
"url": "https://developer.sailpoint.com/docs/api/rate-limit",
"selectors_key": "api_v3",
"tags": ["IDN API Documenation"]
},
{
"url": "https://developer.sailpoint.com/idn/api/v3",
"url": "https://developer.sailpoint.com/docs/api/v3",
"selectors_key": "api_v3",
"tags": ["IDN V3 APIs"]
},
{
"url": "https://developer.sailpoint.com/idn/api/beta",
"url": "https://developer.sailpoint.com/docs/api/beta",
"selectors_key": "api_v3",
"tags": ["IDN Beta APIs"]
},
{
"url": "https://developer.sailpoint.com/iiq/api",
"url": "https://developer.sailpoint.com/docs/api/iiq",
"selectors_key": "api_iiq",
"tags": ["IIQ APIs"]
}

View File

@@ -2,7 +2,7 @@
"index_name": "dev_DEVELOPER_SAILPOINT_COM",
"start_urls": [
{
"url": "https://developer.sailpoint.com/idn/docs/transforms",
"url": "https://developer.sailpoint.com/docs/extensibility/transforms",
"tags": ["IDN Documentation", "Transforms"]
}
],

View File

@@ -1 +0,0 @@
# Developer Relations main

View File

@@ -0,0 +1,31 @@
---
id: api-specifications
title: API Specifications
pagination_label: API Specifications
sidebar_label: API Specifications
sidebar_position: 1
sidebar_class_name: apiSpecifications
keywords: ['api', 'specifications']
description: Identity Security Cloud API specifications.
slug: /api/api-specifications
tags: ['API Specifications']
---
## Overview
The Identity Security Cloud (ISC) APIs provide developers with a way to interact with the ISC platform and extend it. Developers can leverage these APIs to customize their platform experiences and build new solutions and integrations that meet their needs.
The API specifications contain detailed information of how to send requests to each API endpoint, as well as example requests and responses. They also include essential information about how to use the APIs and guides you can follow to get started.
```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
<DocCardList items={useCurrentSidebarCategory().items}/>
```
## Discuss
The most valuable resource for ISC developers is the SailPoint Developer Community itself, where ISC users and experts all over the world come together to ask questions and provide solutions.
To learn more about the ISC APIs and discuss them with SailPoint Developer Community members, go to the [SailPoint Developer Community Forum](https://developer.sailpoint.com/discuss/tags/c/isc/6/apis).

View File

@@ -6,7 +6,7 @@ sidebar_label: Authentication
sidebar_position: 2
sidebar_class_name: authentication
keywords: ['authentication']
description: A guide on how to generate API credentials to authenticate to SailPoint's APIs.
description: Authenticate to the ISC APIs.
slug: /api/authentication
tags: ['Authentication']
---
@@ -15,9 +15,9 @@ import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';
## Overview
With SailPoint's IdentityNow (IDN) APIs, you can extend your IDN platform far beyond its current capabilities.
With SailPoint's Identity Security Cloud (ISC) APIs, you can extend your ISC platform far beyond its current capabilities.
To be able to do so, you must first authenticate to the IDN APIs.
To be able to do so, you must first authenticate to the ISC APIs.
Authentication is the act of validating a user's identity, generally by passing some kind of credentials.
A fast, simple way to authenticate to the APIs is to generate a [personal access token](#generate-a-personal-access-token) and pass that token.
@@ -36,35 +36,35 @@ This diagram shows the flow of this authentication/authorization process:
sequenceDiagram
autonumber
participant H as HTTP Client
participant I as IdentityNow
participant I as Identity Security Cloud
H->>I: Access Token Request
I->>H: Access Token Response
loop Until token expires
H->>I: API Request + Access Token
I->>H: IdentityNow API Response
I->>H: Identity Security Cloud API Response
end
```
</div>
The flow involves these four key steps:
1. **Access Token Request**: The HTTP client (a script, application, Postman, cURL, etc.) makes a request to IDN to get a JWT `access_token`.
2. **Access Token Response**: If the request is valid, IDN responds to the HTTP client with a JWT `access_token`.
3. **API Request**: The HTTP client makes a request to an IDN endpoint with the header, `Authorization: Bearer {access_token}`.
4. **API Response**: If both the request itself and the JWT `access_token` in its header are valid, IDN responds to the client.
1. **Access Token Request**: The HTTP client (a script, application, Postman, cURL, etc.) makes a request to ISC to get a JWT `access_token`.
2. **Access Token Response**: If the request is valid, ISC responds to the HTTP client with a JWT `access_token`.
3. **API Request**: The HTTP client makes a request to an ISC endpoint with the header, `Authorization: Bearer {access_token}`.
4. **API Response**: If both the request itself and the JWT `access_token` in its header are valid, ISC responds to the client.
If you encounter unexpected errors, refer to the [Troubleshooting](#troubleshooting) section of this document.
The idea is that once you have authenticated to the IDN APIs and you have received an `access_token`, you can use that `access_token` to provide authorization for your API requests.
The idea is that once you have authenticated to the ISC APIs and you have received an `access_token`, you can use that `access_token` to provide authorization for your API requests.
This document includes all the information you need to know to engage in this authentication/authorization process, as well as a guide on how to get started.
## Get started
Read this guide to learn how to authenticate to SailPoint's IDN APIs.
Read this guide to learn how to authenticate to SailPoint's ISC APIs.
To authenticate to the IDN APIs, you must be able to connect to your tenant to send the access token request.
To authenticate to the ISC APIs, you must be able to connect to your tenant to send the access token request.
To do so, you need to do the following:
1. [Find your tenant's OAuth details](#find-your-tenant's-oauth-details)
2. [Generate personal access token](#generate-personal-access-token)
@@ -76,13 +76,13 @@ To do so, you need to do the following:
Your tenant's OAuth details refer to the details you need to know to connect it to the APIs.
You need to know your tenant's name, its `authorizeEndpoint` URL, and its `tokenEndpoint` URL.
Your IDN instance is likely using the domain name supplied by SailPoint (`{tenant}.api.identitynow.com`), in which case, the tenant name is in the URL.
Your ISC instance is likely using the domain name supplied by SailPoint (`{tenant}.api.identitynow.com`), in which case, the tenant name is in the URL.
This is assumed to be the case in this guide.
However, if your IDN instance is using a vanity URL, you must enter this URL into your browser to get your OAuth info:
However, if your ISC instance is using a vanity URL, you must enter this URL into your browser to get your OAuth info:
`https://{tenant}.api.identitynow.com/oauth/info`
If you have admin access but don't know your tenant name, you can learn it by following these steps:
1. Log into your IDN instance.
1. Log into your ISC instance.
2. Select the 'Dashboard' dropdown.
3. Select 'Overview'.
4. Find the tenant name ('Org Name') in the dashboard's `Org Details` section.
@@ -109,10 +109,10 @@ A personal access token (PAT) is a method of authenticating to an API as a user
PATs are primarily used in scripts or programs that lack an easy way to implement an OAuth2 flow but need to call API endpoints that require user context.
PATs are also convenient for use in tools like [Postman](https://www.postman.com/) when you are exploring and testing the APIs.
Any IDN user can generate a PAT.
Any ISC user can generate a PAT.
To do so, follow these steps:
1. Select **Preferences** from the drop-down menu under your username, then **Personal Access Tokens** on the left.
You can also go directly to the page by using this URL (replace `{tenant}` with your IdentityNow tenant): `https://{tenant}.identitynow.com/ui/d/user-preferences/personal-access-tokens`
You can also go directly to the page by using this URL (replace `{tenant}` with your Identity Security Cloud tenant): `https://{tenant}.identitynow.com/ui/d/user-preferences/personal-access-tokens`
2. Click **New Token** and enter a meaningful description to help differentiate the token from others.
@@ -133,7 +133,7 @@ After you create the token, the value of the `Client ID` will be visible in the
4. Copy both values somewhere that will be secure and accessible to you when you need to use the the token.
To generate a personal access token from the API, use the [create personal access token endpoint](/idn/api/beta/create-personal-access-token).
To generate a personal access token from the API, use the [create personal access token endpoint](/docs/api/beta/create-personal-access-token).
Once you have created the PAT and you know its `Client ID` and `Client Secret`, you have everything you need to follow the [Client Credentials Grant Flow](#request-access-token-with-client-credentials-grant-flow) and use the PAT to generate an `access_token`.
You will need this `access_token` to authenticate your requests to the APIs.
@@ -145,11 +145,11 @@ You must choose the one that best serves your purposes.
This document covers these three common flows:
1. [**Client Credentials**](https://oauth.net/2/grant-types/client-credentials/) - Clients use this grant type to obtain a JWT `access_token` without user involvement such as scripts, programs or system to system integration.
2. [**Authorization Code**](https://oauth.net/2/grant-types/authorization-code/) - Clients use this grant type to exchange an authorization code for an `access_token`. Authorization codes are mainly used by web applications because there is a login into IDN with a subsequent redirect back to the web application/client.
2. [**Authorization Code**](https://oauth.net/2/grant-types/authorization-code/) - Clients use this grant type to exchange an authorization code for an `access_token`. Authorization codes are mainly used by web applications because there is a login into ISC with a subsequent redirect back to the web application/client.
3. [**Refresh Token**](https://oauth.net/2/grant-types/refresh-token/) - Clients use this grant type to exchange a refresh token for a new `access_token` when the existing `access_token` has expired. This allows clients to continue using the APIs without having to re-authenticate as frequently. This grant type is commonly used together with `Authorization Code` to prevent a user from having to log in several times per day.
One way to determine which authorization flow you need to use is to look at the specification for the endpoint you want to use.
The endpoint will have the supported OAuth flows listed under the 'Authorization' dropdown, like the [List Access Profiles endpoint](https://developer.sailpoint.com/idn/api/beta/list-access-profiles):
The endpoint will have the supported OAuth flows listed under the 'Authorization' dropdown, like the [List Access Profiles endpoint](https://developer.sailpoint.com/docs/api/beta/list-access-profiles):
![Authorization Dropdown](./img/authorization/authorization-dropdown.png)
@@ -161,9 +161,9 @@ The guide will detail the three different authorization grant flows you can use
Clients use the 'Client Credentials' grant type to obtain access tokens without user involvement. This is the simplest authentication flow.
API endpoints that require [user level permissions](https://documentation.sailpoint.com/saas/help/common/users/user_level_matrix.html) require the use of Personal access tokens (PATs). Correspondingly, the endpoints a personal access token (PAT) can call depends on the permissions of the user who generated it and the configuration of IDN.
API endpoints that require [user level permissions](https://documentation.sailpoint.com/saas/help/common/users/user_level_matrix.html) require the use of Personal access tokens (PATs). Correspondingly, the endpoints a personal access token (PAT) can call depends on the permissions of the user who generated it and the configuration of ISC.
Note: If an API Key is used then IDN API calls are made outside of the context of a user and some API calls will not work.
Note: If an API Key is used then ISC API calls are made outside of the context of a user and some API calls will not work.
An OAuth 2.0 client using the client credentials grant flow must have `CLIENT_CREDENTIALS` as one of its grantTypes (PATs are implicitly granted the `CLIENT_CREDENTIALS` grant type):
@@ -184,7 +184,7 @@ An OAuth 2.0 client using the client credentials grant flow must have `CLIENT_CR
This is the overall authorization flow:
1. The client first submits an OAuth 2.0 token request to IDN in this form:
1. The client first submits an OAuth 2.0 token request to ISC in this form:
```text
POST https://{tenant}.api.identitynow.com/oauth/token
@@ -221,7 +221,7 @@ curl --location 'https://{tenant}.api.identitynow.com/oauth/token' \
--form 'client_secret="{clientSecret}"'
```
2. IDN validates the token request and responds.
2. ISC validates the token request and responds.
If the request is successful, the response contains a JWT access token.
For more information about the JWT access token in the response, refer to [#OAuth-token-response](#oauth-token-response).
@@ -234,7 +234,7 @@ To learn more about the OAuth client credentials grant flow, refer [here](https:
Further Reading: [https://oauth.net/2/grant-types/authorization-code/](https://oauth.net/2/grant-types/authorization-code/)
Clients use this grant type to exchange an authorization code for an `access_token`.
This is mainly used for web apps because there is a login into IDN with a subsequent redirect back to the web app/client.
This is mainly used for web apps because there is a login into ISC with a subsequent redirect back to the web app/client.
The OAuth 2.0 client you are using must have `AUTHORIZATION_CODE` as one of its grant types.
The redirect URLs must also match the list in the client as well:
@@ -270,7 +270,7 @@ sequenceDiagram
autonumber
participant U as User
participant W as Web App
participant I as IdentityNow
participant I as Identity Security Cloud
U->>W: Click login link
W->>I: Authorization request to https://{tenant}.login.sailpoint.com/oauth/authorize
@@ -287,19 +287,19 @@ This is the overall authorization flow:
1. The user clicks the login link on a web app.
2. The web app sends an authorization request to IDN in this form:
2. The web app sends an authorization request to ISC in this form:
```Text
GET https://{tenant}.login.sailpoint.com/oauth/authorize?client_id={client-id}&client_secret={client-secret}&response_type=code&redirect_uri={redirect-url}
```
3. IDN redirects the user to a login prompt to authenticate to IdentityNow.
3. ISC redirects the user to a login prompt to authenticate to Identity Security Cloud.
4. The user authenticates to IDN.
4. The user authenticates to ISC.
5. Once authentication is successful, IDN issues an authorization code back to the web app.
5. Once authentication is successful, ISC issues an authorization code back to the web app.
6. The web app submits an OAuth 2.0 token request to IDN in this form:
6. The web app submits an OAuth 2.0 token request to ISC in this form:
```text
POST https://{tenant}.api.identitynow.com/oauth/token?grant_type=authorization_code&client_id={client-id}&client_secret={client-secret}&code={code}&redirect_uri={redirect-url}
@@ -311,7 +311,7 @@ The token endpoint URL is `{tenant}.api.identitynow.com`, and the authorize URL
:::
7. IDN validates the token request and submits a response. If the request is successful, the response contains a JWT `access_token`.
7. ISC validates the token request and submits a response. If the request is successful, the response contains a JWT `access_token`.
For more information about the JWT access token in the response, refer to [#OAuth-token-response](#oauth-token-response).
These are the query parameters in the OAuth 2.0 token request for the authorization code grant:
@@ -363,13 +363,13 @@ This is the overall authorization flow:
1. The client application receives an `access_token` and a `refresh_token` from one of the other OAuth grant flows, like `AUTHORIZATION_CODE`.
2. The client application detects that the `access_token` is about to expire, based on the `expires_in` attribute contained within the JWT token.
3. The client submits an OAuth 2.0 token request to IDN in this form:
3. The client submits an OAuth 2.0 token request to ISC in this form:
```text
POST https://{tenant}.api.identitynow.com/oauth/token?grant_type=refresh_token&client_id={client_id}&client_secret={client_secret}&refresh_token={refresh_token}
```
4. IDN validates the token request and submits a response. If the request is successful, the response contains a new `access_token` and `refresh_token`.
4. ISC validates the token request and submits a response. If the request is successful, the response contains a new `access_token` and `refresh_token`.
These are the query parameters in the OAuth 2.0 token request for the refresh token grant flow:
@@ -417,7 +417,7 @@ A successful request using any of the grant flows to `https://{tenant}.api.ident
}
```
You can use the JWT `access_token` to authorize REST API calls through the IDN API gateway.
You can use the JWT `access_token` to authorize REST API calls through the ISC API gateway.
To use the `access_token`, simply include it in the `Authorization` header as a `Bearer` token.
This is an example V3 API request that has the access token in the header:
@@ -440,7 +440,7 @@ However, the `refresh_token` will only be present if the API client has the `REF
- The `user_id` and `identity_id` define the identity context of the person who authenticated.
However, these values aren't set for the client credentials grant type because it doesn't have a user context.
With the JWT `access_token`, you can now successfully send authenticated IDN API requests. To learn more about authorization and the scopes you can apply to further control access to the APIs, refer to [Authorization](/idn/api/authorization).
With the JWT `access_token`, you can now successfully send authenticated ISC API requests. To learn more about authorization and the scopes you can apply to further control access to the APIs, refer to [Authorization](/docs/api/authorization).
## More Information
@@ -522,25 +522,25 @@ This section describes some different use cases and which grant flow you would w
For daily work or short, quick administrative actions, you can just use a PAT. This makes the process easier because you don't really need to worry about grant types - you can easily generate a PAT in the user interface (UI).
Follow these steps to do so:
1. Log in to IDN.
1. Log in to ISC.
2. Go to 'Preferences', then 'Personal Access Tokens', and [generate a PAT](#generate-a-personal-access-token).
3. The PAT's `client_id` and `client_secret` provide the necessary authentication to send API requests, without any grant flow.
#### Postman
[Postman](https://www.postman.com/) is a popular HTTP client you can use to design, build, test, and iterate your APIs. Postman users and teams can create public workspaces they can use to make it easy to access their API collections and environments and get started. SailPoint maintains a [public workspace for the IdentityNow API collections](https://www.postman.com/sailpoint/workspace/identitynow). You can use this workspace to access all the IDN API collections and stay up to date.
[Postman](https://www.postman.com/) is a popular HTTP client you can use to design, build, test, and iterate your APIs. Postman users and teams can create public workspaces they can use to make it easy to access their API collections and environments and get started. SailPoint maintains a [public workspace for the Identity Security Cloud API collections](https://www.postman.com/sailpoint/workspace/identitynow). You can use this workspace to access all the ISC API collections and stay up to date.
If you're using Postman, you have some different ways to set up your authorization.
You can just leverage the accessToken as mentioned above, or you can configure Postman to use OAuth 2.0 directly.
For more information about how to do so, refer [here](https://learning.postman.com/docs/sending-requests/authorization/).
#### Web applications
If you are making a web application, the best grant flow to use is the [Authorization Code grant flow](#request-access-token-with-authorization-grant-flow). This will allow users to be directed to IDN to login and then redirected back to the web application through a URL redirect. This also works well with Single Sign-on (SSO), strong authentication, and pass-through authentication mechanisms.
If you are making a web application, the best grant flow to use is the [Authorization Code grant flow](#request-access-token-with-authorization-grant-flow). This will allow users to be directed to ISC to login and then redirected back to the web application through a URL redirect. This also works well with Single Sign-on (SSO), strong authentication, and pass-through authentication mechanisms.
SailPoint doesn't recommend using a password grant flow for web applications because doing so would involve entering IDN credentials in the web application.
SailPoint doesn't recommend using a password grant flow for web applications because doing so would involve entering ISC credentials in the web application.
This flow also doesn't allow you to work with SSO, strong authentication, or pass-through authentication.
#### Scripts, programs or system to system integration
If you are writing scripts, programs or system integrations that leverage the IDN APIs, the OAuth 2.0 grant you should use typically depends on what you're doing and the user context you need to operate under.
If you are writing scripts, programs or system integrations that leverage the ISC APIs, the OAuth 2.0 grant you should use typically depends on what you're doing and the user context you need to operate under.
Because scripts, code, and programs lack an interactive web-interface, it is difficult, but not impossible, to implement a working authorization code grant flow. System to system integrations may require an elevated level of access and utilize a service account to make API calls beyond the privileges of the authenticated user.
@@ -614,7 +614,7 @@ You can also view all of the active clients in the UI by going to `https://{tena
```
4. If you're using an [Authorization Code](#authorization-code-grant-flow) grant flow, verify that the redirect URL(s) for your application match the `redirectUris` value in the client.
You can check this by calling the [List OAuth Clients endpoint](/idn/api/beta/list-oauth-clients).
You can check this by calling the [List OAuth Clients endpoint](/docs/api/beta/list-oauth-clients).
### Verify OAuth calls
Verify that the OAuth call flow is going to the right URLs, with the correct query parameters and data values.

View File

@@ -6,7 +6,7 @@ sidebar_label: Authorization
sidebar_position: 3
sidebar_class_name: authorization
keywords: ['authorization','scope','permission']
description: A guide on how to restrict an API token's level of access.
description: Authorize your ISC API requests.
slug: /api/authorization
tags: ['Authorization','Scopes','Permissions']
---
@@ -23,7 +23,7 @@ Authorization and authentication are two related concepts that help secure APIs.
sequenceDiagram
autonumber
participant H as HTTP Client
participant I as IdentityNow
participant I as Identity Security Cloud
H->>I: Request to delete a source
I->>I: Authenticate access token
@@ -61,7 +61,7 @@ Scopes contain one or more rights, which are low level permissions that grant ac
By default, each PAT has the scope, `sp:scopes:all`, which grants access to all the rights appropriate for the [user level](https://documentation.sailpoint.com/saas/help/common/users/user_level_matrix.html). For example, a user with the **Admin** user level has access to all APIs, so `sp:scopes:all` grants **Admin** users access to all APIs. A user with the **Cert Admin** user level, however, has access to only a subset of APIs necessary to perform their role, most notably the certification APIs, so `sp:scopes:all` grants **Cert Admin** users access to only that subset of APIs.
Alternatively, `sp:scopes:default` is the least privileged scope that only grants access to endpoints that require no authorization at all, such as [list public identities](https://developer.sailpoint.com/idn/api/v3/get-public-identities).
Alternatively, `sp:scopes:default` is the least privileged scope that only grants access to endpoints that require no authorization at all, such as [list public identities](https://developer.sailpoint.com/docs/api/v3/get-public-identities).
Scopes are additive, which means the final right set is the intersection of all the rights granted by the scopes assigned to a PAT, excluding any rights that fall outside of the user level. Each scope added to an PAT builds up the credential's permission set, incrementally increasing access to the API. If a PAT has `sp:scopes:all` granted, then any additional scope is ignored because `sp:scopes:all` already contains the complete set of rights available to the user level.
@@ -76,7 +76,7 @@ If the API requirements for the personal access token exceed the scopes allowed
## Identifying Necessary Authorization for an Endpoint
Each endpoint document specifies how to authorize with the endpoint in the **Authorization** dropdown, which is located on the right side column below the endpoint path. Selecting **Authorization** expands the dropdown menu showing the details of how to authorize with the endpoint. The following image shows the authorization details of the [List Access Profiles](https://developer.sailpoint.com/idn/api/beta/list-access-profiles) endpoint.
Each endpoint document specifies how to authorize with the endpoint in the **Authorization** dropdown, which is located on the right side column below the endpoint path. Selecting **Authorization** expands the dropdown menu showing the details of how to authorize with the endpoint. The following image shows the authorization details of the [List Access Profiles](https://developer.sailpoint.com/docs/api/beta/list-access-profiles) endpoint.
![Authorization Dropdown](./img/authorization/authorization-dropdown.png)
@@ -98,7 +98,7 @@ When you create a PAT in the UI, you can apply scopes to the token. More informa
## Assigning Scopes with the API
You can [create PATs](https://developer.sailpoint.com/idn/api/v3/create-personal-access-token) programmatically with the API. The request body for the endpoint allows the caller to specify a list of scopes to be applied to the PAT. If the `scope` property is omitted from the request body, then `sp:scopes:all` is granted to the credentials. The following example shows how to generate a PAT with the `idn:access-request:manage` and `idn:nelm:manage` scopes.
You can [create PATs](https://developer.sailpoint.com/docs/api/v3/create-personal-access-token) programmatically with the API. The request body for the endpoint allows the caller to specify a list of scopes to be applied to the PAT. If the `scope` property is omitted from the request body, then `sp:scopes:all` is granted to the credentials. The following example shows how to generate a PAT with the `idn:access-request:manage` and `idn:nelm:manage` scopes.
POST <https://{tenant}.api.identitynow.com/v3/personal-access-tokens>

View File

@@ -6,14 +6,14 @@ sidebar_label: Getting Started
sidebar_position: 1
sidebar_class_name: gettingStarted
keywords: ['getting started']
description: This is this place to get started with IdentityNow APIs.
description: Start using the ISC APIs.
slug: /api/getting-started
tags: ['Getting Started']
---
## Overview
This guide is intended to help you quickly make your first API call to SailPoint IdentityNow and assumes an intermediate level of understanding of APIs. For beginners to APIs, we recommend you watch this presentation that covers the fundamentals of APIs with visual demonstrations of how to make an API call in SailPoint.
This guide is intended to help you quickly make your first API call to SailPoint Identity Security Cloud and assumes an intermediate level of understanding of APIs. For beginners to APIs, we recommend you watch this presentation that covers the fundamentals of APIs with visual demonstrations of how to make an API call in SailPoint.
<div class="text--center">
<iframe width="560" height="315" src="https://www.youtube.com/embed/YFRz8AcdWXg?si=9AvO6gMT1oCqYXAj" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
@@ -21,13 +21,13 @@ This guide is intended to help you quickly make your first API call to SailPoint
## Find Your Tenant Name
To form the proper URL for an API request, you must know your tenant name. To find your tenant name, log into IdentityNow, navigate to Admin, select the Dashboard dropdown, and select Overview. The org name is displayed within the Org Details section of the dashboard. If you do not have admin access, you can still find your tenant name and the API base URL you will use for API calls. To do so, view your session details when you are logged into your IdentityNow instance. Change your URL to the following: `https://{your-IdentityNow-hostname}.com/ui/session`, where `{your-IdentityNow-hostname}` is your company's domain name for accessing IdentityNow. The session detail you want is the `baseUrl`, which has the form of `https://{tenant}.api.identitynow.com`.
To form the proper URL for an API request, you must know your tenant name. To find your tenant name, log into Identity Security Cloud, navigate to Admin, select the Dashboard dropdown, and select Overview. The org name is displayed within the Org Details section of the dashboard. If you do not have admin access, you can still find your tenant name and the API base URL you will use for API calls. To do so, view your session details when you are logged into your Identity Security Cloud instance. Change your URL to the following: `https://{your-Identity Security Cloud-hostname}.com/ui/session`, where `{your-Identity Security Cloud-hostname}` is your company's domain name for accessing Identity Security Cloud. The session detail you want is the `baseUrl`, which has the form of `https://{tenant}.api.identitynow.com`.
## Make Your First API Call
To get started, create a [personal access token](./authentication.md#personal-access-tokens), which can then be used to generate access tokens to authenticate your API calls. To generate a personal access token from IdentityNow, after logging into your IdentityNow instance, do the following:
To get started, create a [personal access token](./authentication.md#personal-access-tokens), which can then be used to generate access tokens to authenticate your API calls. To generate a personal access token from Identity Security Cloud, after logging into your Identity Security Cloud instance, do the following:
1. Select **Preferences** from the drop-down menu under your username. Then select **Personal Access Tokens** on the left. You can also go straight to the page using this URL, replacing `{tenant}` with your IdentityNow tenant: `https://{tenant}.identitynow.com/ui/d/user-preferences/personal-access-tokens`.
1. Select **Preferences** from the drop-down menu under your username. Then select **Personal Access Tokens** on the left. You can also go straight to the page using this URL, replacing `{tenant}` with your Identity Security Cloud tenant: `https://{tenant}.identitynow.com/ui/d/user-preferences/personal-access-tokens`.
2. Select **New Token** and enter a meaningful description to differentiate the token from others.
@@ -47,13 +47,13 @@ The **New Token** button will be disabled when you reach the limit of 10 persona
4. Copy both values somewhere that will be secure and accessible to you when you need to use the the token.
5. To create an `access_token` that can be used to authenticate API requests, use the following cURL command, replacing `{tenant}` with your IdentityNow tenant. The response body will contain an `access_token`, which will look like a long string of random characters.
5. To create an `access_token` that can be used to authenticate API requests, use the following cURL command, replacing `{tenant}` with your Identity Security Cloud tenant. The response body will contain an `access_token`, which will look like a long string of random characters.
```bash
curl --location --request POST 'https://{tenant}.api.identitynow.com/oauth/token?grant_type=client_credentials&client_id={client_id}&client_secret={secret}'
```
6. To test your `access_token`, execute the following cURL command, replacing `{tenant}` with your IdentityNow tenant and `access_token` with the token you generated in the previous step. If this is successful, you should get a JSON representation of an identity in your tenant.
6. To test your `access_token`, execute the following cURL command, replacing `{tenant}` with your Identity Security Cloud tenant and `access_token` with the token you generated in the previous step. If this is successful, you should get a JSON representation of an identity in your tenant.
```bash
curl --request GET --url 'https://{tenant}.api.identitynow.com/v3/public-identities?limit=1' --header 'authorization: Bearer {access_token}'

View File

@@ -0,0 +1,29 @@
---
id: identity-security-cloud
title: Identity Security Cloud API Specifications
pagination_label: Identity Security Cloud API Specifications
sidebar_label: Identity Security Cloud API Specifications
sidebar_position: 1
sidebar_class_name: iscSpecifications
keywords: ['api', 'specifications']
description: ISC API specifications.
slug: /api
tags: ['API Specifications']
---
## Overview
The Identity Security Cloud (ISC) APIs provide developers with a way to interact with the ISC platform and extend it. Developers can leverage these APIs to customize their platform experiences and build new solutions and integrations that meet their needs.
```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
<DocCardList items={useCurrentSidebarCategory().items}/>
```
## Discuss
The most valuable resource for ISC developers is the SailPoint Developer Community itself, where ISC users and experts all over the world come together to ask questions and provide solutions.
To learn more about the ISC APIs and discuss them with SailPoint Developer Community members, go to the [SailPoint Developer Community Forum](https://developer.sailpoint.com/discuss/tags/c/isc/6/apis).

View File

Before

Width:  |  Height:  |  Size: 91 KiB

After

Width:  |  Height:  |  Size: 91 KiB

View File

Before

Width:  |  Height:  |  Size: 3.3 KiB

After

Width:  |  Height:  |  Size: 3.3 KiB

View File

Before

Width:  |  Height:  |  Size: 48 KiB

After

Width:  |  Height:  |  Size: 48 KiB

View File

Before

Width:  |  Height:  |  Size: 70 KiB

After

Width:  |  Height:  |  Size: 70 KiB

View File

Before

Width:  |  Height:  |  Size: 18 KiB

After

Width:  |  Height:  |  Size: 18 KiB

View File

Before

Width:  |  Height:  |  Size: 92 KiB

After

Width:  |  Height:  |  Size: 92 KiB

View File

@@ -6,8 +6,8 @@ sidebar_label: Authentication
sidebar_position: 2
sidebar_class_name: authentication
keywords: ['authentication']
description: A guide on how to use API credentials to authenticate to NERM APIs.
slug: /api/authentication
description: Authenticate to the NERM APIs.
slug: /api/nerm/authentication
tags: ['Authentication']
---

View File

@@ -6,8 +6,8 @@ sidebar_label: Getting Started
sidebar_position: 1
sidebar_class_name: gettingStarted
keywords: ['getting started']
description: This is this place to get started with NERM APIs.
slug: /api/getting-started
description: Start using the NERM APIs.
slug: /api/nerm/getting-started
tags: ['Getting Started']
---

View File

@@ -6,8 +6,8 @@ sidebar_label: Pagination, Metadata and Filtering
sidebar_position: 3
sidebar_class_name: paginationMetadataFiltering
keywords: ['pagination metadata filtering']
description: Many endpoints in the NERM API support a generic syntax for paginating and filtering, and sorting the results.
slug: /api/pagination-metadata-filtering
description: NERM API pagination, metadata, and filtering.
slug: /api/nerm/pagination-metadata-filtering
tags: ['Pagination Metadata Filtering']
---

31
docs/api/non-employee.md Normal file
View File

@@ -0,0 +1,31 @@
---
id: non-employee
title: NERM API Specifications
pagination_label: NERM API Specifications
sidebar_label: NERM API Specifications
sidebar_position: 1
sidebar_class_name: nermApiSpecifications
keywords: ['api', 'specifications']
description: NERM API specifications.
slug: /api/nerm
tags: ['API Specifications']
---
## Overview
[Non-Employee Risk Management (NERM)](https://documentation.sailpoint.com/ne-admin/help/) is an add-on to Identity Security Cloud (ISC) that helps organizations track non-employees such as contractors, partners, and vendors, and their lifecycles within the organization.
The Non-Employee Risk Management (NERM) APIs provide developers with a way to interact with the NERM add-on and extend it. Developers can leverage these APIs to customize their platform experiences and build new solutions and integrations that meet their needs.
```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
<DocCardList items={useCurrentSidebarCategory().items}/>
```
## Discuss
The most valuable resource for ISC developers is the SailPoint Developer Community itself, where ISC users and experts all over the world come together to ask questions and provide solutions.
To learn more about the NERM APIs and discuss them with SailPoint Developer Community members, go to the [SailPoint Developer Community Forum](https://developer.sailpoint.com/discuss/tag/nerm).

View File

@@ -6,17 +6,17 @@ sidebar_label: Patch Requests
sidebar_position: 8
sidebar_class_name: patchRequests
keywords: ['patch']
description: Read this guide to learn how to send PATCH requests to SailPoint's IdentityNow APIs.
description: Send PATCH ISC API requests.
tags: ['patch', 'guide']
---
## PATCH requests
You can use the IdentityNow APIs to update existing resources. Many of the APIs offer multiple ways to do so:
You can use the Identity Security Cloud APIs to update existing resources. Many of the APIs offer multiple ways to do so:
- You can send a **PUT** request to replace the existing resource with a new one. For example, if you wanted to update one of John Doe's source accounts, you could use the [Put Account](https://developer.sailpoint.com/idn/api/v3/put-account) endpoint to replace John Doe's existing source account with a new one. This is a viable way to update a resource, but it requires you to update the entire resource each time.
- You can send a **PUT** request to replace the existing resource with a new one. For example, if you wanted to update one of John Doe's source accounts, you could use the [Put Account](https://developer.sailpoint.com/docs/api/v3/put-account) endpoint to replace John Doe's existing source account with a new one. This is a viable way to update a resource, but it requires you to update the entire resource each time.
- You can send a **PATCH** request to make a specific change to the resource. For example, if you wanted to update John Doe's account's associated "city" attribute, you could use the [Patch Account](https://developer.sailpoint.com/idn/api/v3/update-account) endpoint to replace his existing "city" with a new one, all without affecting any of the other source account details. This can be very helpful when you want to make specific updates to resources, but it requires some knowledge of the types of changes, or "operations", that are possible, the specific paths of the fields you want to update, and some understanding of the basic data types.
- You can send a **PATCH** request to make a specific change to the resource. For example, if you wanted to update John Doe's account's associated "city" attribute, you could use the [Patch Account](https://developer.sailpoint.com/docs/api/v3/update-account) endpoint to replace his existing "city" with a new one, all without affecting any of the other source account details. This can be very helpful when you want to make specific updates to resources, but it requires some knowledge of the types of changes, or "operations", that are possible, the specific paths of the fields you want to update, and some understanding of the basic data types.
This guide will focus on the partial update method, PATCH requests. Read this guide to learn how to start sending PATCH requests.
@@ -24,17 +24,17 @@ This guide will focus on the partial update method, PATCH requests. Read this gu
To use PATCH to update a resource, you first need to know the resource ID.
Not all resource IDs are available in the IdentityNow UI, so you may need to use the API to find the ID for the resource you want to update.
Not all resource IDs are available in the Identity Security Cloud UI, so you may need to use the API to find the ID for the resource you want to update.
For example, account IDs aren't avilable in the IdentityNow UI. If you want to use the [Patch Account](https://developer.sailpoint.com/idn/api/v3/update-account) endpoint to make a change to a specific account, you first need to find out the account's ID.
For example, account IDs aren't avilable in the Identity Security Cloud UI. If you want to use the [Patch Account](https://developer.sailpoint.com/docs/api/v3/update-account) endpoint to make a change to a specific account, you first need to find out the account's ID.
You can use the [List Accounts](https://developer.sailpoint.com/idn/api/v3/list-accounts) endpoint to view all the accounts in your tenant, along with their details, such as their identities. You can find your account and its ID in this list.
You can use the [List Accounts](https://developer.sailpoint.com/docs/api/v3/list-accounts) endpoint to view all the accounts in your tenant, along with their details, such as their identities. You can find your account and its ID in this list.
## Get the resource details
Once you know the resource ID, you can use a GET request to get that resource's details. To successfully use a PATCH request to make changes to a resource, you need to know which paths you can update, what values they have, and the structure of those paths.
For example, once you know the ID for the source you want to update with a PATCH request, you can use the [Get Source by ID](https://developer.sailpoint.com/idn/api/v3/get-source) endpoint to view only that source and its details.
For example, once you know the ID for the source you want to update with a PATCH request, you can use the [Get Source by ID](https://developer.sailpoint.com/docs/api/v3/get-source) endpoint to view only that source and its details.
In this example, the API returns a source, "ubuntu", along with all its details. This JSON response shows the resource's structure and its different paths:
@@ -181,7 +181,7 @@ PATCH https://{tenant}.api.identitynow.com/v3/sources/:id
This example request uses a "replace" operation to replace the source's existing description with a new value, "new description". This example shows the parts involved in sending a PATCH request. You must specify an operation to apply to the target resource, a path to apply the operation to, and the change you want to make, often in the form of a value or a "from" location for "copy" and "move" operations.
You can find this example in the [Patch Source](https://developer.sailpoint.com/idn/api/v3/update-source) specification. The API specifications have examples on the right side of the page that you can copy and use to get started. You can tab between the different examples to see a variety of pre-built requests you can use.
You can find this example in the [Patch Source](https://developer.sailpoint.com/docs/api/v3/update-source) specification. The API specifications have examples on the right side of the page that you can copy and use to get started. You can tab between the different examples to see a variety of pre-built requests you can use.
A PATCH request can be more complex as well - the values can be simple or vast and detailed. You can use a PATCH request to apply multiple operations, with a path for each, or you can apply the same type of operation to multiple paths. The PATCH request will always have the same essential structure though.
@@ -239,7 +239,7 @@ These are the available PATCH operations:
The "add" operation adds a value to the target location. For more information about the "add" operation and how it behaves in different scenarios, refer to the [JSON PATCH documentation](https://datatracker.ietf.org/doc/html/rfc6902).
This example uses the [Patch Source Schema](https://developer.sailpoint.com/idn/api/v3/update-source-schema) endpoint to add a new "office" attribute to the end of a source schema's array of attributes:
This example uses the [Patch Source Schema](https://developer.sailpoint.com/docs/api/v3/update-source-schema) endpoint to add a new "office" attribute to the end of a source schema's array of attributes:
```json
[
@@ -268,7 +268,7 @@ You can use "0" to add a value to the beginning of the array. You can use "1" to
The "remove" operation removes a value from the target location. The target location must exist for the operation to be successful.
This example uses the [Patch Source](https://developer.sailpoint.com/idn/api/v3/update-source) endpoint to remove an existing filter string from a source's connector:
This example uses the [Patch Source](https://developer.sailpoint.com/docs/api/v3/update-source) endpoint to remove an existing filter string from a source's connector:
```json
[
@@ -285,7 +285,7 @@ This example uses the [Patch Source](https://developer.sailpoint.com/idn/api/v3/
If there is an array of values, you must specify the position within the array to remove that value.
This example uses the [Patch Source](https://developer.sailpoint.com/idn/api/v3/update-source) endpoint to remove the first feature from a source's list of features.
This example uses the [Patch Source](https://developer.sailpoint.com/docs/api/v3/update-source) endpoint to remove the first feature from a source's list of features.
The source has three features, "ENABLE", "PROVISIONING", AND "UNLOCK".
@@ -304,7 +304,7 @@ This request will remove the the first value from the list, "ENABLE".
The "replace" operation replaces the value at the target location with a new value. The operation object must contain a "value" member whose content specifies the replacement value, and the target location must exist for the operation to be successful. This operation is the equivalent of a "remove" followed by an "add".
This example uses the [Patch Source](https://developer.sailpoint.com/idn/api/v3/update-source) endpoint to replace a source's existing features with new ones:
This example uses the [Patch Source](https://developer.sailpoint.com/docs/api/v3/update-source) endpoint to replace a source's existing features with new ones:
```json
[
@@ -322,7 +322,7 @@ This example uses the [Patch Source](https://developer.sailpoint.com/idn/api/v3/
]
```
You can also replace a value within an array. This example uses the [Patch Source](https://developer.sailpoint.com/idn/api/v3/update-source) endpoint to replace the first value in the array with the specified value:
You can also replace a value within an array. This example uses the [Patch Source](https://developer.sailpoint.com/docs/api/v3/update-source) endpoint to replace the first value in the array with the specified value:
```json
[
@@ -340,7 +340,7 @@ This request removes the first feature ("PASSWORD") in the list and adds the "CU
The "move" operation removes the operation from a specified location and adds it to the target location. This operation object must contain a "from" member whose content specifies the location to remove the value from, and the "from" location must exist for the operation to be successful.
This example uses the [Patch Source Schema](https://developer.sailpoint.com/idn/api/v3/update-source-schema) endpoint to move an attribute from the beginning to the end of the schema's array of attributes:
This example uses the [Patch Source Schema](https://developer.sailpoint.com/docs/api/v3/update-source-schema) endpoint to move an attribute from the beginning to the end of the schema's array of attributes:
```json
[
@@ -356,7 +356,7 @@ This example uses the [Patch Source Schema](https://developer.sailpoint.com/idn/
The "copy" operation copies the value from a specified location to the target location. The operation object must contain a "from" member whose content specifies the location to copy the value from, and the "from" location must exist for the operation to be successful.
This example uses the [Patch Source Schema](https://developer.sailpoint.com/idn/api/v3/update-source-schema) endpoint to copies an attribute from the beginning and duplicates it at the end of the schema's array of attributes:
This example uses the [Patch Source Schema](https://developer.sailpoint.com/docs/api/v3/update-source-schema) endpoint to copies an attribute from the beginning and duplicates it at the end of the schema's array of attributes:
```json
[
@@ -374,7 +374,7 @@ The "test" operation is unique in that it does not apply changes to the resource
The "test" operation allows you to check that a resource has the values you expect it to have, and then you can make changes to those values from there with another PATCH request.
This example uses the [Patch Source](https://developer.sailpoint.com/idn/api/v3/update-source) endpoint to test a source's existing features to make sure they match the specified values.:
This example uses the [Patch Source](https://developer.sailpoint.com/docs/api/v3/update-source) endpoint to test a source's existing features to make sure they match the specified values.:
```json
[
@@ -455,7 +455,7 @@ PATCH https://{tenant}.api.identitynow.com/v3/sources/:id
]
```
However, you cannot make changes to all paths. Use the API specifications for the PATCH endpoint you want to use to find out which paths you can make changes to. The API specifications will list the paths, or fields, that are immutable, if there are any. For example, the [Patch Source](https://developer.sailpoint.com/idn/api/v3/update-source) specification lists paths like `id` and `type` as being immutable. Trying to use modify these paths results in a 400 error.
However, you cannot make changes to all paths. Use the API specifications for the PATCH endpoint you want to use to find out which paths you can make changes to. The API specifications will list the paths, or fields, that are immutable, if there are any. For example, the [Patch Source](https://developer.sailpoint.com/docs/api/v3/update-source) specification lists paths like `id` and `type` as being immutable. Trying to use modify these paths results in a 400 error.
The paths are often nested within other paths, like within the "connectorAttributes" path from the earlier example source's details:
@@ -616,7 +616,7 @@ PATCH https://{tenant}.api.identitynow.com//v3/sources/:sourceId/schemas/:schema
]
```
This request uses the [PATCH Source Schema](https://developer.sailpoint.com/idn/api/v3/update-source-schema) endpoint to add a new attribute, along with its details, to the end of the array of a source's schema's attributes.
This request uses the [PATCH Source Schema](https://developer.sailpoint.com/docs/api/v3/update-source-schema) endpoint to add a new attribute, along with its details, to the end of the array of a source's schema's attributes.
This example uses the "-" after the path to indicate that the value will be added to the end of the array. When you are adding a new value to an array of values, you can specify the position within the array where you want to add the new value. In this example, using the "-" expression at the end of the path specifies that the new attribute will be added to the end of the array of attributes.
@@ -626,7 +626,7 @@ You can use "0" to add a value to the beginning of the array. You can use "1" to
The "move" and "copy" operations allow you to remove or copy information from one path and add it to another path without your needing to specify the value, which could be an extensive array of information. To use the "move" and "copy" operations, you must specify a "from", a JSON Pointer representing the location you are moving or copying the value from.
This example request uses the [PATCH Source schema](https://developer.sailpoint.com/idn/api/v3/update-source-schema) endpoint to move an attribute, along with its details, from the beginning to the end of a source schema's array of attributes:
This example request uses the [PATCH Source schema](https://developer.sailpoint.com/docs/api/v3/update-source-schema) endpoint to move an attribute, along with its details, from the beginning to the end of a source schema's array of attributes:
```text
PATCH https://{tenant}.api.identitynow.com//v3/sources/:sourceId/schemas/:schemaId
@@ -660,6 +660,6 @@ When the request is successful, the API will return the updated resource.
## Get started
Now you can use PATCH requests partially update resources. For more information about PATCH requests, refer to this [documentation](https://datatracker.ietf.org/doc/html/rfc6902). For more information about the IdentityNow PATCH endpoints and which paths can be changed for each one, refer to their API specifications.
Now you can use PATCH requests partially update resources. For more information about PATCH requests, refer to this [documentation](https://datatracker.ietf.org/doc/html/rfc6902). For more information about the Identity Security Cloud PATCH endpoints and which paths can be changed for each one, refer to their API specifications.
Use this guide to get started, and if you have questions, don't hesitate to reach out on the SailPoint Developer Community forum at https://developer.sailpoint.com/discuss!

View File

@@ -6,18 +6,18 @@ sidebar_label: Postman Collections
sidebar_position: 7
sidebar_class_name: postmanCollections
keywords: ['postman']
description: How to run the APIs in Postman.
description: Run ISC APIs in Postman.
tags: ['postman']
---
import GitHubPublicFileComponent from '@site/src/components/GitHubLink';
[Postman](https://www.postman.com/) is a platform you can use to design, build, test, and iterate your APIs. Postman users and teams can create public workspaces they can use to make it easy to access their API collections and environments and get started. SailPoint maintains a [public workspace for the IdentityNow API collections](https://www.postman.com/sailpoint/workspace/identitynow). You can use this workspace to access all the IDN API collections and stay up to date.
[Postman](https://www.postman.com/) is a platform you can use to design, build, test, and iterate your APIs. Postman users and teams can create public workspaces they can use to make it easy to access their API collections and environments and get started. SailPoint maintains a [public workspace for the Identity Security Cloud API collections](https://www.postman.com/sailpoint/workspace/identitynow). You can use this workspace to access all the ISC API collections and stay up to date.
## Run in Postman
Each IDN API version is broken out into a separate collection within the workspace. The following table lists the available IDN API collections. To import a collection into your workspace, select the 'Run in Postman' button for your desired version. Doing so forks the collection into your workspace.
Each ISC API version is broken out into a separate collection within the workspace. The following table lists the available ISC API collections. To import a collection into your workspace, select the 'Run in Postman' button for your desired version. Doing so forks the collection into your workspace.
@@ -34,7 +34,7 @@ When you fork the collection, when you check the 'Watch original collection' che
## Update your collections
SailPoint is often making improvements to the IDN API collections. To keep your workspace in sync with updates to one of SailPoint's public collections, you can right click on the forked collection and select "pull changes". sometimes this process will fail because of the size of our collection and limitations of the Postman tool. In that case, in order to update, you will need to visit the [sailpoint workspace](https://www.postman.com/sailpoint/workspace/identitynow) and create a fork of the most recently published version or click the links above to fork the most recent version.
SailPoint is often making improvements to the ISC API collections. To keep your workspace in sync with updates to one of SailPoint's public collections, you can right click on the forked collection and select "pull changes". sometimes this process will fail because of the size of our collection and limitations of the Postman tool. In that case, in order to update, you will need to visit the [sailpoint workspace](https://www.postman.com/sailpoint/workspace/identitynow) and create a fork of the most recently published version or click the links above to fork the most recent version.
## Configure your environment
@@ -47,7 +47,7 @@ To send API requests in Postman, you must authenticate to the APIs. To authentic
| Environment Variable | Required | Description |
| ----------- | ----------- | ----------- |
| tenant | Yes | Your IDN tenant, typically your company's name |
| tenant | Yes | Your ISC tenant, typically your company's name |
| clientId | Yes | The client ID for the API client or personal access token |
| clientSecret | Yes | The client secret for the API client or personal access token |
| domain | No | This optional field is only necessary for those who have a domain in their API URL that isn't "identitynow". |

View File

@@ -6,7 +6,7 @@ sidebar_label: Rate Limiting
sidebar_position: 6
sidebar_class_name: rateLimit
keywords: ['rate limit']
description: There is a rate limit of 100 requests per access_token per 10 seconds for V3 API calls through the API gateway.
description: ISC API rate limits.
tags: ['Rate Limit']
---

View File

@@ -6,11 +6,11 @@ sidebar_label: Standard Collection Parameters
sidebar_position: 5
sidebar_class_name: standardCollectionParameters
keywords: ['standard collection parameters']
description: Many endpoints in the IdentityNow API support a generic syntax for paginating, filtering and sorting the results.
description: ISC API pagination, filtering, and sorting.
tags: ['Standard Collection Parameters']
---
Many endpoints in the IdentityNow API support a generic syntax for paginating, filtering and sorting the results. A collection endpoint has the following characteristics:
Many endpoints in the Identity Security Cloud API support a generic syntax for paginating, filtering and sorting the results. A collection endpoint has the following characteristics:
- The HTTP verb is always GET.
- The last component in the URL is a plural noun (ex. `/v3/public-identities`).
@@ -22,7 +22,7 @@ Use the following optional query parameters to achieve pagination:
| Name | Description | Default | Constraints |
| --- | --- | --- | --- |
| `limit` | Integer specifying the maximum number of records to return in a single API call. If it is not specified, a default limit is used. | `250` for list endpoints, `10000` for search endpoint | Maxiumum of 250 records per page for list endpoints, 10000 records per page for the [Search endpoint](https://developer.sailpoint.com/idn/api/v3/search) |
| `limit` | Integer specifying the maximum number of records to return in a single API call. If it is not specified, a default limit is used. | `250` for list endpoints, `10000` for search endpoint | Maxiumum of 250 records per page for list endpoints, 10000 records per page for the [Search endpoint](https://developer.sailpoint.com/docs/api/v3/search) |
| `offset` | Integer specifying the offset of the first result from the beginning of the collection. The **offset** value is record-based, not page-based, and the index starts at 0. For example, **offset=0** and **limit=20** returns records 0-19, but **offset=1** and **limit=20** returns records 1-20. | `0` | Between 0 and the last record index. |
| `count` | Boolean indicating whether a total count is returned, factoring in any filter parameters, in the **X-Total-Count** response header. The value is the total size of the collection that would be returned if **limit** and **offset** were ignored. For example, if the total number of records is 1000, then count=true would return 1000 in the **X-Total-Count** header. Because requesting a total count can have performance impact, do not send **count=true** if that value is not being used. | `false` | Must be `true` or `false` |
@@ -34,7 +34,7 @@ Examples:
## Paginating Search Queries
The [search API](https://developer.sailpoint.com/idn/api/v3/search) in IdentityNow leverages [Elasticsearch](https://www.elastic.co/guide/en/elasticsearch/reference/current/elasticsearch-intro.html) functionality, which returns a maximum of 10,000 records by default. However, you can page more than 10,000 records by using the "searchAfter" property.
The [search API](https://developer.sailpoint.com/docs/api/v3/search) in Identity Security Cloud leverages [Elasticsearch](https://www.elastic.co/guide/en/elasticsearch/reference/current/elasticsearch-intro.html) functionality, which returns a maximum of 10,000 records by default. However, you can page more than 10,000 records by using the "searchAfter" property.
The `searchAfter` capability provides the ability to page on sorted field values, instead of offset paging. For example, if you sort by ID and page 100 records at a time, you can take the 1st page of 100 records, pass the last ID from that record set into your next search, and the next search will return the next 100 records after that ID. You continue that pattern of using the last value passed into `searchAfter` until the end of the result set. This allows you to page past the 10,000 record limit until you reach the final record.

29
docs/connectivity.md Normal file
View File

@@ -0,0 +1,29 @@
---
id: connectivity
title: Connectivity
pagination_label: Connectivity
sidebar_label: Connectivity
sidebar_position: 1
sidebar_class_name: connectivity
keywords: ['connectivity']
description: Build and expand ISC connectivity.
slug: /connectivity
tags: ['connectivity']
---
## Overview
Connectivity refers to Identity Security Cloud's (ISC) ability to connect to many different [sources](https://documentation.sailpoint.com/saas/help/sources/index.html) of many different types. Organizations can then manage access to the different sources and ensure that the access is secure.
```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
<DocCardList items={useCurrentSidebarCategory().items}/>
```
## Discuss
The most valuable resource for ISC developers is the SailPoint Developer Community itself, where ISC users and experts all over the world come together to ask questions and provide solutions.
To learn more about ISC connectivity and discuss it with SailPoint Developer Community members, go to the [SailPoint Developer Community Forum](https://developer.sailpoint.com/discuss/c/isc/6).

View File

@@ -7,7 +7,7 @@ sidebar_position: 3
sidebar_class_name: commonCliCommands
keywords: ['connectivity', 'connectors', 'commands', 'cli']
description: These are the CLI commands most commonly used when building SaaS Connectors.
slug: /docs/saas-connectivity/common-cli-commands
slug: /connectivity/saas-connectivity/common-cli-commands
tags: ['Connectivity']
---
@@ -18,21 +18,21 @@ Below is a list of commands and their usages:
- Create a customizer on your local system `sail conn customizers init "my-customizer-project"`
- Test your connector or customizer locally: `npm run debug`
- **Deployment**
- Create an empty connector in your IDN Org (used to get id so you can upload): `sail conn create "my-project"`
- Create an empty customizer in your IDN Org (used to get id so you can upload): `sail conn customizers create "my-customizer-project"`
- Create an empty connector in your ISC Org (used to get id so you can upload): `sail conn create "my-project"`
- Create an empty customizer in your ISC Org (used to get id so you can upload): `sail conn customizers create "my-customizer-project"`
- Build a project: `npm run pack-zip`
- Upload your connector to your IDN Org: `sail conn upload -c [connectorID | connectorAlias] -f dist/[connector filename].zip`
- Upload your customizer to your IDN Org: `sail conn customizers upload -c [customizerID] -f dist/[customizer filename].zip`
- Upload your connector to your ISC Org: `sail conn upload -c [connectorID | connectorAlias] -f dist/[connector filename].zip`
- Upload your customizer to your ISC Org: `sail conn customizers upload -c [customizerID] -f dist/[customizer filename].zip`
- **Exploring**
- List connectors in your IDN Org: `sail conn list`
- List customizers in your IDN Org: `sail conn customizers list`
- List source instances in your IDN Org: `sail conn instances list`
- List connectors in your ISC Org: `sail conn list`
- List customizers in your ISC Org: `sail conn customizers list`
- List source instances in your ISC Org: `sail conn instances list`
- List your connector tags: `sail conn tags list -c [connectorID | connectorAlias]`
- **Testing and Debugging**
- Test your connector on the IDN Org: `sail connectors invoke [action] -c [connectorID | connectorAlias] -p config.json`
- Test your connector on the ISC Org: `sail connectors invoke [action] -c [connectorID | connectorAlias] -p config.json`
- Get a list of actions: `sail conn invoke -h`
- Run read-only integration tests against your connector: `sail conn validate -p config.json -c [connectorID | connectorAlias] -r`
- Tail IDN Org connector logs: `sail conn logs tail`
- Tail ISC Org connector logs: `sail conn logs tail`
- **Delete**
- Delete a connector: `sail conn delete -c [connectorID | connectorAlias]`
- **Linking**

View File

@@ -5,7 +5,7 @@ pagination_label: Account Create
sidebar_label: Account Create
keywords: ['connectivity', 'connectors', 'account create']
description: Create account on the source.
slug: /docs/saas-connectivity/commands/account-create
slug: /connectivity/saas-connectivity/commands/account-create
tags: ['Connectivity', 'Connector Command']
---
@@ -57,13 +57,13 @@ tags: ['Connectivity', 'Connector Command']
## Description
The account create command triggers whenever IDN is told to provision entitlements for an identity on the target source, but no account for the identity on the target source exists yet. For example, if you create an access profile that grants a group on the target source and then add that access profile to a role, any identity matching that roles membership criteria will be granted to the group. IDN determines which identities do not have accounts on the target source and triggers the account create command for each identity. If an identity already has an account, then it invokes the account update command.
The account create command triggers whenever ISC is told to provision entitlements for an identity on the target source, but no account for the identity on the target source exists yet. For example, if you create an access profile that grants a group on the target source and then add that access profile to a role, any identity matching that roles membership criteria will be granted to the group. ISC determines which identities do not have accounts on the target source and triggers the account create command for each identity. If an identity already has an account, then it invokes the account update command.
## The Provisioning Plan
The account create command accepts a provisioning plan from IDN and creates the corresponding account(s) in the target source. When you configure your source in IDN, you must set up Create Profile to tell IDN how to provision new accounts for your source.
The account create command accepts a provisioning plan from ISC and creates the corresponding account(s) in the target source. When you configure your source in ISC, you must set up Create Profile to tell ISC how to provision new accounts for your source.
You can create the provisioning plan through the `accountCreateTemplate` in the `connector-spec.json` file, and you can also modify its behavior in IDN using the create profile screen:
You can create the provisioning plan through the `accountCreateTemplate` in the `connector-spec.json` file, and you can also modify its behavior in ISC using the create profile screen:
![Account Create](./img/account_create_idn.png)
@@ -177,7 +177,7 @@ public static createWithStdAccountCreateInput(record: StdAccountCreateInput): Ai
## The return object
When the account is returned to IDN, any values you set are updated in IDN. So if an account ID is auto-generated on the source system, you must send the account ID back to IDN so IDN is aware of it for future account update activities. This is useful for the compound key type.
When the account is returned to ISC, any values you set are updated in ISC. So if an account ID is auto-generated on the source system, you must send the account ID back to ISC so ISC is aware of it for future account update activities. This is useful for the compound key type.
## Password Handling
@@ -224,9 +224,9 @@ async createAccount(input: StdAccountCreateInput): Promise<AirtableAccount> {
}
```
## Testing in IdentityNow
## Testing in Identity Security Cloud
One way to test whether the account create code works in IDN is to set up an access profile and role that grants members an entitlement from the connectors target source. Start by creating an access profile that grants one or more entitlements from the target source.
One way to test whether the account create code works in ISC is to set up an access profile and role that grants members an entitlement from the connectors target source. Start by creating an access profile that grants one or more entitlements from the target source.
![Testing 1](./img/testing1.png)

View File

@@ -5,7 +5,7 @@ pagination_label: Account Delete
sidebar_label: Account Delete
keywords: ['connectivity', 'connectors', 'account delete']
description: Remove account from a source.
slug: /docs/saas-connectivity/commands/account-delete
slug: /connectivity/saas-connectivity/commands/account-delete
tags: ['Connectivity', 'Connector Command']
---
@@ -36,9 +36,9 @@ tags: ['Connectivity', 'Connector Command']
## Description
The account delete command sends one attribute from IDN, the identity to delete. This can be passed to your connector to delete the account from the source system.
The account delete command sends one attribute from ISC, the identity to delete. This can be passed to your connector to delete the account from the source system.
Enable account delete in IDN through a BeforeProvisioning rule. The connector honors whichever operation the provisioning plan sends. For more information, see the [documentation](https://community.sailpoint.com/t5/IdentityNow-Articles/IdentityNow-Rule-Guide/ta-p/76665) and an [example implementation](https://community.sailpoint.com/t5/IdentityNow-Wiki/IdentityNow-Rule-Guide-Before-Provisioning-Rule/ta-p/77415).
Enable account delete in ISC through a BeforeProvisioning rule. The connector honors whichever operation the provisioning plan sends. For more information, see the [documentation](https://community.sailpoint.com/t5/Identity Security Cloud-Articles/Identity Security Cloud-Rule-Guide/ta-p/76665) and an [example implementation](https://community.sailpoint.com/t5/Identity Security Cloud-Wiki/Identity Security Cloud-Rule-Guide-Before-Provisioning-Rule/ta-p/77415).
The following snippet shows an example of account delete command implementation:

View File

@@ -5,7 +5,7 @@ pagination_label: Account Disable
sidebar_label: Account Disable
keywords: ['connectivity', 'connectors', 'account disable']
description: Disable an account on the source.
slug: /docs/saas-connectivity/commands/account-disable
slug: /connectivity/saas-connectivity/commands/account-disable
tags: ['Connectivity', 'Connector Command']
---
@@ -54,7 +54,7 @@ You typically invoke the `account disable` command during the joiner, mover, lea
Disabling accounts is generally preferred if the source supports account disabling so the account data remains for later reactivation or inspection. If the source does not support account disabling, or deleting accounts is preferred when an identity leaves the organization, the connector can perform the necessary steps to delete an account with the account disable function.
> 🚧 It is important to note that although SaaS Connectivity supports the account delete command, IDN never sends the account delete command, only the account disable command. The connectors developer determines the appropriate action for account disable on the source.
> 🚧 It is important to note that although SaaS Connectivity supports the account delete command, ISC never sends the account delete command, only the account disable command. The connectors developer determines the appropriate action for account disable on the source.
Account disable is similar to implementing the account update command. If you have implemented your source call to modify any of the values on your source, then you can use the same method to implement the command. The following code implements disable:

View File

@@ -5,7 +5,7 @@ pagination_label: Account Discover
sidebar_label: Account Discover
keywords: ['connectivity', 'connectors', 'account discover']
description: Dynamically determine account schema from the source.
slug: /docs/saas-connectivity/commands/account-discover
slug: /connectivity/saas-connectivity/commands/account-discover
tags: ['Connectivity', 'Connector Command']
---
@@ -51,7 +51,7 @@ tags: ['Connectivity', 'Connector Command']
## Description
The account discover schema command tells IDN to dynamically create the account schema for the source rather than use the account schema provided by the connector in connector-spec.json. It is often ideal to statically define the account schema because it is generally more performant and easier to develop and reason about the code. However, some sources have schemas that can be different for each customer deployment. It can also be difficult to determine which account attributes to statically expose, which requires the schema to be dynamically generated. SalesForce is an example of a source that can have thousands of account attributes, which makes it impractical to statically define a set of attributes that satisfies all connector users. Although the SalesForce connector defines a standard set of account attributes out of the box, it also allows schema discovery for users looking for more attributes.
The account discover schema command tells ISC to dynamically create the account schema for the source rather than use the account schema provided by the connector in connector-spec.json. It is often ideal to statically define the account schema because it is generally more performant and easier to develop and reason about the code. However, some sources have schemas that can be different for each customer deployment. It can also be difficult to determine which account attributes to statically expose, which requires the schema to be dynamically generated. SalesForce is an example of a source that can have thousands of account attributes, which makes it impractical to statically define a set of attributes that satisfies all connector users. Although the SalesForce connector defines a standard set of account attributes out of the box, it also allows schema discovery for users looking for more attributes.
## Implementation
@@ -229,7 +229,7 @@ export const connector = async () => {
}
```
Next, implement the `discoverSchema()` function in your client code. The following function calls the necessary endpoints to get the full schema of the user account you want to represent in IDN. After you receive a response from your call, you must build your account schema object that will return to IDN. The response has a structure like the accountSchema property in the connector-spec.json file. The following is an example from [airtable.ts](https://github.com/sailpoint-oss/airtable-example-connector/blob/main/src/airtable.ts).
Next, implement the `discoverSchema()` function in your client code. The following function calls the necessary endpoints to get the full schema of the user account you want to represent in ISC. After you receive a response from your call, you must build your account schema object that will return to ISC. The response has a structure like the accountSchema property in the connector-spec.json file. The following is an example from [airtable.ts](https://github.com/sailpoint-oss/airtable-example-connector/blob/main/src/airtable.ts).
```javascript
async getAccountSchema(): Promise<StdAccountDiscoverSchemaOutput> {
@@ -276,7 +276,7 @@ async getAccountSchema(): Promise<StdAccountDiscoverSchemaOutput> {
}
```
This code produces the following payload that will be sent back to IDN.
This code produces the following payload that will be sent back to ISC.
```javascript
{
@@ -343,9 +343,9 @@ This code produces the following payload that will be sent back to IDN.
There are many properties in this payload, so you may want to remove some, but it can be hard to determine which properties to keep in a dynamic way. If you can programmatically determine which properties to remove, you can alter the `discoverSchema()` function to remove them.
## Test in IdentityNow
## Test in Identity Security Cloud
To test the account discover schema command in IDN, ensure that you upload your latest connector code and create a new source in IDN. After you configure and test your source connection, go to the Account Schema page. You will see an empty schema.
To test the account discover schema command in ISC, ensure that you upload your latest connector code and create a new source in ISC. After you configure and test your source connection, go to the Account Schema page. You will see an empty schema.
![Discover Schema 1](./img/discover_schema_idn1.png)
@@ -353,7 +353,7 @@ To discover the schema for this source, click the Options dropdown in the
![Discover Schema 2](./img/discover_schema_idn2.png)
IDN then asks you to assign attributes to Account ID and 'Account Name.'
ISC then asks you to assign attributes to Account ID and 'Account Name.'
![Discover Schema 3](./img/discover_schema_idn3.png)

View File

@@ -5,7 +5,7 @@ pagination_label: Account Enable
sidebar_label: Account Enable
keywords: ['connectivity', 'connectors', 'account enable']
description: Enable an account on the source.
slug: /docs/saas-connectivity/commands/account-enable
slug: /connectivity/saas-connectivity/commands/account-enable
tags: ['Connectivity', 'Connector Command']
---

View File

@@ -4,8 +4,8 @@ title: Account List
pagination_label: Account List
sidebar_label: Account List
keywords: ['connectivity', 'connectors', 'account list']
description: Aggregate all accounts from the source into IdentityNow.
slug: /docs/saas-connectivity/commands/account-list
description: Aggregate all accounts from the source into Identity Security Cloud.
slug: /connectivity/saas-connectivity/commands/account-list
tags: ['Connectivity', 'Connector Command']
---
@@ -47,7 +47,7 @@ tags: ['Connectivity', 'Connector Command']
## Description
The account list command aggregates all accounts from the target source into IdentityNow. IDN calls this command during a manual or scheduled account aggregation.
The account list command aggregates all accounts from the target source into Identity Security Cloud. ISC calls this command during a manual or scheduled account aggregation.
![Account List](./img/account_list_idn.png)
@@ -73,13 +73,13 @@ async getAllAccounts(): Promise<AirtableAccount[]> {
:::caution Important
IDN will throw a connection timeout error if your connector doesn't respond within 3 minutes, and there are memory limitations involved with aggregating data. To prevent large memory utilization or timeout errors, you should set up your connectors to send data to IDN as it's retrieved from your source system. For more details and an example, refer to [Connector Timeouts](../in-depth/connector-timeouts.md).
ISC will throw a connection timeout error if your connector doesn't respond within 3 minutes, and there are memory limitations involved with aggregating data. To prevent large memory utilization or timeout errors, you should set up your connectors to send data to ISC as it's retrieved from your source system. For more details and an example, refer to [Connector Timeouts](../in-depth/connector-timeouts.md).
:::
:::caution Important
IDN supports [delta aggregation](#delta-aggregation-state). If your source has a large number of accounts that will be syncronized with IDN, then it is highly recommended to utilize [delta aggregation](#delta-aggregation-state) for the source.
ISC supports [delta aggregation](#delta-aggregation-state). If your source has a large number of accounts that will be syncronized with ISC, then it is highly recommended to utilize [delta aggregation](#delta-aggregation-state) for the source.
:::
@@ -105,7 +105,7 @@ export const connector = async () => {
...
```
IDN expects each user in the target source to be converted into a format IDN understands. The specific attributes the web service returns depend on what your source provides.
ISC expects each user in the target source to be converted into a format ISC understands. The specific attributes the web service returns depend on what your source provides.
```javascript
public toStdAccountListOutput(): StdAccountListOutput {
@@ -130,7 +130,7 @@ private buildStandardObject(): StdAccountListOutput | StdAccountCreateOutput | S
}
```
The result of the account list command is not an array of objects but several individual objects. This is the format IDN expects, so if you see something like the following result while testing, it is normal:
The result of the account list command is not an array of objects but several individual objects. This is the format ISC expects, so if you see something like the following result while testing, it is normal:
```javascript
{
@@ -193,7 +193,7 @@ If your source can keep track of changes to the data in some way, then delta agg
}
```
2. In the ```stdAccountList``` command, when you are done sending accounts, you need to also send the state to IDN so it knows where to start the next time it sends a list request:
2. In the ```stdAccountList``` command, when you are done sending accounts, you need to also send the state to ISC so it knows where to start the next time it sends a list request:
```javascript
const state = {"data": Date.now().toString()}

View File

@@ -4,8 +4,8 @@ title: Account Read
pagination_label: Account Read
sidebar_label: Account Read
keywords: ['connectivity', 'connectors', 'account read']
description: Aggregate a single account from the source into IdentityNow.
slug: /docs/saas-connectivity/commands/account-read
description: Aggregate a single account from the source into Identity Security Cloud.
slug: /connectivity/saas-connectivity/commands/account-read
tags: ['Connectivity', 'Connector Command']
---
@@ -50,7 +50,7 @@ tags: ['Connectivity', 'Connector Command']
## Description
The account read command aggregates a single account from the target source into IdentityNow. IDN can call this command during a “one-off” account refresh, which you can trigger by aggregating an individual account in IDN.
The account read command aggregates a single account from the target source into Identity Security Cloud. ISC can call this command during a “one-off” account refresh, which you can trigger by aggregating an individual account in ISC.
![Account Read](./img/account_read_idn.png)
@@ -84,7 +84,7 @@ async getAccount(identity: SimpleKeyType | CompoundKeyType): Promise<AirtableAcc
}
```
One special case of this command is the `NotFound` type. On line 20, if an account is not found, the `ConnectorError` is thrown with the `ConnectorErrorType.NotFound` type. This tells IDN the account does not exist, and IDN then triggers the account create logic to generate the account.
One special case of this command is the `NotFound` type. On line 20, if an account is not found, the `ConnectorError` is thrown with the `ConnectorErrorType.NotFound` type. This tells ISC the account does not exist, and ISC then triggers the account create logic to generate the account.
The following code snippet from [index.ts](https://github.com/sailpoint-oss/airtable-example-connector/blob/main/src/index.ts) shows how to register the account read command on the connector object:

View File

@@ -5,7 +5,7 @@ pagination_label: Account Unlock
sidebar_label: Account Unlock
keywords: ['connectivity', 'connectors', 'account unlock']
description: Lock and unlock an account on the source.
slug: /docs/saas-connectivity/commands/account-unlock
slug: /connectivity/saas-connectivity/commands/account-unlock
tags: ['Connectivity', 'Connector Command']
---
@@ -50,7 +50,7 @@ tags: ['Connectivity', 'Connector Command']
## Description
The account lock and account unlock commands provide ways to temporarily prevent access to an account. IDN only supports the unlock command, so accounts must be locked on the source level, but they can be unlocked through IDN, and IDN can store the account's status.
The account lock and account unlock commands provide ways to temporarily prevent access to an account. ISC only supports the unlock command, so accounts must be locked on the source level, but they can be unlocked through ISC, and ISC can store the account's status.
Implementing account unlock is similar to the other commands that update attributes on an account. The following code unlocks an account:

View File

@@ -5,7 +5,7 @@ pagination_label: Account Update
sidebar_label: Account Update
keywords: ['connectivity', 'connectors', 'account update']
description: Update an account on the source.
slug: /docs/saas-connectivity/commands/account-update
slug: /connectivity/saas-connectivity/commands/account-update
tags: ['Connectivity', 'Connector Command']
---
@@ -59,11 +59,11 @@ tags: ['Connectivity', 'Connector Command']
## Description
The account update command triggers whenever IDN is told to modify an identity's attributes or entitlements on the target source. For example, granting an identity a new entitlement through a role, changing an identitys lifecycle state, or modifying an identity attribute tied to an account attribute all trigger the account update command.
The account update command triggers whenever ISC is told to modify an identity's attributes or entitlements on the target source. For example, granting an identity a new entitlement through a role, changing an identitys lifecycle state, or modifying an identity attribute tied to an account attribute all trigger the account update command.
## Input Schema
The payload from IDN contains the ID of the identity to modify, the configuration items the connector needs to call the source API, and one or more change operations to apply to the identity. Each operation has the following special considerations:
The payload from ISC contains the ID of the identity to modify, the configuration items the connector needs to call the source API, and one or more change operations to apply to the identity. Each operation has the following special considerations:
- **Set:** Set tells the connector to overwrite the current value of the attribute or entitlement with the new value provided in the payload. The entire entitlement array resets if there are multi-valued entitlements.
@@ -95,14 +95,14 @@ The following example payload tells the connector to perform the following updat
## Response Schema
After the connector applies the operations defined in the input payload, the connector must respond to IDN with the changes to the account so IDN can update the identity accordingly. If an account update operation results in no changes to the account, the connector responds with an empty object `{}`. If the update operation results in one or more changes to the account, the connector responds with the complete account as it exists in the source, just like an account read response. IDN can parse the response and apply the differences accordingly.
After the connector applies the operations defined in the input payload, the connector must respond to ISC with the changes to the account so ISC can update the identity accordingly. If an account update operation results in no changes to the account, the connector responds with an empty object `{}`. If the update operation results in one or more changes to the account, the connector responds with the complete account as it exists in the source, just like an account read response. ISC can parse the response and apply the differences accordingly.
## Testing in IdentityNow
## Testing in Identity Security Cloud
You can test the account update command the way you test the [Account Create](./account-create.md) command. Follow the steps in “Testing in IdentityNow” from “Account Create” to set up an access profile and role. Be sure to run the aggregation so the account(s) are created in the target source. Once the account(s) are created in the target source, modify the access profile to grant an additional entitlement. Return to the role and click the Update button in the upper right corner. Doing so triggers the account update command because the accounts are already created in the target source. Once the update is complete, ensure the account(s) have the additional entitlement.
You can test the account update command the way you test the [Account Create](./account-create.md) command. Follow the steps in “Testing in Identity Security Cloud” from “Account Create” to set up an access profile and role. Be sure to run the aggregation so the account(s) are created in the target source. Once the account(s) are created in the target source, modify the access profile to grant an additional entitlement. Return to the role and click the Update button in the upper right corner. Doing so triggers the account update command because the accounts are already created in the target source. Once the update is complete, ensure the account(s) have the additional entitlement.
Note: Testing the account update command for removing entitlements using this method does not work. You can remove the entitlement from the access profile and run an update, but IDN will not send an update command to the connector to remove the entitlement. We are looking for suggestions on how to test the removal of entitlements.
Note: Testing the account update command for removing entitlements using this method does not work. You can remove the entitlement from the access profile and run an update, but ISC will not send an update command to the connector to remove the entitlement. We are looking for suggestions on how to test the removal of entitlements.
## Handling an account that is not found
If an account can't be found in the source system, IDN can recreate the account by using the ```ConnectorErrorType.NotFound``` error type. For details and implementation, refer to [Error Handling](../in-depth/error-handling.md#not-found-error-type).
If an account can't be found in the source system, ISC can recreate the account by using the ```ConnectorErrorType.NotFound``` error type. For details and implementation, refer to [Error Handling](../in-depth/error-handling.md#not-found-error-type).

View File

@@ -5,7 +5,7 @@ pagination_label: Change Password
sidebar_label: Change Password
keywords: ['connectivity', 'connectors', 'change password']
description: Change password for an account on the source.
slug: /docs/saas-connectivity/commands/change-password
slug: /connectivity/saas-connectivity/commands/change-password
tags: ['Connectivity', 'Connector Command']
---
@@ -34,7 +34,7 @@ tags: ['Connectivity', 'Connector Command']
## Description
The change password command is triggered in IDN when a user changes their password through IDN. When this occurs, if your source has change password enabled, then you can change the user password on the source system through IDN.
The change password command is triggered in ISC when a user changes their password through ISC. When this occurs, if your source has change password enabled, then you can change the user password on the source system through ISC.
## The Provisioning Plan
@@ -46,6 +46,6 @@ The change password command sends the password change event to your connector wh
})
```
## Testing in IdentityNow
## Testing in Identity Security Cloud
In order to test in IdentityNow, the source application must be configured so that it is able to accept password change requests through the Password Manager. Once this setup is complete, you can log in as a user whose identity exists in the configured application and change their password in the Password Manager.
In order to test in Identity Security Cloud, the source application must be configured so that it is able to accept password change requests through the Password Manager. Once this setup is complete, you can log in as a user whose identity exists in the configured application and change their password in the Password Manager.

View File

@@ -5,7 +5,7 @@ pagination_label: Entitlement List
sidebar_label: Entitlement List
keywords: ['connectivity', 'connectors', 'entitlement list']
description: Gather a list of all entitlements available on the source.
slug: /docs/saas-connectivity/commands/entitlement-list
slug: /connectivity/saas-connectivity/commands/entitlement-list
tags: ['Connectivity', 'Connector Command']
---
@@ -42,7 +42,7 @@ tags: ['Connectivity', 'Connector Command']
## Description
The entitlement list command triggers during a manual or scheduled entitlement aggregation operation within IDN. This operation gathers a list of all entitlements available on the target source, usually multi-valued entitlements like groups or roles. This operation provides IDN administrators with a list of entitlements available on the source so they can create access profiles and roles accordingly, and it provides IDN with more details about the entitlements. The entitlement schemas minimum requirements are name and ID, but you can add other values, such as created date, updated date, status, etc.
The entitlement list command triggers during a manual or scheduled entitlement aggregation operation within ISC. This operation gathers a list of all entitlements available on the target source, usually multi-valued entitlements like groups or roles. This operation provides ISC administrators with a list of entitlements available on the source so they can create access profiles and roles accordingly, and it provides ISC with more details about the entitlements. The entitlement schemas minimum requirements are name and ID, but you can add other values, such as created date, updated date, status, etc.
![Discover Schema 4](./img/entitlement_list_idn.png)
@@ -106,13 +106,13 @@ private buildStandardObject(): StdEntitlementReadOutput | StdEntitlementListOutp
```
:::caution Important
IDN will throw a connection timeout error if your connector doesn't respond within 3 minutes, and there are memory limitations involved with aggregating data. To prevent large memory utilization or timeout errors, you should set up your connectors to send data to IDN as it's retrieved from your source system. For more details and an example, refer to [Connector Timeouts](../in-depth/connector-timeouts.md).
ISC will throw a connection timeout error if your connector doesn't respond within 3 minutes, and there are memory limitations involved with aggregating data. To prevent large memory utilization or timeout errors, you should set up your connectors to send data to ISC as it's retrieved from your source system. For more details and an example, refer to [Connector Timeouts](../in-depth/connector-timeouts.md).
:::
:::caution Important
IDN supports [delta aggregation](#delta-aggregation-state). If your source has a large number of entitlements that will be syncronized with IDN, then it is highly recommended to utilize [delta aggregation](#delta-aggregation-state) for the source.
ISC supports [delta aggregation](#delta-aggregation-state). If your source has a large number of entitlements that will be syncronized with ISC, then it is highly recommended to utilize [delta aggregation](#delta-aggregation-state) for the source.
:::
@@ -133,7 +133,7 @@ If your source can keep track of changes to the data in some way, then delta agg
}
```
2. In the ```stdEntitlementList``` command, when you are done sending entitlments, you need to also send the state to IDN so it knows where to start the next time it sends a list request:
2. In the ```stdEntitlementList``` command, when you are done sending entitlments, you need to also send the state to ISC so it knows where to start the next time it sends a list request:
```javascript
const state = {"data": Date.now().toString()}

View File

@@ -5,13 +5,13 @@ pagination_label: Entitlement Read
sidebar_label: Entitlement Read
keywords: ['connectivity', 'connectors', 'entitlement read']
description: Fetch a single entitlements attributes from the source.
slug: /docs/saas-connectivity/commands/entitlement-read
slug: /connectivity/saas-connectivity/commands/entitlement-read
tags: ['Connectivity', 'Connector Command']
---
:::note
At this time Entitlement Read is not triggered from IDN for any specific workflow and as such it is not necessary to implement this in order to have a fully functional connector.
At this time Entitlement Read is not triggered from ISC for any specific workflow and as such it is not necessary to implement this in order to have a fully functional connector.
:::
@@ -54,7 +54,7 @@ At this time Entitlement Read is not triggered from IDN for any specific workflo
## Response Schema
Entitlement read fetches a single entitlements attributes and returns the resulting object to IDN, similar to how entitlement list does. You can implement this in the main connector file, [index.ts](https://github.com/sailpoint-oss/airtable-example-connector/blob/main/src/index.ts):
Entitlement read fetches a single entitlements attributes and returns the resulting object to ISC, similar to how entitlement list does. You can implement this in the main connector file, [index.ts](https://github.com/sailpoint-oss/airtable-example-connector/blob/main/src/index.ts):
```javascript
...

View File

@@ -7,7 +7,7 @@ sidebar_position: 7
sidebar_class_name: connectorCommands
keywords: ['connectivity', 'connector', 'commands']
description: All commands available to implement in a SaaS Connector.
slug: /docs/saas-connectivity/connector-commands
slug: /connectivity/saas-connectivity/connector-commands
tags: ['Connectivity']
---

View File

@@ -5,7 +5,7 @@ pagination_label: Source Data Discover
sidebar_label: Source Data Discover
keywords: ['connectivity', 'connectors', 'Source Data Discover']
description: Discover potential source data types.
slug: /docs/saas-connectivity/commands/source-data-discover
slug: /connectivity/saas-connectivity/commands/source-data-discover
tags: ['Connectivity', 'Connector Command']
---
@@ -44,9 +44,9 @@ tags: ['Connectivity', 'Connector Command']
## Description
Use the source data discover command to identify the types of data your source can return. Different sources can send different types of data to IdentityNow. For example, one source may be able to send a list of the different languages it supports, while another may be able to send values describing source details normally sent through accounts and entitlements. You can use the source data discover command to discover these possibilities.
Use the source data discover command to identify the types of data your source can return. Different sources can send different types of data to Identity Security Cloud. For example, one source may be able to send a list of the different languages it supports, while another may be able to send values describing source details normally sent through accounts and entitlements. You can use the source data discover command to discover these possibilities.
One typical use for the source data discover command is found in IdentityNow customer forms for dropdown menus: they use the command to identify the additional source types their sources can provide to IdentityNow and use that information to populate the dropdown menus.
One typical use for the source data discover command is found in Identity Security Cloud customer forms for dropdown menus: they use the command to identify the additional source types their sources can provide to Identity Security Cloud and use that information to populate the dropdown menus.
This is a simple example of the source data discover command. It has been implemented to list two types of queries that the Airtable source can supply.

View File

@@ -5,7 +5,7 @@ pagination_label: Source Data Read
sidebar_label: Source Data Read
keywords: ['connectivity', 'connectors', 'Source Data Read']
description: Read source data.
slug: /docs/saas-connectivity/commands/source-data-read
slug: /connectivity/saas-connectivity/commands/source-data-read
tags: ['Connectivity', 'Connector Command']
---
@@ -45,7 +45,7 @@ tags: ['Connectivity', 'Connector Command']
## Description
Use the source data read command to query a source in IdentityNow and return a set of data. This data is typically used to populate a dropdown menu for selection purposes. This functionality is typically useful for IdentityNow forms, but it can be used for any type of implementation that requires you to get other information from a source, information that is not normally retrieved from identites or entitlements.
Use the source data read command to query a source in Identity Security Cloud and return a set of data. This data is typically used to populate a dropdown menu for selection purposes. This functionality is typically useful for Identity Security Cloud forms, but it can be used for any type of implementation that requires you to get other information from a source, information that is not normally retrieved from identites or entitlements.
This is a simple example of the source data read command. It is implemented to retrieve the base ID name. The `sourceDataKey` is required, the ```source data read``` command should return it.

View File

@@ -5,7 +5,7 @@ pagination_label: Test Connection
sidebar_label: Test Connection
keywords: ['connectivity', 'connectors', 'test connection']
description: Ensure the connector can communicate with the source.
slug: /docs/saas-connectivity/commands/test-connection
slug: /connectivity/saas-connectivity/commands/test-connection
tags: ['Connectivity', 'Connector Command']
---
@@ -25,7 +25,7 @@ tags: ['Connectivity', 'Connector Command']
The test connection command ensures the connector can communicate with the target web service. It validates API credentials, host names, ports, and other configuration items. To implement this command, look for either a health endpoint or a simple GET endpoint. Some web services implement a health endpoint that returns status information about the service, which can be useful to test a connection. If no health endpoint exists, use a simple GET endpoint that takes few to no parameters to ensure the connector can make a successful call to the web service.
Use Test Connection in the IDN UI after an admin has finished entering configuration information for a new instance of the connector.
Use Test Connection in the ISC UI after an admin has finished entering configuration information for a new instance of the connector.
![Test Connection](./img/test_command_idn.png)

View File

@@ -5,7 +5,7 @@ pagination_label: Account Create
sidebar_label: Account Create
keywords: ['connectivity', 'connectors', 'Account Create']
description: Intercept the account create command.
slug: /docs/saas-connectivity/customizers/commands/account-create
slug: /connectivity/saas-connectivity/customizers/commands/account-create
tags: ['Connectivity', 'Connector Command']
---

View File

@@ -5,7 +5,7 @@ pagination_label: Account Delete
sidebar_label: Account Delete
keywords: ['connectivity', 'connectors', 'Account Delete']
description: Intercept the account delete command.
slug: /docs/saas-connectivity/customizers/commands/account-delete
slug: /connectivity/saas-connectivity/customizers/commands/account-delete
tags: ['Connectivity', 'Connector Command']
---

View File

@@ -5,7 +5,7 @@ pagination_label: Account Disable
sidebar_label: Account Disable
keywords: ['connectivity', 'connectors', 'Account Disable']
description: Intercept the account disable command.
slug: /docs/saas-connectivity/customizers/commands/account-disable
slug: /connectivity/saas-connectivity/customizers/commands/account-disable
tags: ['Connectivity', 'Connector Command']
---

View File

@@ -5,7 +5,7 @@ pagination_label: Account Enable
sidebar_label: Account Enable
keywords: ['connectivity', 'connectors', 'Account Enable']
description: Intercept the account enable command.
slug: /docs/saas-connectivity/customizers/commands/account-enable
slug: /connectivity/saas-connectivity/customizers/commands/account-enable
tags: ['Connectivity', 'Connector Command']
---

View File

@@ -5,7 +5,7 @@ pagination_label: Account List
sidebar_label: Account List
keywords: ['connectivity', 'connectors', 'Account List']
description: Intercept the account list command.
slug: /docs/saas-connectivity/customizers/commands/account-list
slug: /connectivity/saas-connectivity/customizers/commands/account-list
tags: ['Connectivity', 'Connector Command']
---
@@ -40,4 +40,4 @@ The `input` object can be mutated and returned, but the same data type must stil
### After account-list command
After account-list is not available for customization at this time. If you need to modify the values of the response, it is recommended that you use [Transforms](https://developer.sailpoint.com/idn/docs/transforms/).
After account-list is not available for customization at this time. If you need to modify the values of the response, it is recommended that you use [Transforms](https://developer.sailpoint.com/docs/extensibility/transforms/).

View File

@@ -5,7 +5,7 @@ pagination_label: Account Read
sidebar_label: Account Read
keywords: ['connectivity', 'connectors', 'Account Read']
description: Intercept the account read command.
slug: /docs/saas-connectivity/customizers/commands/account-read
slug: /connectivity/saas-connectivity/customizers/commands/account-read
tags: ['Connectivity', 'Connector Command']
---

View File

@@ -5,7 +5,7 @@ pagination_label: Account Unlock
sidebar_label: Account Unlock
keywords: ['connectivity', 'connectors', 'Account Unlock']
description: Intercept the account unlock command.
slug: /docs/saas-connectivity/customizers/commands/account-unlock
slug: /connectivity/saas-connectivity/customizers/commands/account-unlock
tags: ['Connectivity', 'Connector Command']
---

View File

@@ -5,7 +5,7 @@ pagination_label: Account Update
sidebar_label: Account Update
keywords: ['connectivity', 'connectors', 'Account Update']
description: Intercept the account update command.
slug: /docs/saas-connectivity/customizers/commands/account-update
slug: /connectivity/saas-connectivity/customizers/commands/account-update
tags: ['Connectivity', 'Connector Command']
---

View File

@@ -5,7 +5,7 @@ pagination_label: Change Password
sidebar_label: Change Password
keywords: ['connectivity', 'connectors', 'Change Password']
description: Intercept the change password command.
slug: /docs/saas-connectivity/customizers/commands/change-password
slug: /connectivity/saas-connectivity/customizers/commands/change-password
tags: ['Connectivity', 'Connector Command']
---

View File

@@ -5,7 +5,7 @@ pagination_label: Entitlement List
sidebar_label: Entitlement List
keywords: ['connectivity', 'connectors', 'Entitlement List']
description: Intercept the entitlement list command.
slug: /docs/saas-connectivity/customizers/commands/entitlement-list
slug: /connectivity/saas-connectivity/customizers/commands/entitlement-list
tags: ['Connectivity', 'Connector Command']
---
@@ -42,4 +42,4 @@ The `input` object can be mutated and returned, but the same data type must stil
### After entitlement-list command
After entitlement-list is not available for customization at this time. If you need to modify the values of the response, it is recommended that you use [Transforms](https://developer.sailpoint.com/idn/docs/transforms/).
After entitlement-list is not available for customization at this time. If you need to modify the values of the response, it is recommended that you use [Transforms](https://developer.sailpoint.com/docs/extensibility/transforms/).

View File

@@ -5,7 +5,7 @@ pagination_label: Entitlement Read
sidebar_label: Entitlement Read
keywords: ['connectivity', 'connectors', 'Entitlement Read']
description: Intercept the entitlement read command.
slug: /docs/saas-connectivity/customizers/commands/entitlement-read
slug: /connectivity/saas-connectivity/customizers/commands/entitlement-read
tags: ['Connectivity', 'Connector Command']
---

View File

@@ -7,7 +7,7 @@ sidebar_position: 7
sidebar_class_name: connectorCommands
keywords: ['connectivity', 'connector', 'commands']
description: Available connectivity customizer commands.
slug: /docs/saas-connectivity/customizers/commands
slug: /connectivity/saas-connectivity/customizers/commands
tags: ['Connectivity']
---

View File

@@ -5,7 +5,7 @@ pagination_label: Source Data Discover
sidebar_label: Source Data Discover
keywords: ['connectivity', 'connectors', 'Source Data Discover']
description: Intercept the source data discover command.
slug: /docs/saas-connectivity/customizers/commands/source-data-discover
slug: /connectivity/saas-connectivity/customizers/commands/source-data-discover
tags: ['Connectivity', 'Connector Command']
---

View File

@@ -5,7 +5,7 @@ pagination_label: Source Data Read
sidebar_label: Source Data Read
keywords: ['connectivity', 'connectors', 'Source Data Read']
description: Intercept the source data read command.
slug: /docs/saas-connectivity/customizers/commands/source-data-read
slug: /connectivity/saas-connectivity/customizers/commands/source-data-read
tags: ['Connectivity', 'Connector Command']
---

View File

@@ -5,7 +5,7 @@ pagination_label: Test Connection
sidebar_label: Test Connection
keywords: ['connectivity', 'connectors', 'test connection']
description: Intercept the test connection command.
slug: /docs/saas-connectivity/customizers/commands/test-connection
slug: /connectivity/saas-connectivity/customizers/commands/test-connection
tags: ['Connectivity', 'Connector Command']
---

View File

@@ -7,7 +7,7 @@ sidebar_position: 7
sidebar_class_name: saasConnectivity
keywords: ['connectivity', 'connectors', customizers]
description: Full connectivity customizer example.
slug: /docs/saas-connectivity/customizers/example
slug: /connectivity/saas-connectivity/customizers/example
tags: ['Connectivity']
---

View File

@@ -7,7 +7,7 @@ sidebar_position: 4
sidebar_class_name: saasConnectivity
keywords: ['connectivity', 'connectors', customizers]
description: Get started with connectivity customizers.
slug: /docs/saas-connectivity/customizers/getting-started
slug: /connectivity/saas-connectivity/customizers/getting-started
tags: ['Connectivity']
---

View File

@@ -7,17 +7,17 @@ sidebar_position: 7.1
sidebar_class_name: saasConnectivity
keywords: ['connectivity', 'connectors', customizers]
description: Connectivity customizers can customize out of the box SaaS connectors.
slug: /docs/saas-connectivity/customizers
slug: /connectivity/saas-connectivity/customizers
tags: ['Connectivity']
---
# Overview
SaaS Connectivity Customizers are cloud-based connector customizers that make customizing out of the box SaaS connectors possible. The customizers allow you to customize the out of the box connectors in a similar way to how you can use rules to customize VA (virtual appliance) based connectors. By using a customizer, you can change a connector's input before the connector ingests the data, or you can change the connector's output before to the output is sent to IdentityNow.
SaaS Connectivity Customizers are cloud-based connector customizers that make customizing out of the box SaaS connectors possible. The customizers allow you to customize the out of the box connectors in a similar way to how you can use rules to customize VA (virtual appliance) based connectors. By using a customizer, you can change a connector's input before the connector ingests the data, or you can change the connector's output before to the output is sent to Identity Security Cloud.
## How do they work?
SaaS Connectivity Customizers work by sitting in between IdentityNow and the connector. They intercept calls from IdentityNow to the connector and calls from the connector to IdentityNow. When the customizer intercepts a call, it can call custom code to mutate the data in any way necessary to change the connector behavior.
SaaS Connectivity Customizers work by sitting in between Identity Security Cloud and the connector. They intercept calls from Identity Security Cloud to the connector and calls from the connector to Identity Security Cloud. When the customizer intercepts a call, it can call custom code to mutate the data in any way necessary to change the connector behavior.
This chart shows an example of this interception process - the ```stdAccountRead``` command is implemented with the customizer in place:
@@ -26,14 +26,14 @@ This chart shows an example of this interception process - the ```stdAccountRead
```mermaid
sequenceDiagram
autonumber
participant IDN as IdentityNow
participant ISC as Identity Security Cloud
participant CUS as Customizer
participant CON as SaaS Connector
IDN->>CUS: StdAccountRead Request
ISC->>CUS: StdAccountRead Request
CUS->>CON: Mutated StdAccountRead Request
CON->>CUS: StdAccountRead Response
CUS->>IDN: Mutated StdAccountRead Response
CUS->>ISC: Mutated StdAccountRead Response
```

View File

@@ -7,7 +7,7 @@ sidebar_position: 6
sidebar_class_name: saasConnectivity
keywords: ['connectivity', 'connectors', customizers]
description: Link connectivity customizers to sources.
slug: /docs/saas-connectivity/customizers/linking
slug: /connectivity/saas-connectivity/customizers/linking
tags: ['Connectivity']
---
@@ -15,7 +15,7 @@ tags: ['Connectivity']
### Initial requirements
Before you can link a connector customizer to a source, you must have a SaaS source in IdentityNow, as well as a Customizer built and deployed. You can use the following commands to get a list of valid sources, as well as customizers:
Before you can link a connector customizer to a source, you must have a SaaS source in Identity Security Cloud, as well as a Customizer built and deployed. You can use the following commands to get a list of valid sources, as well as customizers:
Use this command to find sources:

View File

@@ -7,7 +7,7 @@ sidebar_position: 6
sidebar_class_name: saasConnectivity
keywords: ['connectivity', 'connectors', customizers]
description: Test and debug connectors with customizers.
slug: /docs/saas-connectivity/customizers/testing
slug: /connectivity/saas-connectivity/customizers/testing
tags: ['Connectivity']
---

View File

@@ -1,17 +1,17 @@
---
id: connectivity-customizers-uploading
title: Build and Upload into Identity Now
title: Build and Upload into Identity Security Cloud
pagination_label: Build and Upload
sidebar_label: Build and Upload
sidebar_position: 5
sidebar_class_name: saasConnectivity
keywords: ['connectivity', 'connectors', customizers]
description: Build and upload connectivity customizers.
slug: /docs/saas-connectivity/customizers/upload
slug: /connectivity/saas-connectivity/customizers/upload
tags: ['Connectivity']
---
# Building and uploading to Identity Now
# Building and uploading to Identity Security Cloud
### Initial requirements
@@ -48,9 +48,9 @@ After the build is complete, you will see a message like this:
Connector zip file created under dist folder: my-connector-customizer-0.1.0.zip
```
### Upload to IdentityNow
### Upload to Identity Security Cloud
To upload the customizer to IdentityNow, use the upload command:
To upload the customizer to Identity Security Cloud, use the upload command:
```bash
sail conn customizers upload -c 7b968fab-0f40-49f0-b13b-8bf529fc0b82 -f .\dist\my-connector-customizer-0.1.0.zip

View File

@@ -5,7 +5,7 @@ pagination_label: Card
sidebar_label: Card
keywords: ['connectivity', 'connectors','connector-spec', 'card']
description: Details on using the card item
slug: /docs/saas-connectivity/connector-spec/card
slug: /connectivity/saas-connectivity/connector-spec/card
tags: ['Connectivity', 'Connector Spec']
---

View File

@@ -6,14 +6,14 @@ sidebar_label: Connector Spec File
sidebar_position: 4
sidebar_class_name: connectorSpecFile
keywords: ['connectivity', 'connectors', 'spec', 'specification']
description: The connector spec file tells IDN how the connector should interact between IDN and the custom connector. It is the glue between IDN and the connector, so understanding the different sections are key to understanding how to build a custom connectors.
slug: /docs/saas-connectivity/connector-spec
description: The connector spec file tells ISC how the connector should interact between ISC and the custom connector. It is the glue between ISC and the connector, so understanding the different sections are key to understanding how to build a custom connectors.
slug: /connectivity/saas-connectivity/connector-spec
tags: ['Connectivity']
---
## Summary
The connector spec file tells IDN how the connector should interact between IDN and the custom connector. It is the glue between IDN and the connector, so understanding the different sections are key to understanding how to build a custom connectors.
The connector spec file tells ISC how the connector should interact between ISC and the custom connector. It is the glue between ISC and the connector, so understanding the different sections are key to understanding how to build a custom connectors.
## Sample File
@@ -23,7 +23,7 @@ To see a sample spec file, see this link: [connector-spec.json](https://github.c
The following describes in detail the different fields in the connector spec:
- **name:** The name of the connector as it appears in IDN. Tags can be appended to this name.
- **name:** The name of the connector as it appears in ISC. Tags can be appended to this name.
- **keyType:** Either “simple” or “compound” This determines which type of key your connector expects to receive and send back for each of the commands. This must always be indicated in your connector spec - the connector returns the correct type for each command that returns a key type.
@@ -31,9 +31,9 @@ The following describes in detail the different fields in the connector spec:
- **commands:** The list of commands the connector supports. A full list of available commands can be found [here](../connector-commands/index.md).
- **[sourceConfigInitialValues](./connector-spec/initial-value):** Key value pair of source config item keys and the default value that should be associated with them.
- **sourceConfig** A list of configuration items you must provide when you create a source in IDN. The order of these items is preserved in the UI.
- **sourceConfig** A list of configuration items you must provide when you create a source in ISC. The order of these items is preserved in the UI.
- **type:** This is always “menu” - it indicates a new menu for the sidebar. You can have multiple sections defined for complex connector configurations
- **label:** This label indicates the text that will show up on the sidebar in IDN
- **label:** This label indicates the text that will show up on the sidebar in ISC
- **items:** The array of items in the menu
- **type:** This is always "section" - it indicates a new section on the page
- **sectionTitle:** The large text title that will display for the section.
@@ -42,7 +42,7 @@ The following describes in detail the different fields in the connector spec:
- **docLink:** The optional link that the docLinkLabel will direct to if clicked.
- **key:** The name of the configuration item as it is referenced in code.
- **label:** The name of the configuration item as it appears in the UI.
- **required** (Optional): Set to 'false' by default. Valid values are 'true' or 'false.' You must populate required configuration items in the IDN source configuration wizard before continuing.
- **required** (Optional): Set to 'false' by default. Valid values are 'true' or 'false.' You must populate required configuration items in the ISC source configuration wizard before continuing.
- **type:** The configuration items' types. The following types are valid:
- text
- number
@@ -57,27 +57,27 @@ The following describes in detail the different fields in the connector spec:
- [list](./connector-spec/list)
- [keyValue](./connector-spec/key-value)
- [cardList](./connector-spec/card)
- **accountSchema:** The schema for an account in IDN populated by data from the source.
- **displayAttribute:** Identifies the attribute (defined below) used to map to `Account Name` in the IdentityNow account schema. This should be a unique value even though it is not required because the connector will use this value to correlate accounts in IDN to accounts in the source system.
- **identityAttribute:** Identifies the attribute (defined below) used to map to `Account ID` in the IdentityNow account schema. This must be a globally unique identifier, such as email address, employee ID, etc.
- **accountSchema:** The schema for an account in ISC populated by data from the source.
- **displayAttribute:** Identifies the attribute (defined below) used to map to `Account Name` in the Identity Security Cloud account schema. This should be a unique value even though it is not required because the connector will use this value to correlate accounts in ISC to accounts in the source system.
- **identityAttribute:** Identifies the attribute (defined below) used to map to `Account ID` in the Identity Security Cloud account schema. This must be a globally unique identifier, such as email address, employee ID, etc.
- **groupAttribute:** Identifies the attribute used to map accounts to entitlements. For example, a web service can define `groups` that users are members of, and the `groups` grant entitlements to each user. In this case, **groupAttribute** is “groups,” and there is also an account attribute called “groups”.
- **attributes:** One or more attributes that map to a users attribute on the target source. Each attribute defines the following:
- **name:** The attributes name as it appears in IDN.
- **name:** The attributes name as it appears in ISC.
- **type:** The attributes type. Possible values are `string`, `boolean`, `long`, and `int`.
- **description:** A helpful description of the attribute. This is useful to source owners when they are trying to understand the account schema.
- **managed:** This indicates whether the entitlements are manageable through IDN or read-only.
- **entitlement:** This boolean indicates whether the attribute is an entitlement. Entitlements give identities privileges on the source system. Use this indication to determine which fields to synchronize with accounts in IDN for tasks such as separation of duties and role assignment. The boolean indicates whether the attribute is an entitlement.
- **managed:** This indicates whether the entitlements are manageable through ISC or read-only.
- **entitlement:** This boolean indicates whether the attribute is an entitlement. Entitlements give identities privileges on the source system. Use this indication to determine which fields to synchronize with accounts in ISC for tasks such as separation of duties and role assignment. The boolean indicates whether the attribute is an entitlement.
- **multi:** This indicates entitlements that are stored in an array format. This one field can store multiple entitlements for a single account.
- **entitlementSchemas:** A list of entitlement schemas in IDN populated by data from the source.
- **entitlementSchemas:** A list of entitlement schemas in ISC populated by data from the source.
- **type:** The entitlements type. Currently, only `group` is supported.
- **displayAttribute:** The entitlement attributes name. This can be the `name` or another human friendly identifier for a group.
- **identityAttribute:** The entitlement attributes unique ID. This can be the `id` or another unique key for a group.
- **attributes:** The entitlements list of attributes. This list of attributes is an example: `id`, `name`, and `description`.
- **name:** The name of the attribute as it appears in IDN.
- **name:** The name of the attribute as it appears in ISC.
- **type:** The attributes type. Possible values are `string`, `boolean`, `long`, and `int`.
- **description:** A helpful description the attribute. This is useful to source owners when they are trying to understand the account schema.
- **accountCreateTemplate:** A map of identity attributes IDN will pass to the connector to create an account in the target source.
- **key:** The unique identifier of the attribute. This is also the name that is presented in the Create Profile screen in IDN.
- **accountCreateTemplate:** A map of identity attributes ISC will pass to the connector to create an account in the target source.
- **key:** The unique identifier of the attribute. This is also the name that is presented in the Create Profile screen in ISC.
- **label:** A friendly name for presentation purposes.
- **type:** The attributes type. Possible values are `string`, `boolean`, `long`, and `int`.
- **initialValue (Optional):** Use this to specify identitAttribute mapping, generator or default values.
@@ -88,4 +88,4 @@ The following describes in detail the different fields in the connector spec:
- **maxSize:** Use this for the Create Unique Account ID generator type. This value specifies the maximum size of the username to be generated.
- **maxUniqueChecks:** Use this for the Create Unique Account ID generator type. This value specifies the maximum retries in case a unique ID is not found with the first random generated user.
- **template:** Use this for the Create Unique Account ID generator type. This value specifies the template used for generation. Example: `"$(firstname).$(lastname)$(uniqueCounter)"`.
- **required (Optional):** Determines whether the account create operation requires this attribute. It defaults to `false`. If it is `true` and IdentityNow encounters an identity missing this attribute, IDN does not send the account to the connector for account creation.
- **required (Optional):** Determines whether the account create operation requires this attribute. It defaults to `false`. If it is `true` and Identity Security Cloud encounters an identity missing this attribute, ISC does not send the account to the connector for account creation.

View File

@@ -5,7 +5,7 @@ pagination_label: Initial Value
sidebar_label: Initial Value
keywords: ['connectivity', 'connectors','connector-spec', 'sourceConfigInitialValues']
description: How to use the sourceConfigInitialValues field
slug: /docs/saas-connectivity/connector-spec/initial-value
slug: /connectivity/saas-connectivity/connector-spec/initial-value
tags: ['Connectivity', 'Connector Spec']
---

View File

@@ -5,7 +5,7 @@ pagination_label: Key Value
sidebar_label: Key Value
keywords: ['connectivity', 'connectors','connector-spec', 'keyValue']
description: Details on using the key value item
slug: /docs/saas-connectivity/connector-spec/key-value
slug: /connectivity/saas-connectivity/connector-spec/key-value
tags: ['Connectivity', 'Connector Spec']
---

View File

@@ -5,7 +5,7 @@ pagination_label: List
sidebar_label: List
keywords: ['connectivity', 'connectors','connector-spec', 'list']
description: Details on using the list item
slug: /docs/saas-connectivity/connector-spec/list
slug: /connectivity/saas-connectivity/connector-spec/list
tags: ['Connectivity', 'Connector Spec']
---

View File

@@ -5,7 +5,7 @@ pagination_label: Radio
sidebar_label: Radio
keywords: ['connectivity', 'connectors','connector-spec', 'radio']
description: Details on using the Radio item
slug: /docs/saas-connectivity/connector-spec/radio
slug: /connectivity/saas-connectivity/connector-spec/radio
tags: ['Connectivity', 'Connector Spec']
---

View File

@@ -5,7 +5,7 @@ pagination_label: Select
sidebar_label: Select
keywords: ['connectivity', 'connectors','connector-spec', 'select']
description: Details on using the select item
slug: /docs/saas-connectivity/connector-spec/select
slug: /connectivity/saas-connectivity/connector-spec/select
tags: ['Connectivity', 'Connector Spec']
---

View File

@@ -7,7 +7,7 @@ sidebar_position: 5
sidebar_class_name: exampleConnectors
keywords: ['connectivity', 'connectors', 'example']
description: Here are a few example connectors that were built for you to download and learn from.
slug: /docs/saas-connectivity/example-connectors
slug: /connectivity/saas-connectivity/example-connectors
tags: ['Connectivity']
---

View File

Before

Width:  |  Height:  |  Size: 3.3 KiB

After

Width:  |  Height:  |  Size: 3.3 KiB

View File

Before

Width:  |  Height:  |  Size: 8.6 KiB

After

Width:  |  Height:  |  Size: 8.6 KiB

View File

Before

Width:  |  Height:  |  Size: 12 KiB

After

Width:  |  Height:  |  Size: 12 KiB

View File

Before

Width:  |  Height:  |  Size: 8.3 KiB

After

Width:  |  Height:  |  Size: 8.3 KiB

View File

Before

Width:  |  Height:  |  Size: 2.4 KiB

After

Width:  |  Height:  |  Size: 2.4 KiB

View File

Before

Width:  |  Height:  |  Size: 2.3 KiB

After

Width:  |  Height:  |  Size: 2.3 KiB

View File

Before

Width:  |  Height:  |  Size: 3.9 KiB

After

Width:  |  Height:  |  Size: 3.9 KiB

View File

@@ -7,7 +7,7 @@ sidebar_position: 1
sidebar_class_name: apiCalls
keywords: ['connectivity', 'connectors', 'api calls']
description: Calling API endpoints sequentially for hundreds or thousands of accounts is slow. If several API calls are required to build a users account, then it is recommended that you use asynchronous functions to speed up this task.
slug: /docs/saas-connectivity/in-depth/api-calls
slug: /connectivity/saas-connectivity/in-depth/api-calls
tags: ['Connectivity']
---

View File

@@ -6,12 +6,12 @@ sidebar_label: CLI - Advanced
sidebar_position: 1
sidebar_class_name: cliAdvanced
keywords: ['connectivity', 'connectors', 'cli']
description: Using the CLI to properly test and debug your connector in IdentityNow
slug: /docs/saas-connectivity/in-depth/cli-advanced
description: Using the CLI to properly test and debug your connector in Identity Security Cloud
slug: /connectivity/saas-connectivity/in-depth/cli-advanced
tags: ['Connectivity']
---
You can use the CLI to invoke a number of calls in IdentityNow, including calls that aren't specifically defined by the CLI. This section includes examples that show how you can invoke those calls:
You can use the CLI to invoke a number of calls in Identity Security Cloud, including calls that aren't specifically defined by the CLI. This section includes examples that show how you can invoke those calls:
## Use provided CLI invoke calls

View File

@@ -6,14 +6,14 @@ sidebar_label: Connector Timeouts
sidebar_position: 1.2
sidebar_class_name: connectorTimeouts
keywords: ['connectivity', 'connectors', 'timeout']
description: IdentityNow will throw an error if your connector does not send a response in 3 minutes. For connector commands that might take longer than 3 minutes, make sure to send data at regular intervals to prevent a timeout.
slug: /docs/saas-connectivity/in-depth/connector-timeouts
description: Identity Security Cloud will throw an error if your connector does not send a response in 3 minutes. For connector commands that might take longer than 3 minutes, make sure to send data at regular intervals to prevent a timeout.
slug: /connectivity/saas-connectivity/in-depth/connector-timeouts
tags: ['Connectivity']
---
An IdentityNow SaaS Connectivity connector will send a timeout error if it doesn't send a response within 3 minutes. If the connector is sending thousands of records, the record fetching process will likely exceed this timeout limit. If you are storing all those records in memory before sending them to IDN, you can run into memory utilization issues. To prevent these issues, you should paginate through your source data and send the data back in regular intervals.
An Identity Security Cloud SaaS Connectivity connector will send a timeout error if it doesn't send a response within 3 minutes. If the connector is sending thousands of records, the record fetching process will likely exceed this timeout limit. If you are storing all those records in memory before sending them to ISC, you can run into memory utilization issues. To prevent these issues, you should paginate through your source data and send the data back in regular intervals.
In the case of a long running API call to the source system, you can also optionally send `res.keepAlive()` to keep the connection to IdentityNow open without having to send any data to IdentityNow. If `res.keepAlive()` or `res.send()` is not called within 3 minutes, a connector timeout will occur.
In the case of a long running API call to the source system, you can also optionally send `res.keepAlive()` to keep the connection to Identity Security Cloud open without having to send any data to Identity Security Cloud. If `res.keepAlive()` or `res.send()` is not called within 3 minutes, a connector timeout will occur.
This is an example of how to set up this pagination:
@@ -25,8 +25,8 @@ async getAccounts(res: Response<StdAccountListOutput>): Promise<boolean> {
// each page will be called recursively until there are no more records to fetch, at which case the promise is fulfilled
).eachPage((records, fetchNextPage) => {
for (let record of records) {
// this is the part that sends the data to IdentityNow. Since eachPage is called with just 10 records,
// if there are 100 records total, we would send data back to IDN in 10 sets of 10 records.
// this is the part that sends the data to Identity Security Cloud. Since eachPage is called with just 10 records,
// if there are 100 records total, we would send data back to ISC in 10 sets of 10 records.
res.send({
identity: record.id,
attributes: {

Some files were not shown because too many files have changed in this diff Show More