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&username=USERNAME&password=PASSWORD
Where USERNAME is user’s name and PASSWORD is user’s password.
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).
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 tokenrequestToken
, to create and save the tokengetName
, 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