OAuth2 setup preparation in component.json
It is important to make sure that this setup is prepared and provided during the design of the integration component.
Description
It is important to make sure that this setup is prepared and provided during the design of the integration component. The setup of oauth
part is one part of the general process of authorization.
The oauth
setup in the component.json
of your component ensures that several things are set:
-
The
credentials
field is presented in the user interface for the user to give its explicit authorization to the elastic.io Application. This ensures the ability to add security credentials to be used for the integration component proper function. -
The proper connection endpoints, as well as connection specific protocols, are indicated. Those endpoints are used by the verification process to authorize the user
credentials
.
Example
Let us explain how it should be done on an example of currently working example. Here are the first 31 lines from component.json
of Microsoft Outlook component by elastic.io showing those parts:
{
"title": "Outlook",
"description": "integration component for Office 365 Outlook REST API",
"envVars": {
"MSAPP_CLIENT_ID": {
"required": true,
"description": "Your App Client ID"
},
"MSAPP_CLIENT_SECRET": {
"required": true,
"description": "Your App Client Secret"
}
},
"credentials": {
"fields": {
"oauth": {
"label": "Authentication",
"viewClass": "OAuthFieldView",
"required": true
}
},
"oauth2": {
"client_id": "",
"client_secret": "",
"auth_uri": "https://login.microsoftonline.com/common/oauth2/v2.0/authorize",
"token_uri": "https://login.microsoftonline.com/common/oauth2/v2.0/token",
"scopes": [
"openid","offline_access","User.Read","Contacts.Read","Profile","Calendars.ReadWrite"
]
}
}
}
There are two ways how we can exchange authorization code for tokens:
- Using
client_id
andclient_secret
inside body parameter (as example above). - Using headers - Basic Authentication, where
client_id
andclient_secret
will be used as user and password.
To use headers - you need to provide additional parameter in component.json
at credentials section:
"oauth2" : {
"client_auth": "basic"
}
Your component.json
will be look like this:
"title": "Best component",
"description": "Best component",
"version": "1.0.0",
"authClientTypes": [
"oauth2"
],
"credentials": {
"fields": {
"oauth": {
"label": "Authentication",
"viewClass": "HTTPAuthView",
"required": true
}
},
"oauth2" : {
"client_auth": "basic"
}
},
...
Notes
From the example we have the following sections to note:
Lines 16-20 show the oauth
which will be used to draw the interface for credentials
. For more details please refer to credentials object description. This would be the interface where the User would be asked to authorise. This is just one example representation and can be different from component to component. However, everything which is involved in drawing that part should be included here.
Lines 22-30 represent the oauth2
setup which contains the necessary parameters and endpoint like client_id
, client_secret
, auth_uri
, token_uri
and several more to initiate the user redirection. These parameters will be used to connect and enquire for the access_token
and other parameters.
It is also worth to mention that
oauth
would also be used as a name of the JSON structure where the finalcredentials
would be saved in the database.