I was working with a colleague on creating a custom connector to talk to Fresh Service. He did most of the hard work, I got involved towards the end to figure out some authentication stuff.
With Fresh, for instance, to authenticate you need to send an API key.
|
1 |
curl -v -u apikey:X -H "Content-Type: application/json" -X GET 'https://domain.freshservice.com/api/v2/tickets' |
The username is the API key you get from their website, the password is X (capital X).
The equivalent of the above in PowerShell would be:
|
1 2 3 4 5 6 7 8 9 |
$apiKey = "whatever" $base64AuthInfo = [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes(("{0}:{1}" -f $apiKey,"X"))) $freshHeaders = @{ "Authorization" = "Basic $base64AuthInfo" "Content-Type" = "application/json" } Invoke-RestMethod -Headers $freshHeaders -Method 'GET' -Uri "${freshBaseUrl}/api/v2/tickets" |
Basically you have to convert the “API Key:X” bit to Base64 and then send it along.
So far so good. But how about when using a custom connector? When creating one you can select Basic authentication but that just prompts the user to add the API Key and X when creating a connection using the custom connector. Which might be fine too, coz you’d want each user to use their own API key after all.
But we wanted to provide the connector as something users can use without entering their key. We have a “service account” in Fresh and want to use its API key as that’s got additional rights. But at the same time we don’t want to open it up for everyone. A custom connector is perfect in that respect because we can expose just the API actions we need… if only we could figure a way of putting this key somewhere!
The trick is to set the authentication as “No authentication”.
And then, in the Definition section, under Policies, create a new policy.
And here, give it a name, then choose the “Set HTTP header” template.
After that fill as follows:
Replace the bit after “Basic” with the Base64 encoded value of <username>:<password>. Which in the case of Fresh is APIKey:X.
That’s it. Now your custom connector won’t prompt users for an API key.
If you export the connector, this info isn’t exported. When you import it elsewhere you will have to add it again. Which is good.
There is a small catch in this though, in that when you publish the custom connector in an environment with View rights, even though the edit icon is grayed out:
Someone can still click the three dots, go to View properties:
And notice the “Edit” button there? Yeah… they can click it to see everything!
Users can’t change anything, but this leaves the API key you added above visible to them.
Which is a bummer of course. I’ve raised a ticket with Microsoft to see if we can do something about this. There’s no reason why someone with View rights should be able to see inside the custom connector. Technically, I understand, they are still only viewing the information.. but still, that’s not what one was expecting.
Another weird behaviour with custom connectors.
If you add it within an environment it respects the share permissions. As in, only those whom you make it available to as View or Edit or View & Share can actually see it (albeit also see inside it as above). On the other hand, if you add the custom connector to a solution in the environment – be it adding directly, or adding to the environment and then importing into the solution – then everyone can now see the custom connector and also edit/ delete it. Crazy!
So, always import custom connectors into your environment and not solution.