Important
You are browsing the documentation for version 3.1 of OroCommerce, OroCRM and OroPlatform, which is no longer maintained. Read version 5.1 (the latest LTS version) of the Oro documentation to get up-to-date information.
See our Release Process documentation for more information on the currently supported and upcoming releases.
Add OAuth Applications under My User Menu¶
Hint
The feature requires extension, so visit Oro Marketplace to download the OAuth 2.0 Server extension and then use the composer to install the extension to your application.
Oro applications support oAuth 2.0 credentials authorization grant type to enable connection of third-party applications to the web API. To connect a third-party application, you need to add it and configure its pre-generated credentials in the back-office of your Oro application. These credentials are managed on user level which enables generation of different credentials for various applications across multiple organizations.
Starting Conditions¶
To be able to add an OAuth application, make sure that you generate private and public encryption keys and add them to the /var directory of the installed Oro application. Although the path to the keys is predefined, you can change it by providing your custom location in the config.yml file.
Note
If no keys are found, the following warning message will be displayed in the back-office:
OAuth authorization is not available as encryption keys configuration was not complete. Please contact your administrator.
Oro Side: Add an Application¶
To add a new OAuth application in the back-office:
Click on your user name on the top right of the screen.
Click My User.
In the OAuth Applications section, click Add Application on the top right and provide the following details in the pop-up dialog:
Organization — If you are adding an application within the organization with global access, you can select which other available organization to add the application to. This field is displayed to users with access to multiple organizations.
Application Name — Provide a meaningful name for the application you are adding.
Active — Select the Active check box to activate the new application.
Click Create.
A corresponding notification is sent to the primary email address of the user, the owner of oauth application. You can change the default recipient, localization, or an email content if needed by updating the OAuth email templates and the related notification rule set out-of-the-box in the system configuration.
Once the application is created, you are provided with a Client ID and a Client Secret. Click on the icon to copy the credentials to the clipboard.
Important
For security reasons, the Client Secret is displayed only once – immediately after you have created a new application. You cannot view the Client Secret anywhere in the application once you close this dialog, so make sure you save it somewhere safe so you can access it later.
You can add as many applications as you need for any of your existing organizations. All added applications are displayed in the grid, and you can filter them by name, organization, and status.
Hint
Use the More Options menu to edit, deactivate or delete an application.
Use the generated Client ID and Client Secret to retrieve an access token to connect to your Oro application.
Third Party Side: Generate Token¶
To configure machine-to-machine authentication and retrieve the access token:
Provide your Request URL.
The Request URL consists of your application URL and the /oauth2-token slug, e.g.,
https://yourapplication/oauth2-token.Send a POST request with the following body parameters to the authorization server:
grant_type with the value client_credentials
client_id with the client’s ID
client_secret with the client’s secret
scopes with a space-delimited list of requested scopes permissions
Note
client_credentials is currently the only supported grant type.
Receive response from the authorization server with a JSON object containing the following properties:
token_type with the value Bearer
expires_in = 3600 seconds. Once the token is generated, it is valid for an hour and can be used multiple times within this time limit to request the necessary data.
access_token a JSON web token signed with the authorization server’s private key
Use the generated access token to make requests to the API.
Note
Access tokens for backend and frontend API are not interchangeable. If you attempt to request data for the frontend API with a token generated for the backend application (i.e., a back-office user), access will be denied.
Related Articles