Securely invoking a Client Endpoint in Ballerina
Authentication of HTTP endpoints
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.
- Basic authentication
- OAuth 2.0 authentication
- 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.
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 Uwge6OmhNhObkdG1GeaeAxdJd8Bks3jWithout 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’.
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.
Demo
You can refer the following .bal file which has a summary of all the authentication schemes mentioned above.
Happy coding with Ballerina !
Further Reading
The following article explains how to write a client endpoint in Ballerina. Here the authentication of client endpoint handles internally when the client endpoint gets initialized.
