Table of Contents

Security

Every API request must contain an access token in order to keep the communication safety. MibServer API security is based on OAuth 2.0 Authorization Framework (RFC 6749).

1 - Application types

Before using the API you must create your Application inside MibServer web interface and choose the right Application Type among three distinct options below.

  • Interactive Confidential: user-interactive applications in which authentication workflow is kept entirely in server-side, such as ASP.NET, JSP, Python, Rails, Node.js, PHP, Perl.

  • Interactive Public: user-interactive applications in which authentication workflow is made at client-side, such as jQuery/Javascript code, Silverlight, Flash, WPF, Windows Forms, Windows Store app or mobile applications (iOS, Android, Windows Phone). Less secure than previous, but easier implementation. Should be avoided if possible because does not provide Application authentication and the Access Token is visible from the client-side.

  • Non-Interactive: Services, agents, routines, triggers, jobs. Applications without user entry or interactivity.

If your application is composed by two or more situations described above, you should create more than one application for each module of your software and use them where more suitable.

2 - Interactive Confidential token request

Based on "Authorization Code" grant of OAuth 2.0 (RFC 6749 - Section 4.1). This method should be used only by interactive confidential applications, such as web applications capable of maintaining the confidentiality of their credentials (on a secure server-side with restricted access to the client credentials). A "Interactive Confidential Application" must be created through MibServer interface, then your application must have the following information:

  • ApplicationId: unique for each API client application, can be generated through MibServer interface;

  • ApplicationKey: password associated to ApplicationId;

  • StateControl: (optional) any value to keep your control over which session is this request. The same value will travel in all requests along the process, although not required, it's important to use it to avoid cross-site request forgery, as seen in following article: https://tools.ietf.org/html/rfc6749#section-10.12;

  • An entry point (URL) identical for two callbacks: authorization code callback and access token callback.

First, you have to redirect your user's browser to https://{mibserverurl}/api/v1/OAuth/Login?response_type=code&client_id={ApplicationId}&redirect_uri={AuthorizationCallback}&state={StateControl}, where {mibserverurl}, {ApplicatoinId}, {AuthorizationCallback} and {StateControl} should be replaced by real values, and all parameters should be URL encoded (RFC 1738).

Your user will then log into MibServer web page and API will redirect the browser to your authorization callback URL with the authorization code (and the state control, if provided), so your URL has to be prepared to receive such informations on query string parameters "code" and "state", respectively (i.e., if your redirect_uri is https://myapp.com/oauthcallback, API will redirect (HTTP/1.1 302 Found) to https://myapp.com/oauthcallback?code=abcde&state=1). This code will expire after 1 minute, time enough for you to request the access token. This code should never be reused. If any error during user authentication, or your app is not authorized, API will then redirect the browser to your authorization callback URL passing the parameters "error" and "state" (if provided). Error parameter possible values are "invalid_request" (missing parameters), "unauthorized_client" (application should be created as interactive confidential in MibServer), "access_denied" (user didn't allow your application), "server_error" (unexpected condition, please contact MibServer team), "temporarily_unavailable" (maintenance or overload on MibServer, try again later).

When you receive the callback in your authorization callback URL and you were successfully authorized, you must get the authorization code sent by API and, in server-side, request the access token posting to URL https://{mibserverurl}/api/v1/OAuth/Token with the following fields URL encoded (RFC 1738):

  • grant_type: required, just set to "authorization_code";

  • code: required, the authorization code received from MibServer ("code" parameter) in previous step;

  • redirect_uri: required, access token callback, identical to the previous callback URL provided in first request;

  • client_id: required, your ApplicationId;

  • client_secret: required, your ApplicationKey;

  • state: optional, if you are using state control since the beginning it should be here again.

This HTTP POST should be "form url encoded" with all parameters above in request body, for example:

POST /api/v1/OAuth/Token HTTP/1.1
Host: mediaibox.mydomain.com
User-Agent: Any
Accept: application/vnd.api+json
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code&code=aaaaaaaa&redirect_url=https%3A%2F%2Fmyapp.com%2Foauthcallback&client_id=MyApp&client_secret=abc123def456&state=1

Successful request will return a JSON containing the Access Token and its expiration time.

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
  "access_token": "aAaAaAAaaAAaAAaAAA",
  "token_type": "bearer",
  "expires_in": 3600,
  "client_id": "MyApp",
  "state": "1"
}

Incorrect request will return a JSON containing the message error.

HTTP/1.1 400 Bad Request
Content-Type: application/vnd.api+json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
WWW-Authenticate: Basic
{
  "error":"invalid_request"
}

Possible messages:

  • invalid_request: some parameter is missing or invalid;

  • invalid_client: application ID and secret are not valid;

  • invalid_grant: grant_type parameter should be password;

  • access_denied: user credentials are invalid.

3- Interactive Public token request

Under consideration, might not be in the final specification due to security concerns.

Based on "Implicit" grant of OAuth 2.0 (RFC 6749 - Section 4.2). This method should be used only by interactive public applications, such as clients incapable of maintaining the confidentiality of their credentials, usually native applications, mobile apps, Silverlight and Flash applications and web applications where the client-side (Javascript/jQuery) is directly responsible for authentication, without a server-side orchestration. A "Interactive Public Application" must be created through MibServer interface, then your application must have the following information:

  • ApplicationId: unique for each API client application, can be generated through MibServer interface;

  • StateControl: (optional) any value to keep your control over which session is this request. The same value will travel in all requests along the process, although not required, it's important to use it to avoid cross-site request forgery;

  • An entry point (URL) for authorization callback. When developing a mobile app, remember that you must register your callback URL as a "virtual URL" (usually called "Custom URL Scheme", "Intent Filter" or "URI Association") for your app at the system level (instructions for Android, iOS, Windows Phone).

First, you have to redirect your user's browser (or open a mobile browser or a WebView control for mobile apps) pointing to https://{mibserverurl}/api/v1/OAuth/Login?response_type=token&client_id={ApplicationId}&redirect_uri={AuthorizationCallback}&state={StateControl}, where {mibserverurl}, {ApplicatoinId}, {AuthorizationCallback} and {StateControl} should be replaced by real values, and all parameters should be URL encoded (RFC 1738).

Your user will then log into MibServer web page and API will redirect the browser (or WebView mobile control) to your authorization callback URL with the Access Token, Expiration Time, Token Type (always "bearer" token) and state control (if provided), so your URL (or mobile app, through URL scheme) has to be prepared to receive such informations on fragment component (#something) as "access_token", "expires_in", "token_type" and "state", respectively (i.e., if your redirect_uri is myapp://oauthcallback, API will redirect (HTTP/1.1 302 Found) to myapp://oauthcallback#access_token=abc&expires_in=3600&token_type=bearer&state=1). If any error during user authentication, or your app is not authorized, API will then redirect the browser to your authorization callback URL passing (also as fragment) the parameters "error" and "state" (if provided). Error parameter possible values are "invalid_request" (missing parameters), "unauthorized_client" (application should be created as interactive confidential in MibServer), "access_denied" (user didn't allow your application), "server_error" (unexpected condition, please contact MibServer team), "temporarily_unavailable" (maintenance or overload on MibServer, try again later).

4 - Non-interactive token request

Based on "Resource Owner Password Credentials" grant of OAuth 2.0 (RFC 6749 - Section 4.3). This method should be used only by non-interactive applications, such as Services and Agents. A "Non-Interactive Application" must be created through MibServer interface, then your application must have the following information:

  • ApplicationId: unique for each API client application, can be generated through MibServer interface;

  • ApplicationKey: password associated to ApplicationId;

  • User login: username of a MibServer user, whose permissions will be used during this session;

  • User password: secret key of the same MibServer user above.

It's recommended to create a MibServer user specific for this application, assign proper permissions (or groups) and have in mind that all created objects will be owned by the authenticated user. It's also possible to log with different users in the same application, creating different tokens and using them as needed in each API call.

First, you have to URL encode (RFC 1738) the four attributes described above.

Prepare your HTTP Request using POST method, content type "application/x-www-form-urlencoded" and a "form encoded" body with the following information:

  • grant_type: required, just set to password;

  • username: required, MibServer user login;

  • password: required, MibServer user password;

  • client_id: required, ApplicationId generated through MibServer interface;

  • client_secret: required, ApplicationKey generated through MibServer interface.

Previous methods used to recommend the inclusion of a "state" value for tracking the workflow. As "Resource Owner Password Credentials" is a synchronous call, there's no need for such parameter, although will be replied as expected if you send it.

POST /api/v1/OAuth/Token HTTP/1.1
Host: mediaibox.mydomain.com
User-Agent: Any
Accept: application/vnd.api+json
Content-Type: application/x-www-form-urlencoded
grant_type=password&username=admin&password=$3cR3tKeY&client_id=MyApp&client_secret=abc123def456

Successful request will return a JSON containing the Access Token and its expiration time.

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
  "access_token": "aAaAaAAaaAAaAAaAAA",
  "token_type": "bearer",
  "expires_in": 3600,
  "client_id": "MyApp"
}

Incorrect request will return a JSON containing the message error.

HTTP/1.1 400 Bad Request
Content-Type: application/vnd.api+json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
WWW-Authenticate: Basic
{
  "error":"invalid_request"
}

Possible messages:

  • invalid_request: some parameter is missing or invalid;

  • invalid_client: application ID and secret are not valid;

  • invalid_grant: grant_type parameter should be password;

  • access_denied: user credentials are invalid.

5 - Token usage

After a successful authentication, the client should keep the bearer token until its expiration, and reuse it in every API request. This token must be present in header "Authorization" after the word "Bearer" and a space (e.g., "Authorization: Bearer A1B2C3").

Authenticated request example:

GET /api/v1/mvp_movies/1 HTTP/1.1
Host: mediaibox.mydomain.com
User-Agent: Any
Authorization: Bearer mYs3cr3tT0k3n
Accept: application/vnd.api+json

6 - Security level permissions

Some fields may also be configured considering their security level permission. When a transaction is made, those permissions are checked one by one comparing each one of them with the security level of the API client. If a field security level is greater than the security level of the API client, it is a forbidden field and is handled as a non-existent field by that API client.

  • Reading data: When reading data, all fields of a mediatype are returned, except for those which their security level is greater than API s. If one of those forbidden fields is included in a fields list, for example, the user receives an exception saying that this field does not exist, and this access attempt is logged alongside the user id.

  • Writing data: When writing data, if there is a forbidden field included, it is ignored, and this access attempt is logged alongside the user id.

The API security level configuration is performed in the [API_CLIENTS] table through the [SECURITY_LEVEL_PERMISSION] field. This information will be compared with the information contained in the field [MINIMUM_SECURITY_LEVEL] from the table [ADM_FIELDS], checking which fields will be available according to the information level. If the value contained in the field [MINIMUM_SECURITY_LEVEL] is greater than the value defined in [SECURITY_LEVEL_PERMISSION] access to the field is prohibited.

Edit this page