Authentication and Authorization

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

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="baz", 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.

Users and Roles

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

Metamug User Table Structure

bazfoo

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

Metamug User Role Table Structure

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

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

Considering you have a user (foo,bar) entitled to a role baz, you need to make the following entry.

insert into usr(user_name, pass_word) values("foo", "bar");
insert into usr_role (role_name, user_id) values("baz", 1);

Roles Screen

The console provides a user-role management screen which enables creation of roles and assignment of roles to existing users as well as setting them as auth attribute in a resource.

Roles Screen

Assigning roles to users using the roles screen internally creates entries in the usr_role table mentioned above.

Backend Properties

You can add auth queries required for BASIC and BEARER authentication on backend properties page.

Metamug Config table

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

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

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

To set sub,aud and exp you can write a query inside mtg_config table entry 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.

Note: These two queries are already configured as per usr and usr_role tables. If you use these two tables for storing users and their roles, auth properties need not be changed.

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. The 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="baz">

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.

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.

Authorization Error

We proceed with sending requests with HTTP Basic or Token Based under OAuth 2. If you try to access a resource without Authorization header, when auth is enabled, you will get the following error.

{
    "message": "Forbidden access to resource",
    "status":403
}

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.

JS Example

Javascript has btoa function that does Base64 encoding.

req.setRequestHeader("Authorization", "Basic " + btoa('foo' + ":" + 'bar'));
//Authorization: Basic Zm9vOmJhcg==
curl -H "Authorization: Basic Zm9vOmJhcg==" http://localhost:7000/movie/v1.0/resource

Token Based Authentication (JWT)

In this scheme, the app requests a token from the backend as follows using the user credentials (foo,bar).

curl -d "auth=bearer&userid=foo&password=bar" -X POST http://localhost:7000/{backend_name}/

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

{
    "token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxIiwiYXVkIjoiYmF6IiwiaXNzIjoibWFzb24ubWV0YW11Zy5uZXQiLCJleHAiOjE1NjE0NDk4NjYsImlhdCI6MTU1MzY1NDA2NjA5NCwianRpIjoiODFjZDVhMzYtZmVmYi00NDA3LTk5NmUtYjc0OTM5Y2Q5ZmFmIn0=.8SrZr998LYJ0v/MOh75tHtyISp+UipfRbammjFTlZ6I=",
    "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 eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxIiwiYXVkIjoiYmF6IiwiaXNzIjoibWFzb24ubWV0YW11Zy5uZXQiLCJleHAiOjE1NjE0NDk4NjYsImlhdCI6MTU1MzY1NDA2NjA5NCwianRpIjoiODFjZDVhMzYtZmVmYi00NDA3LTk5NmUtYjc0OTM5Y2Q5ZmFmIn0=.8SrZr998LYJ0v/MOh75tHtyISp+UipfRbammjFTlZ6I=

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.

The curl request looks as follows

curl -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxIiwiYXVkIjoiYmF6IiwiaXNzIjoibWFzb24ubWV0YW11Zy5uZXQiLCJleHAiOjE1NjE0NDk4NjYsImlhdCI6MTU1MzY1NDA2NjA5NCwianRpIjoiODFjZDVhMzYtZmVmYi00NDA3LTk5NmUtYjc0OTM5Y2Q5ZmFmIn0=.8SrZr998LYJ0v/MOh75tHtyISp+UipfRbammjFTlZ6I=" http://localhost:7000/movie/v1.0/resource

Payload

{
  "sub": "1",
  "aud": "baz",
  "iss": "mason.metamug.net",
  "exp": 1561449866,
  "iat": 1553654066094,
  "jti": "81cd5a36-fefb-4407-996e-b74939cd9faf"
}