Securely invoking a client endpoint in Ballerina

Authentication of HTTP endpoints

Chanaka Lakmal
May 21, 2018 · 3 min read
Image for post
Image for post
Source: https://www.trisoft.co.uk

NOTE: All the Ballerina codes in this article are tested and compatible with Ballerina version 0.980.0

What is Ballerina

Ballerina is a cloud-native programming language whose syntax and run-time address the difficult problems of integration.

What is a client endpoint

Ballerina uses client endpoints to connect to external systems. With the use of an endpoint, it handles security and makes the end user’s life easier by avoiding the external API behavior. Simply, this is a wrapper of external API.

What is securely invoking

Almost all the client endpoints are secured with different kind of authentication schemes like Basic, HMAC, OAuth 1.0, OAuth 2.0, etc. Some endpoints even support multiple authentication schemes. Simply, securely invoking means how we can connect to those endpoints with the required authentication schemes.

Prerequisites

Before starting, you have to setup your machine with Ballerina. Please refer to Ballerina’s Getting Started Guide.

Once you have successfully installed Ballerina, execute ballerina-v command to ensure it works. This should display the Ballerina version you installed.

Let’s Start

The Ballerina HTTP Client Endpoint has a new type called AuthConfig which is implemented for securely invoking an HTTP endpoint. Hence, you do not need to worry about the authentication headers of your HTTP request.

public type AuthConfig {
AuthScheme scheme,
string username,
string password,
string accessToken,
string refreshToken,
string refreshUrl,
string consumerKey,
string consumerSecret,
string tokenUrl,
string clientId,
string clientSecret,
};

The above implementation, currently you can securely invoke an HTTP client endpoint with following authentication schemes.

  1. Basic authentication
  2. OAuth 2.0 authentication
  3. JWT authentication

Basic Authentication

This is the most simple way to deal with authentication. Here we use a special HTTP header where we add base64 encoded value of ‘username:password’ as a part of the header value.

GET / HTTP/1.1
Host: example.org
Authorization: Basic YmF0bRFuOmhdG1hbkAxNjN==

Without worrying about those you have to just pass your username and password mentioning scheme as ‘http:BASIC_AUTH’. It is simple as that in Ballerina.

Sample for basic authentication

OAuth 2.0 Authentication

This is a somewhat complex but highly secured way to deal with authentication. Here we use a special HTTP header where we just add the bearer token as a part of the header value. It is the same as in bearer token authentication scheme. But the difference is that the access token can be manually revoked or automatically expired after a time period. In order to get a new access token and proceed, there is a special mechanism in OAuth 2.0 workflow.

GET / HTTP/1.1
Host: example.org
Authorization: Bearer Uwge6OmhNhObkdG1GeaeAxdJd8Bks3j

Without worrying about those you have to just pass your access token, client id, client secret, refresh token and refresh url mentioning scheme as ‘http:OAUTH2’.

Sample for OAuth 2.0 authentication

JWT Authentication

This is also somewhat complex but a commonly used method to deal with authentication. Without worrying on those you have to set the token, scheme and authToken into runtime context as represented in setJwtTokenToAuthContext() method of following code sample and mentioning scheme as ‘http:JWT_AUTH’ at the endpoint declaration part.

Sample for JWT authentication

Demo

You can refer the following .bal file which has a summary of all the authentication schemes mentioned above.

Happy coding with Ballerina !

Ballerina-Techblog

The Ballerina Tech Blog

Medium is an open platform where 170 million readers come to find insightful and dynamic thinking. Here, expert and undiscovered voices alike dive into the heart of any topic and bring new ideas to the surface. Learn more

Follow the writers, publications, and topics that matter to you, and you’ll see them on your homepage and in your inbox. Explore

If you have a story to tell, knowledge to share, or a perspective to offer — welcome home. It’s easy and free to post your thinking on any topic. Write on Medium

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store