-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
* new-powershell-connector Made changes to use the new powershell v2 target logic. * Resolved review comments Resolved the review comments from the pull request * Update readme Update readme, more in line with HelloID-Conn-Prov-Target-V2-Template * fix link fix link * Updated readme to match template Updated according to template: * Added requirements * Added remarks * Added instructions to setup the connector. * Added references to documentation * Updated password to token as password is deprecated * formatted * Updated with examples from github helper functions library --------- Co-authored-by: rschouten97 <69046642+rschouten97@users.noreply.github.com>
- Loading branch information
1 parent
0142431
commit d933c47
Showing
10 changed files
with
779 additions
and
396 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,50 +1,118 @@ | ||
| # HelloID-Conn-Prov-Target-Atlassian-Jira | ||
|
|
||
| | :information_source: Information | | ||
| |:---------------------------| | ||
| | This repository contains the connector and configuration code only. The implementer is responsible to acquire the connection details such as username, password, certificate, etc. You might even need to sign a contract or agreement with the supplier before implementing this connector. Please contact the client's application manager to coordinate the connector requirements. | | ||
| > [!IMPORTANT] | ||
| > This repository contains the connector and configuration code only. The implementer is responsible to acquire the connection details such as username, password, certificate, etc. You might even need to sign a contract or agreement with the supplier before implementing this connector. Please contact the client's application manager to coordinate the connector requirements. | ||
| <br /> | ||
| <p align="center"> | ||
| <img src="https://www.tools4ever.nl/connector-logos/atlassianjira-logo.png"> | ||
| <img src="https://github.com/Tools4everBV/HelloID-Conn-Prov-Target-Atlassian-Jira/blob/main/Logo.png?raw=true"> | ||
| </p> | ||
|
|
||
| ## Versioning | ||
| | Version | Description | Date | | ||
| | - | - | - | | ||
| | 1.1.0 | Updated with group management | 2022/12/15 | | ||
| | 1.0.0 | Initial release | 2021/04/02 | | ||
|
|
||
| <!-- TABLE OF CONTENTS --> | ||
| ## Table of Contents | ||
| - [Versioning](#versioning) | ||
| - [Table of Contents](#table-of-contents) | ||
| - [Introduction](#introduction) | ||
| - [Connection settings](#connection-settings) | ||
| - [Getting help](#getting-help) | ||
| - [HelloID Docs](#helloid-docs) | ||
| ## Table of contents | ||
|
|
||
| - [HelloID-Conn-Prov-Target-Atlassian-Jira](#helloid-conn-prov-target-atlassian-jira) | ||
| - [Table of contents](#table-of-contents) | ||
| - [Prerequisites](#prerequisites) | ||
| - [Remarks](#remarks) | ||
| - [Introduction](#introduction) | ||
| - [Getting started](#getting-started) | ||
| - [Provisioning PowerShell V2 connector](#provisioning-powershell-v2-connector) | ||
| - [Correlation configuration](#correlation-configuration) | ||
| - [Field mapping](#field-mapping) | ||
| - [Connection settings](#connection-settings) | ||
| - [Setup the connector](#setup-the-connector) | ||
| - [API token](#api-token) | ||
| - [Permissions](#permissions) | ||
| - [Getting help](#getting-help) | ||
| - [HelloID docs](#helloid-docs) | ||
|
|
||
| ## Prerequisites | ||
| - [ ] _HelloID_ Provisioning agent (cloud or on-prem). | ||
| - [ ] _HelloID_ environment. | ||
| - [ ] API token in Atlassian. The following values are needed to connect: | ||
| - [ ] Username. | ||
| - [ ] Password. | ||
|
|
||
| ## Remarks | ||
| - There is no update API available, therefore there is no update action available either. | ||
|
|
||
| ## Introduction | ||
| The interface to communicate with Jira is via the API. Please see https://developer.atlassian.com/cloud/jira/platform/rest/v3/ for more information about the API. | ||
| _HelloID-Conn-Prov-Target-Atlassian-Jira_ is a _target_ connector. _Atlassian_ provides a set of REST API's that allow you to programmatically interact with its data. The Atlassian jira connector uses the API endpoints listed in the table below. | ||
|
|
||
| | Endpoint | Description | | ||
| | ------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- | | ||
| | [/rest/api/3/user](https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-users/#api-rest-api-3-user-post) | Create user (POST) | | ||
| | [/rest/api/3/user](https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-users/#api-rest-api-3-user-delete) | Delete user (DELETE) | | ||
| | [/rest/api/3/groups/picker](https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-groups/#api-rest-api-3-groups-picker-get) | List groups (GET) | | ||
| | [/rest/api/3/group/user](https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-groups/#api-rest-api-3-group-user-post) | Add member (POST) | | ||
| | [/rest/api/3/group/user](https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-groups/#api-rest-api-3-group-user-delete) | Remove member (DELETE) | | ||
|
|
||
|
|
||
| The following lifecycle actions are available: | ||
|
|
||
| | Action | Description | | ||
| | ----------------------------- | -------------------------------------- | | ||
| | create.ps1 | Create or correlate to an account | | ||
| | delete.ps1 | Delete an account | | ||
| | groups - permissions.ps1 | List groups as permissions | | ||
| | groups - grantPermission.ps1 | Grant groupmembership to an account | | ||
| | groups - revokePermission.ps1 | Revoke groupmembership from an account | | ||
| | configuration.json | Default _configuration.json_ | | ||
| | fieldMapping.json | Default _fieldMapping.json_ | | ||
|
|
||
| ## Getting started | ||
| By using this connector you will have the ability to seamlessly create delete and user accounts in Atlassian Jira. Additionally, you can manage the groupmemberships. | ||
|
|
||
| Connecting to Atlassian API is straightforward. Simply utilize the API Username and API Password pair and connect using basic authentication. | ||
| For further details, refer to the following pages in the Atlassian Docs: | ||
| [Basic auth for REST APIs](https://developer.atlassian.com/cloud/jira/platform/basic-auth-for-rest-apis/). | ||
|
|
||
| ### Provisioning PowerShell V2 connector | ||
|
|
||
| With this connector you can create and delete accounts. Furthermore you can assign/unassign group memberships to Jira groups. | ||
| #### Correlation configuration | ||
| The correlation configuration is used to specify which properties will be used to match an existing account within _Atlassian Jira_ to a person in _HelloID_. | ||
|
|
||
| To properly setup the correlation: | ||
|
|
||
| ## Connection settings | ||
| 1. Open the `Correlation` tab. | ||
|
|
||
| 2. Specify the following configuration: | ||
|
|
||
| | Setting | Value | | ||
| | ------------------------- | ------ | | ||
| | Enable correlation | `True` | | ||
| | Person correlation field | `` | | ||
| | Account correlation field | `name` | | ||
|
|
||
| > [!TIP] | ||
| > _For more information on correlation, please refer to our correlation [documentation](https://docs.helloid.com/en/provisioning/target-systems/powershell-v2-target-systems/correlation.html) pages_. | ||
| #### Field mapping | ||
| The field mapping can be imported by using the _fieldMapping.json_ file. | ||
|
|
||
| ### Connection settings | ||
| The following settings are required to connect to the API. | ||
|
|
||
| | Setting | Description | | ||
| | ------------ | ----------- | | ||
| | Jira Url | Example: https://customer.atlassian.net | | ||
| | Username | User with permissions to create account | | ||
| | Password | Password of the user | | ||
| | Setting | Description | Mandatory | | ||
| | ----------------- | ---------------------------------------------------------------------------------------------------------------------------- | --------- | | ||
| | Jira API URL | The URL to the Jira environment | Yes | | ||
| | Jira API Username | The Username to connect to the Jira environment | Yes | | ||
| | Jira API Token | The API token to connect to the Jira environment | Yes | | ||
| | IsDebug | When toggled, extra logging is shown. Note that this is only meant for debugging, please switch this off when in production. | No | | ||
|
|
||
| ## Getting help | ||
| > _For more information on how to configure a HelloID PowerShell connector, please refer to our [documentation](https://docs.helloid.com/hc/en-us/articles/360012518799-How-to-add-a-target-system) pages_ | ||
|
|
||
| > _If you need help, feel free to ask questions on our [forum](https://forum.helloid.com)_ | ||
| ## Setup the connector | ||
| ### API token | ||
| Before you can connect to the Atlassian API and send requests, you need to register a new API token. This token serves as your gateway to the API, enabling you to establish connections and manage permissions effectively. To generate your API token, please refer to the instructions provided by Atlassian: [Manage API tokens for your Atlassian account](https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/) | ||
|
|
||
| ### Permissions | ||
| The Jira REST API operates under the same access restrictions as the standard Jira web interface. This means that accessing Jira via the API requires proper authentication and authorization. If you attempt to access resources without proper permissions, you will encounter similar limitations as when accessing Jira through its web interface. In essence, your access via the Jira REST API mirrors your access privileges within the Jira environment. | ||
|
|
||
| ## Getting help | ||
| > [!TIP] | ||
| > _For more information on how to configure a HelloID PowerShell connector, please refer to our [documentation](https://docs.helloid.com/en/provisioning/target-systems/powershell-v2-target-systems.html) pages_. | ||
| https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-users/#api-rest-api-3-user-post | ||
| > [!TIP] | ||
| > _If you need help, feel free to ask questions on our [forum](https://forum.helloid.com)_. | ||
| # HelloID Docs | ||
| ## HelloID docs | ||
| The official HelloID documentation can be found at: https://docs.helloid.com/ |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,35 +1,44 @@ | ||
| [ | ||
| { | ||
| "key": "url", | ||
| "type": "input", | ||
| "defaultValue": "", | ||
| "templateOptions": { | ||
| "label": "Jira API Url", | ||
| "placeholder": "Enter the url", | ||
| "description": "https://customer.atlassian.net", | ||
| "required": true | ||
| } | ||
| }, | ||
| { | ||
| "key": "username", | ||
| "type": "input", | ||
| "defaultValue": "", | ||
| "templateOptions": { | ||
| "label": "Jira API Username", | ||
| "placeholder": "Enter the username", | ||
| "description": "", | ||
| "required": true | ||
| } | ||
| }, | ||
| { | ||
| "key": "password", | ||
| "type": "input", | ||
| "defaultValue": "", | ||
| "templateOptions": { | ||
| "label": "Jira API Password", | ||
| "type": "password", | ||
| "placeholder": "Please enter a password", | ||
| "required": true | ||
| } | ||
| { | ||
| "key": "url", | ||
| "type": "input", | ||
| "defaultValue": "", | ||
| "templateOptions": { | ||
| "label": "Jira API Url", | ||
| "placeholder": "Enter the url", | ||
| "description": "https://customer.atlassian.net", | ||
| "required": true | ||
| } | ||
| ] | ||
| }, | ||
| { | ||
| "key": "username", | ||
| "type": "input", | ||
| "defaultValue": "", | ||
| "templateOptions": { | ||
| "label": "Jira API Username", | ||
| "placeholder": "Enter the username", | ||
| "description": "", | ||
| "required": true | ||
| } | ||
| }, | ||
| { | ||
| "key": "token", | ||
| "type": "input", | ||
| "defaultValue": "", | ||
| "templateOptions": { | ||
| "label": "Jira API Token", | ||
| "type": "password", | ||
| "placeholder": "Please enter an API Token", | ||
| "required": true | ||
| } | ||
| }, | ||
| { | ||
| "key": "isDebug", | ||
| "type": "checkbox", | ||
| "defaultValue": false, | ||
| "templateOptions": { | ||
| "label": "Toggle debug logging", | ||
| "required": false | ||
| } | ||
| } | ||
| ] |
Oops, something went wrong.