Create a Secret

API credentials for both endpoint systems must be created and added to the Secret Service. This allows the data flow to access API tokens, etc. securely, without having them hardcoded into the flow configuration, making them visible to anyone with read access to the flow. This also allows the credentials to be stored encrypted at rest.

Open the Postman Collection.
Open Secret Service > POST: Create a secret.
Ensure the appropriate “Environment” is selected (top-right)
In the “body” tab, enter the appropriate data to create a secret of the desired type. Make sure to include tenant ownership.

Example of an API Key Secret:

{
  "data": {
    "value": {
     "key": "<key>"
    }
    "tenant": "<tenant id>",
    "type": "API_KEY",
    "name": "<some identifiable name>",
  }
}

Example of a Bearer Token:

{
  "data": {
    "value": {
      "headerName": "Authorization",
      "key": "Bearer <token>"
    },
    "tenant": "<tenant id>",
    "type": "API_KEY",
    "name": "<some identifiable name>",
  }
}

Example of Basic Authentication:

{
  "data": {
    "value": {
      "username": "<username>",
      "passphrase": "<password>"
    },
    "tenant": "<tenant id>",
    "type": "SIMPLE",
    "name": "<some identifiable name>",
  }
}

Example of Oauth Token:

{
    "data": {
        "name": "<some identifiable name>",
        "type": "OA2_AUTHORIZATION_CODE",
        "tenant": "<tenant id>",
        "value": {
            "authClientId": "<auth client>",
            "refreshToken": "<refresh token>",
            "accessToken": "<access token>",
            "scope": "<oauth scope values>",
            "expires": ""
        }
    }
}

Click “Send” to create the secret.
Save the secret ID. You’ll use it to refer to that credential when configuring API calls in your flows.

It’s important to be very careful about who has access to secrets. These hold potentially powerful credentials to your users’ systems. Limit access for both people and applications to the bare minimum necessary to support your integrations.

Oauth Clients

The OIH Secret Service uses "auth clients" to facilitate the Oauth flow and create an Oauth secret.

Example of Auth Client:

{
  "data": {
    "clientId": "<API key>",
    "clientSecret": "<API secret>",
    "redirectUri": "<redirect URI>",
    "endpoints": {
        "auth": "<authorization URL>",
        "token": "<access token URL>"
    },
    "tenant": "<tenant id>",
    "type": "OA2_AUTHORIZATION_CODE",
    "name": "<some identifiable name>",
  }
}

Oauth via Client Credentials

For systems that support Oauth authentication via Client Credentials grant type, you can create an OIH auth client and secret. You use the type SESSION_AUTH for both the auth client and the secret.

To enable this authentication type, you must first set up an auth client for the external system. Most importantly, this defines how to get a token. It will be shared by all end users who are authenticating to that system. Then on a per end user basis, you set up a secret that interacts with the the auth client to refresh the bearer token that gets used at runtime for API authentication.

The following is an example of such a setup, using what would be required for Microsoft Dynamics 365 Authentication. Note the tokenized refences to fields as {{fields.field_name}}. These are placeholders for the values that are stored in each end client's individual secret under inputFields (see example below).

Example of the Auth Client:

{
        "_id": "64de8d36063cbe20ac1e93e7",
        "tokenPath": "access_token",
        "expirationPath": "expires_in",
        "endpoints": {
            "auth": {
                "requestFields": [
                    {
                        "key": "grant_type",
                        "value": "client_credentials"
                    },
                    {
                        "key": "scope",
                        "value": "{{fields.scope}}"
                    },
                    {
                        "key": "client_id",
                        "value": "{{fields.clientid}}"
                    },
                    {
                        "key": "client_secret",
                        "value": "{{fields.secret}}"
                    }
                ],
                "authType": "FORM_AUTH",
                "url": "https://login.microsoftonline.com>/{{fields.tenantid}}/oauth2/v2.0/token"
            }
        },
        "name": "Dynamics 365 Session Auth Client",
        "type": "SESSION_AUTH",
        "fields": []
    }

The following is a secret that will use the auth client to retrieve an auth token. Note that the inputFields are encrypted, so if you GET the secret via the API, they will be obfuscated.

{
    "name": "Dynamics 365 Session Auth Secret",
    "type": "SESSION_AUTH",
    "tenant": "<the end user's tenant ID>",
    "value": {
        "authClientId": "<the ID of the above auth client>",
        "inputFields": {
            "scope": "<the end user's actual scope>",
            "clientid": "<the end user's actual client ID>",
            "secret": "<the end user's actual client secret>"
        }
    }
}