Connecting your applications enables YeshID to help with orchestrating and managing your IAM related operations.

For example: Enabling Import Users keeps your Access Grid up to date, which is also what enables the (1) /remove user from all applications task during off-boarding workflows and (2) easily presents you an up-to-date snapshot of application users during an Application Audit. For a full mapping of how Integration Actions enable YeshID operations, see the Integration Actions & Enablement Table below.

There are 4 steps to integrating or Connecting your Applications

1. Choosing your Integration Type

2. Configuring Authentication

3. Configuring (and enabling) your Actions

Choosing your Integration Type

In YeshID, there are 3 ways to integrate or connect with your applications.

1. Prebuilt Integrations

Prebuilt integrations are integrations that have been researched and created by YeshID.

Because these integrations have been validated by YeshID, you only need to specify (1) the authentication details and (2) enable the actions that are known to be supported by this Application at time of development.

2. SCIM Integrations

SCIM (System for Cross-domain Identity Management) integrations that follow RFC7644 with standardized endpoints, attributes and operations.

The benefit of SCIM is standardization where (all basic operations(CRUD) are supported and use the same naming and endpoint structure):

Therefore, you only need to configure:

1. Your app/tenant's specific SCIM Endpoint URL

2. Which actions you'd like to enable.

These types of integrations sometimes require that you have the right plan and package within your apps. For example, at time of writing, Slack requires the Enterprise Grid plan to use SCIM.

See: ssotax.yeshid.com for more information.

3. Build Your Own Integrations

This is the fall-back option to support applications that may not be known to YeshID, and may not support SCIM. Use this when:

1. You know what authentication mechanism is required for your app

2. You know the endpoints required to perform required operations (CRUD).

Setting up your Authentication Settings

Authentication (AuthN) is how YeshID will communicate your app to execute the required actions. Once Authentication is set-up, that mechanism (token) is used for every subsequent action (i.e. List Users, Create User, Delete User).

YeshID currently supports 5 Authentication Types:

• Bearer

• OAuth

• Basic

• Custom API Key

• None

Bearer Authentication

Bearer authentication (often called Bearer token auth) is a common way to secure APIs using a token instead of a username/password. The client sends a token in the HTTP Authorization header, and the server trusts the request if the token is valid.

Use this method of your API documentation specifies adding in a "Bearer" token, similar to:

curl https://api.example.com/v1/users \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json"

Whatever is added into "Token" will be inserted into YOUR_ACCESS_TOKEN

OAuth2 Authentication

OAuth 2.0 is an authorization framework that allows an application to obtain limited access to a user's resources on another service without sharing the user's password.

There are 3 sub-types that may be utilized for OAuth2:

2.2.1 Authorization Code Grant

2.2.2 Client Credentials

2.2.3 Refresh Token

Scopes & Optional Fields

• Sometimes, your application may require that scopes are explicitly specified during authentication (i.e. specifying users.read). This can be added in under Scopes

  

• Some Applications may use non-standard header keys and value prefixes (i.e. use Auth: AuthBearer YOUR_ACCESS_TOKEN instead of Authorization: Bearer YOUR_ACCESS_TOKEN )

Basic Authentication

Basic Authentication is an API authentication method where a client sends a Base64-encoded username:password in the HTTP Authorization header with each request.

Use this mechanism if your Application expects basic username+password authentication.

Custom API Key

Custom API Key's are used if your application expects authentication details into non-standard headers (i.e. requires x-api-key instead of Authorization bearer )

• Authorization Params can be added to the Header or included as Query Parameters.

In the case of Pagerduty:

PagerDuty expects auth in the header in a non standard format of Authorization: Token token=<your_token>

To handle this we set:

1. Location Type: Header

2. Header Name: Authorization

3. Header Value: Token token = {{.Key}} where the key is set in

4. Token

None

• In the highly unlikely state that your applications don't require any Authentication, you can use this option.

Configure the Integration Actions

In YeshID, the main operations that are focused on are (CRUD):

• Create - Create User

• Retrieve - Import Users

• Update (Not used)

• Delete - Delete or Deactivate User

• Activate - Used by some applications that initially create users in a non-active state (i.e. "Invited), and requires a subsequent "Activate" action to transition them to "Active").

Enable the Integration Actions

Actions are what enables the basic operations that YeshID requires to work with your applications. See the Integration Actions & Enablement Table above.

UI Managed Integrations

Most integrations will be detailed in your application's documentation, and usually consist of:

1. And endpoint URL

2. An HTTP method (i.e. GET for list users, POST for creating a user)

3. A payload (usualy only required creating users)

Example - Importing Users

1. Click into the Action (Import Users)

2. Enter in the details from your Application

   

3. Click "Test"

4. Examine the response that is returned from the API. Most API's will return all users in JavaScript Object Notation (JSON)

   

5. Map the fields to your users with Agent Yesh

   1. Click "Generate Config"

   2. Confirm the mappings below.

      

      1. If they are incorrect, see below for how to Map the fields to users Manually

   3. Map the fields by clicking "Save"

6. Map the fields to your users (MANUALLY)

   1. You can manually specify the mappings using jq the "Map account information" field.

      Default values required to map to a user are:

      • ID - this is also referred as the "ExternalID" (this is what's used in future operations for updates, deletes etc)

      • Email - This is the field that's used to link with YeshID people.

      • Name

      1. Example:

         1. Records Path: .users

         2. ID: .id

            Or empty:

            In JQ, we use //"" to substitute a "" as a default value if the field is empty.

         3. Email: .email // ""

         4. Name: .name // ""

      2. Click Test to see the mappings and flip to Preview to validate.

         

7. Map the fields by clicking "Save"

8. Enable the Action

   This will trigger an immediate sync with your application.

Congratulations! Your users are now synced with your Application. Clicking into your Application and clicking on "Accounts" will show all your users, automatically kept in sync.

4.1.1 Example - Creating Users

1. Click into the Action

2. Set the Method

3. Set the Endpoint URL

4. Click Advanced to add the Payload Body

   

5. Refer to your application's documentations to determine what information must be provided in the payload. For example, for Pagerduty Create User

{
  "user": {
        "name": "",
        "email": ""
    }
}

6. Construct the JSON payload.

   

7. Enter in the required template variables

   

8. Confirm the payload (preview uses the currently logged in user)

   

9. Click "Save"

10. Enable the Integration

Test the Create user action

1. Click "Manage" > Add User

   

2. Pick an Existing User and click "Add 1 person to <app>"

   

3. You should see "A workflow has been created to add 1 person to PagerDuty"

4. 

Code-Backed Integrations

See documentation here

Add Custom Actions

There may be certain times that custom actions are required.

i.e. If using an I.T. Asset management application, you may want to automate to trigger an Order Asset endpoint. By using a Custom Action, you can execute custom actions as part of YeshID workflows.

1. In your application, "Add a custom action"

   

2. Configure your Custom Action (same as above)

   

3. Enable Action

   

4. In your YeshID Workflow, click /Run provisioner action for user

   

5. Expand task and (1) select application and (2) the custom action you created

   

Relevant Articles

• Connect & Integrate

• Supported Integrations

• SCIM with YeshID

• Code Backed Integrations