GIG: Generating Basic Auth Headers

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:

• Since Basic Auth doesn't require cookies or session tokens, it's a one shot deal: either you send the right credentials and your request is completed or you don't and your request is rejected. In other authentication schemes that use cookies or tokens, one request is made to get a token or session ID, and then that token is used in subsequent requests to the API. 
• 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.

Example

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...

Y2hlZjpleWUgYmFrZSBmb3IgJCQkIQ==

... and my full header would look like this:

"Authorization": "Basic Y2hlZjpleWUgYmFrZSBmb3IgJCQkIQ==" 

For this example, I used an online base64 encoder, but you can also fire up the console in your browser and use the btoa function in javascript:

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 select an authentication type for an inbound integration when creating it. For more information, check our online help for inbound integrations.

Example

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:

Questions? 

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.