Authentication and Authorization

Before proceeding to the following section, the reader must be familiar with the following:

HTTP Basic Authorization

Auth

Metamug provides role-based authentication and authorization of resources. If the requested resource has 'auth' attribute with a role value for e.g. auth=" supplier", then the request must send authorization header. If the user fails to send or sends incorrect credentials the server will respond with 401 message.

If the authenticated user does not have access to the resource i.e. not provided the role of the resource, the server will respond back with 403 Forbidden error. user - authentication

User Group

Let's have a table called usr to store information about the user and it will be used for authentication.

1. user_id
2. user_name
3. pass_word
4. created_on

The second table is usr_role table, this table is used to authorize the authenticated user to a resource using a role. The role_name is used in the resource file to map roles to an auth attribute.

1. id
2. role_name
3. user_id
4. created_on

The configuration table relies on the querying the user and user_role table as per this example to check for authentication and authorization requests.

For a resource file with auth="supplier", following entry needs to be made in the user and user_role table in the backend schema as follows.

insert into usr (user_id, user_name, pass_word) values (1, 'user1', 'pass1')
insert into usr_role (id, role_name, user_id) values(1, 'supplier', 1)

Config table

Below is the structure of the mtg_config table. This table is required for authentication.

In the auth_scheme you can write Basic or Bearer and also the auth_query will differ depending upon this scheme.

insert into mtg_config (auth_scheme, auth_query) VALUES ('Basic', 'select r.user_id,r.role_name from usr_role r inner join usr u on r.user_id=u.user_id WHERE u.user_name=$user AND u.pass_word=$pass')

The above insert record is for Basic.

The variables $user and $pass will automatically be replaced with the values sent in the Authorization header.

Inside Resource

After authentication and authorization, the resource file is given access. The accessed resource file is provided with $uid as the authorized user id. $uid represents the logged-in user. $uid can be used to access information related to the logged-in user.following entry needs to be made in the XML file to give access to the logged in user in the backend schema as follows.

<Resource xmlns="http://xml.metamug.net/resource/1.0" v="1.0" auth="supplier">

After auth is configured successfully. You can check the resource listing in the console it will show an auth badge next to the name of the resource.

Sending requests with auth enabled

We proceed with sending requests with HTTP Basic or Token Based under OAuth 2. These requests are to be sent over SSL to ensure TLS end-to-end encryption. We don't encourage using APIs without HTTPS under suggested auth scheme.

HTTP Basic Auth

Username and password must be sent in form of Base64 encoded under the authorization header as follows.

Authorization: Basic BASE64(username:password)

The basic keyword in the header value tells the server the token followed by it uses Basic Auth scheme. Metamug matches the username and password after decoding the values and provides access to the requested resource accordingly.

The implementation conforms to RFC 2617 for Basic Auth.

Request Header in Javascript

btoa("john:maven")

"am9objptYXZlbg=="

req.setRequestHeader("Authorization", "Basic " + btoa(username + ":" + password));

Token Based Auth

In this scheme, the app requests a token from the backend as follows.

POST  https://api.metamug.com/{backend}

auth=bearer&userid=foo&password=pass

The POST request made to the backend will generate the token in the response.

{
    "token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMzMyNCIsImF1ZCI6ImFkbWluIiwiaWF0IjoxNTEwNDI5NDI0LCJleHAiOjE1MTIyMDMyMjMsImlzcyI6ImFwaS5tZXRhbXVnLmNvbSIsImp0aSI6ImFmZGE5M2ZhZGZhaGZhNzMyMmZhY2FnaGlvZmE4OGYzMiJ9.deXzdDm2lfSoRE-hyAfY94WZE6_ExuBzY-Izb7E-hog",
    "type":"Bearer"
}

The app must store this token to make subsequent requests. This token shall be invalidated when expiry timestamp is reached.

Bearer Token Header

The below is the example of Token Auth header.

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMzMyNCIsImF1ZCI6ImFkbWluIiwiaWF0IjoxNTEwNDI5NDI0LCJleHAiOjE1MTIyMDMyMjMsImlzcyI6ImFwaS5tZXRhbXVnLmNvbSIsImp0aSI6ImFmZGE5M2ZhZGZhaGZhNzMyMmZhY2FnaGlvZmE4OGYzMiJ9.deXzdDm2lfSoRE-hyAfY94WZE6_ExuBzY-Izb7E-hog

The token is a RFC 7519 JWT compliant token. You can decode and use the information in the payload. Paste the token on JWT.io to see its contents.

Payload

{
  "sub": "13324",
  "aud": "admin",
  "iat": 1510429424,
  "exp": 1512203223,
  "iss": "api.metamug.com",
  "jti": "afda93fadfahfa7322facaghiofa88f32"
}

To set sub,aud and exp you can write a query inside mtg_config table entry

insert into mtg_config (auth_scheme, auth_query) VALUES ('Bearer','select r.user_id as sub,r.role_name as aud from usr_role r inner join usr u on r.user_id=u.user_id WHERE u.user_name=$user AND u.pass_word=$pass')

The above insert record is for Bearer. The following three values in the payload iat, iss and jti are system generated and you cannot set them using config query.