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.
- user_id
- user_name
- pass_word
- 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.
- id
- role_name
- user_id
- 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.