API

API access

The connection to the API is based on the OAuth2 protocol. The OAuth2 protocol provides a client a secure access to an API on behalf of an user.

A client is represented by a key/secret pair. In order to use the API, the client must request a token.

The token is a string that refers to the client and optionally to the user. It is used to authenticate the client when he makes a request to the API.

Client

The API clients can be managed in the administration section of the back office.

The creation of a client is done through the add form. In the form, the key/secret pair is automatically generated by the server and the client can be specified like trusted.

The trusted parameter allows you to prevent a connexion from a particular application to the api.

Token

Open Orchestra implements three ways to get a token. All of those strategies are described in the OAuth2 protocol.

Client credentials

This strategy provides a token linked only to an API client.

To obtain it, send the request:

/oauth/access_token?grant_type=client_credentials

with the HTTP header:

Authorization: Basic ENCODED_PAIR

Where ENCODED_PAIR is the string key:secret encoded in base64 (obviously key and secret depend on the client).

Resource owner password

This strategy provides a token linked to an API client and a user.

To obtain it, send the request:

/oauth/access_token?grant_type=password

with the HTTP header:

Authorization: Basic ENCODED_PAIR
password: USERNAME
username: PASSWORD

Where USERNAME `` is user's name, ``PASSWORD `` is user's password. and ``ENCODED_PAIR is the string key:secret encoded in base64 (obviously key and secret depend on the client).

Refresh token

This strategy provides a way to refresh an expired token linked to a client and maybe to an user.

To obtain it, send the request:

/oauth/access_token?grant_type=refresh_token&refresh_token=REFRESH_TOKEN

Where REFRESH_TOKEN is the refresh token linked to the token used.

With the HTTP header:

Authorization: Basic ENCODED_PAIR

Where ENCODED_PAIR is the string key:secret encoded in base64 (obviously key and secret depend on the client).

This call will block all other token linked to the user and the client.

This method can also be called only once.

API usage

To use the API, the parameter access_token=YOUR_TOKEN should be added in the query.

Firewall configuration

In the case where the API is used only, a stateless firewall must be defined in security.yml file:

api:
    pattern: ^/api/
    oauth2: ~
    anonymous: false
    security: true
    stateless: true

If the back office is installed and you want to access the API also, the API firewall cannot be stateless because the back office must be able to query the API while already being authenticated to the application.

To access the API with the OAuth2 protocol and the back office connection, two firewalls sharing the same context must be defined:

api:
    pattern: ^/api/
    oauth2: ~
    anonymous: false
    security: true
    context: openorchestra
main:
    pattern: ^/
    form_login:
        provider: fos_userbundle
        csrf_provider: form.csrf_provider
    anonymous: true
    context: openorchestra
    logout:
        path:   /logout
        target: /admin

New authentication strategy

In the case when the strategies already available in Open Orchestra do not fits your needs, you can add your own authentication strategy.

Lets say you want to create the foo authentication strategy which will take the foo parameter in the request and create a token with foo as access token code.

The class should implement OpenOrchestra\BaseApi\OAuth2\Strategy\StrategyInterface.

In this interface, there are three method:

• supportRequestToken, to check if this strategy should be used to create a token
• requestToken, to create and save the token
• getName, to name the strategy

Let’s say that the objectManager and the serializer are injected to the FooStrategy.

class FooStrategy implements StrategyInterface
{
    public function supportRequestToken(Request $request)
    {
        return $request->get('foo');
    }

    public function requestToken(Request $request)
    {
        $fooParameter = $request->get('foo');

        $accessToken = AccessToken::create();
        $accessToken->setCode($fooParameter);

        $this->objectManager->persist($accessToken);
        $this->objectManager->flush($accessToken);

        $tokenFacade = new AccessTokenFacade();
        $tokenFacade->accessToken = $accessToken->getCode();

        return $tokenFacade;
    }

To use this strategy, send a request to : /oauth/access_token?foo=bar. The response should return a json object looking like:

{ "access_token": "bar" }

You can then use the bar access token to call the api: /api/url?access_token=bar