What's Basic Auth?
Basic authentication is one of the most widespread authentication schemes out there and is used by nearly every API. But what is Basic Auth and how does one do anything with it? In this GIG post, we'll walk through what Basic Auth is and where it's used in the xMatters ecosystem - then we'll see how it works in a real integration.
Wikipedia has a pretty succinct explanation of what Basic Auth is:
HTTP Basic authentication (BA) implementation is the simplest technique for enforcing access controls to web resources because it doesn't require cookies, session identifiers, or login pages; rather, HTTP Basic authentication uses standard fields in the HTTP header, obviating the need for handshakes.
What's Good About Basic Auth?
A couple of notes here on why Basic Auth is good for integrations:
- Additionally, since the credentials are passed via headers in the request, no special handshake or other additional overhead is required. The entire package is sent and processed.
As of June 2016, all xMatters REST APIs use basic authentication (SOAP web services are a different story and we'll leave those out of this discussion). So let's dive into using this for making a REST call.
Creating the Header Value
The header value is simply the username and password concatenated with a colon. Then the whole thing is encoded in Base 64 and finally all that is appended to the word "Basic" with a space. Base64 encoding is the process of translating a string of characters into a smaller set of characters that won't interfere with URLs, JSON and other methods for passing data from one place to another.
Note that this isn't encryption, so it's rather easy to decode this value and view the password in plain text. This might seem like a glaring security flaw, but remember that all of the xMatters APIs use HTTPS which means the entire payload, including the headers, is sent over an encrypted channel.
To put it all together, if my username is "chef" and my password is "eye bake for $$$!", then I would base64 encode this value:
chef:eye bake for $$$!
That latter results in...
... and my full header would look like this:
"Authorization": "Basic Y2hlZjpleWUgYmFrZSBmb3IgJCQkIQ=="
How to Enable Authentication in Inbound Integration Scripts
One other place Basic Auth is used is in the Inbound Integration Scripts in the Integration Builder. You can enable Authentication to an inbound script by clicking the Authentication button (for more details, click here):
This displays a dialog showing the automatically-generated username and password. Be careful though! The password is only shown once, so make sure you put it in a (temporary) place until you can get it properly encrypted or stored.
Using these two values, you can then generate the Basic Auth header using base64 encoding.
A real world example is Sumo Logic. To allow for authentication when using the Webhooks, you must enter the exact header that will be sent. So, after generating the username and password and then encoding the values, paste in the result with "Basic" into the Sumo Logic UI:
Great! I hope you've learned a bit about Basic Auth and how it is used in relation to the xMatters APIs, but if you didn't, here's a Quokka... and, more seriously, post a comment if you'd like me to clarify something.