@itentialopensource/adapter-aws_cognito_identity_provider 0.1.1

package/.eslintignore

@@ -0,0 +1,5 @@
+.nyc_output/*
+backup/*
+coverage/*
+out/*
+adapter_modifications/*

package/.eslintrc.js

@@ -0,0 +1,18 @@
+module.exports = {
+  env: {
+    browser: true,
+    es6: true,
+    node: true
+  },
+  extends: 'airbnb-base',
+  plugins: [
+    'json'
+  ],
+  parserOptions: {
+    sourceType: 'module'
+  },
+  rules: {
+    'max-len': 'warn',
+    'comma-dangle': ['error', 'never']
+  }
+};

package/.jshintrc

@@ -0,0 +1,3 @@
+{
+  "esversion": 6
+}

package/AUTH.md

@@ -0,0 +1,108 @@
+## Authenticating AWS Cognito Identity Provider Adapter 
+
+This document will go through the steps for authenticating the AWS Cognito Identity Provider adapter with AWS Signature 4 Authentication. Properly configuring the properties for an adapter in IAP is critical for getting the adapter online. You can read more about adapter authentication <a href="https://docs.itential.com/opensource/docs/authentication" target="_blank">HERE</a>. 
+
+### AWS Authentication
+The AWS Cognito Identity Provider adapter requires AWS Authentication therefore the `auth_method` should be set to `aws_authentication`. The adapter utilizes AWS signature 4 authentication. There are three mechanisms for doing this. 
+
+The first way is using a "service" account and its AWS keys to authenticate as that account. In this case, you will get the aws_access_key, aws_secret_key, and aws_session_token from AWS and configure them into the adapter service instance as shown below.
+
+The second way is using AWS STS. this still requires a "service" account and its AWS keys to authenticate as that account. In this case, you will get the aws_access_key, aws_secret_key, and aws_session_token from AWS and configure them into the adapter service instance as shown below. In addition, you will provide STS paramaters in the workflow tasks that tell the adapter the role you want used on the particular call.
+
+The third authentication method is to use an IAM role. With this method, you do not need any authentication keys as the adapter will utilize an "internal" AWS call to get the things that it needs for authentication. Since the adapter needs to make the call to this "internal" AWS IP address, the IAP server needs to be where it has access to that address or you will not be able to use this method.
+
+If you change authentication methods, you should change this section accordingly and merge it back into the adapter repository.
+
+### AWS Signature 4 Service Account Authentication
+The AWS Cognito Identity Provider adapter requires AWS Signature 4 Authentication. If you change authentication methods, you should change this section accordingly and merge it back into the adapter repository.
+
+STEPS  
+1. Ensure you have access to a AWS Cognito Identity Provider server and that it is running
+2. Follow the steps in the README.md to import the adapter into IAP if you have not already done so
+3. Use the properties below for the ```properties.authentication``` field
+```json
+"authentication": {
+  "auth_method": "aws_authentication",
+  "aws_access_key": "aws_access_key",
+  "aws_secret_key": "aws_secret_key",
+  "aws_session_token": "aws_session_token"
+}
+```
+you can leave all of the other properties in the authentication section, they will not be used for AWS Cognito Identity Provider authentication.
+4. Restart the adapter. If your properties were set correctly, the adapter should go online. 
+
+### AWS Security Token Service
+The AWS Cognito Identity Provider adapter also supports AWS Security Token Service (STS) Authentication. For using this authentication, you need to use the calls in the Adapter that have the STSRole suffix on them and pass the STS information into the method. You will still need to provide the relevant `aws_secret_key` and `aws_access_key` as described above. Below is an example of the data required in the `sts` tasks:
+
+```json
+{
+  "RoleArn": "arn:aws:iam::1234567:role/my_role",
+  "RoleSessionName": "mySession"
+}
+```
+
+The AWS STS Authentication goes to the AWS STS Service endpoint in order to validate that the primary "service" account the adapter has authenticated with has the permission to assume the role. This call is made to sts.amazonaws.com or a regional sts sevice (e.g. sts.us-east-1.amazonaws.com). By default traffic to these endpoints will go out through the Internet. In the case where you would prefer these route through your network, it is possible to change the STS config for the adapter. 
+
+The proxy field should point to the AWS loadbalancer or a proxy server that forwards to AWS STS. In Itential Cloud, this can be NAT'd to your network. In addition to this, you may need to set the endpoint in order to have the STS SSL certificate validated successfully. By default the adapter will use sts regional servers. If the loadbalancer and proxy are set up for that you should be fine. If however, they point to the global STS service (sts.amazonaws.com) You will need to set the global as the endpoint or the STS certificate will be rejected due to the hosts not matching. 
+
+Region can be important as it is the region in which the STS assume role request will be processed. Each AWS partition may have one primary region for STS. In our tests, we have found that for the standard partition the STS region should be set to us-east-t but this is configurable should your primary region be different or you are working in a different AWS partition.
+
+```json
+"authentication": {
+  "aws_sts": {
+    "region": "us-east-1",
+    "endpoint": "<sts certificate endpoint>",
+    "proxy": "<proxy/loadbalancer ip>",
+  }
+}
+```
+
+### AWS IAM Role
+The AWS Cognito Identity Provider adapter also supports AWS IAM Role Authentication. For using this authentication, you need to use the calls in the Adapter that have the STSRole suffix on them and provide the role's ARN in the RoleName variable. In addition to passing the IAM Role in the task, it is possible to set an IAM Role in the Service Instance Configuration by using the `aws_iam_role` property in the authentication section and providing the role's ARN.
+
+```json
+"authentication": {
+  "auth_method": "aws_authentication",
+  "aws_iam_role": "role_arn"
+}
+```
+
+### AMAZON STEPS FOR IAM ROLE
+Increase number of hops if running IAP inside of docker on Cognito Identity Provider instance
+```bash
+aws sso login --profile aws-bota-1
+<export aws keys for CLI access>
+
+aws ec2 modify-instance-metadata-options  --instance-id i-0e150236026b7c45d  --http-put-response-hop-limit 3 --http-endpoint enabled --region us-east-1
+```
+
+Create a new role and attach to it policies:
+- go to your Cognito Identity Provider instance, select it
+- Actions->Security->Modify IAM Role
+- Click 'Create New IAM Role'
+- Create a role:
+```text
+Trusted entity type: AWS service
+Use Case: cognito-idp
+```
+
+Add desired policies to the role. 
+
+Save the role
+
+Go back to your Cognito Identity Provider instance and Actions->Security->Modify IAM Role, associate newly created role with your Cognito Identity Provider instance
+
+### Troubleshooting
+- Make sure you copied over the correct access key, secret key and session token.
+- Turn on debug level logs for the adapter in IAP Admin Essentials.
+- Turn on auth_logging for the adapter in IAP Admin Essentials (adapter properties).
+- Investigate the logs - in particular:
+  - The FULL REQUEST log to make sure the proper headers are being sent with the request.
+  - The FULL BODY log to make sure the payload is accurate.
+  - The CALL RETURN log to see what the other system is telling us.
+- Credentials should be ** masked ** by the adapter so make sure you verify the username and password - including that there are erroneous spaces at the front or end.
+- Remember when you are done to turn auth_logging off as you do not want to log credentials.
+- For IAM, you can run this on the IAP server to verify you are getting to the "internal" AWS Server
+```bash
+TOKEN=`curl -v -X PUT "http://169.254.169.254/latest/api/token" -H "X-aws-ec2-metadata-token-ttl-seconds: 21600"` && curl -v -H "X-aws-ec2-metadata-token: $TOKEN" -v http://169.254.169.254/latest/meta-data/iam/security-credentials/<rolename>
+```

package/BROKER.md

@@ -0,0 +1,211 @@
+## Integrating Aws_cognito_identity_provider Adapter with IAP Device Broker
+
+This document will go through the steps for integrating the Aws_cognito_identity_provider adapter with IAP's Device Broker. IAP Device Broker integration allows for easier interation into several of IAPs applications (e.g. Configuration Manager). Properly configuring the properties for the adapter in IAP is critical for getting the device broker integration to work. Their is additional information in the configuration section of the adapter readme. This document will go through each of the calls that are utilized by the Device Broker.
+
+### getDevicesFiltered
+getDevicesFiltered(options, callback) → This call returns all of the devices within Aws_cognito_identity_provider that match the provided filter.
+
+#### input
+
+options {object}: defines the options for the search. At current filter is the most important one. The filter can contain the device name (e.g. the options can be { filter: { name: [‘abc’,  ‘def’] }}. The adapter currently filters by doing a contains on the name(s) provided in the array and not an exact match. So deviceabc will be returned when this filter is applied. In many adapters, other options (start, limit, sort and order) are not implemented.
+
+#### output
+
+An Object containing the total number of matching devices and a list containing an array of the details for each device. For example, { total: 2, list: [ { name: ‘abc’, ostype: ‘type’, port: 80, ipaddress: ‘10.10.10.10’ }, { name: ‘def’, ostype: ‘type2’, port: 443, ipaddress: ‘10.10.10.15’ }] }
+
+The fields name and ostype are required by the broker and should be mapped through properties to data from the other system. In addition, ipaddress and port should also be mapped as it is utilized by some north bound IAP applications (e.g. Config Manager). There are other fields that can be set as well but consider these the minimal fields.
+
+Below is an example of how you may set up the properties for this call.
+
+```json
+"getDevicesFiltered": [
+  {
+    "path": "/{org}/get/devices",
+    "method": "GET",
+    "pagination": {
+      "offsetVar": "",
+      "limitVar": "",
+      "incrementBy": "limit",
+      "requestLocation": "query"
+    },
+    "query": {},
+    "body": {},
+    "headers": {},
+    "handleFailure": "ignore",
+    "responseDataKey": "",
+    "requestFields": {
+      "org": "555"
+    },
+    "responseFields": {
+      "name": "{hostField}",
+      "ostype": "{osField}",
+      "ostypePrefix": "system-",
+      "ipaddress": "{attributes.ipaddr}",
+      "port": "443"
+    }
+  },
+  {
+    "path": "/{org}/get/devices",
+    "method": "GET",
+    "query": {},
+    "body": {},
+    "headers": {},
+    "handleFailure": "ignore",
+    "responseDataKey": "",
+    "requestFields": {
+      "org": "777"
+    },
+    "responseFields": {
+      "name": "{hostField}",
+      "ostype": "{osField}",
+      "ostypePrefix": "system-",
+      "ipaddress": "{attributes.ipaddr}",
+      "port": "443",
+      "myorg": "{orgField}"
+    }
+  }
+]
+```
+
+Notice with the path, there is a variable in it ({org}). This variable must be provided in the data available to the call. For getDevicesFiltered this means the requestFields as a static value. In other calls, it may also come from the result of the getDevicesFiltered call.
+
+Notice with the responseFields, it wants the IAP data key as the key and where it is supposed to find the data in the response as the value. You can use nested fields in the response object using standard object notation. You can also add static data as shown in the port field. Finally, you can append data to the response from the requestInformation using its key (e.g. org). The ostypePrefix is a special field that allows you to add static data to the ostype to help define the system you are getting the device from.
+
+Notice here that you can also have multiple calls that make up the results provided to the Device Broker. In this example we are making calls to two different organizations and returning the results from both. 
+
+### isAlive
+isAlive(deviceName, callback) → This call returns whether the device provided is operational.
+
+input
+
+deviceName {string}: the name of the device to get details of. The adapter will always call getDevicesFiltered first with this name in the filter in order to get any additional details it needs for this call (e.g. id).
+
+output
+
+A boolean value. This usually needs to be determined from a particular field in the data returned from the other system. This is where definind a status value and a status field is critical to properly configuring the call.
+
+Below is an example of how you may set up the properties for this call.
+
+```json
+"isAlive": [
+  {
+    "path": "/{org}/get/devices/{id}/status",
+    "method": "GET",
+    "query": {},
+    "body": {},
+    "headers": {},
+    "handleFailure": "ignore",
+    "statusValue": "online",
+    "responseDataKey": "",
+    "requestFields": {
+      "org": "{myorg}",
+      "id": "{name}"
+    },
+    "responseFields": {
+      "status": "{status}"
+    }
+  }
+]
+```
+
+Notice with the requestFields, it will use the org and name that it got from the response of the getDevicesFiltered call to complete the path for the call.
+
+Notice with the responseFields, it use the status field that came back and test to see if the value is online since that is what you defined as the statusValue. If it is it will return true otherwise it will return false.
+
+You could have multiple calls here if needed but generally that will not be the case.
+
+### getConfig
+getConfig(deviceName, format, callback) → This call returns the configuration for the device. This can be a simple call or a complex/multiple calls to get all of the “configuration” desirable.
+
+input
+
+deviceName {string}: the name of the device to get details of. The adapter will always call getDevicesFiltered first with this name in the filter in order to get any additional details it needs for this call (e.g. id).
+
+format {string}: is an optional format you want provided back. Most adapters do not support formats by default and just return the “stringified” json object.
+
+output
+
+An object containing a response field which has the value of the stringified config (e.g. { response: ‘stringified configuration data’ }
+
+Below is an example of how you may set up the properties for this call.
+
+```json
+"getConfig": [
+  {
+    "path": "/{org}/get/devices/{id}/configPart1",
+    "method": "GET",
+    "query": {},
+    "body": {},
+    "headers": {},
+    "handleFailure": "ignore",
+    "responseDataKey": "",
+    "requestFields": {
+      "org": "{myorg}",
+      "id": "{name}"
+    }
+    "responseFields": {}
+  },
+  {
+    "path": "/{org}/get/devices/configPart2",
+    "method": "GET",
+    "query": {},
+    "body": {},
+    "headers": {},
+    "handleFailure": "ignore",
+    "responseDataKey": "",
+    "requestFields": {
+      "org": "{myorg}"
+    }
+    "responseFields": {}
+  }
+]
+```
+
+The example above shows multiple calls. With the handleFailure property set to ignore, if one of the calls fails, the adapter will still send the response with that configuration missing. If you want it to fail set the handleFailure property to fail.
+
+There is no limit on the number of calls you can make however understand that the adapter will make all of these calls prior to providing a response so there can be performance implications.
+
+### getDevice - may be deprecated
+getDevice(deviceName, callback) → This call returns details of the device provided. In many systems the getDevicesFiltered only returns summary information and so we also want a more detailed call to get device details.
+
+input
+
+deviceName {string}: the name of the device to get details of. The adapter will always call getDevicesFiltered first with this name in the filter in order to get any additional details it needs for this call (e.g. id).
+
+output
+
+An Object containing the details of the device. The object should contain at least the same information that was provided in the getDevicesFiltered call (e.g. the fields name, ostype, port and ipaddress should be mapped in the adapter properties to data from the other system) and may contain many more details about the device.
+
+Below is an example of how you may set up the properties for this call.
+
+```json
+"getDevice": [
+  {
+    "path": "/{org}/get/device",
+    "method": "GET",
+    "query": {
+      "id": "{id}"
+    },
+    "body": {},
+    "headers": {},
+    "handleFailure": "ignore",
+    "responseDataKey": "",
+    "requestFields": {
+      "org": "{myorg}",
+      "id": "{name}"
+    },
+    "responseFields": {
+      "name": "{hostField}",
+      "ostype": "{osField}",
+      "ostypePrefix": "system-",
+      "ipaddress": "{attributes.ipaddr}",
+      "port": "443",
+      "myorg": "{orgField}"
+    }
+  }
+]
+```
+
+In this example, we show a query parameter being used. Notice that the value is still provided via the requestFields and then like with the path, we use curly braces in the query to denote a variable. The body and header variables work in this same manner.
+
+You could have multiple calls here if needed but generally that will not be the case.