OAuth2 - Authorization code
We will not detail the communication flow here, because this is rather technical, and it does not help in the context of this documentation.
Configuration steps to set up an OAuth2 authentication:
- Application registration: create an authorization on the target service
- OAuth2 parameters configuration: configure the datasource in Elements Connect
- Credential retrieving: to get the OAuth2 credentials from the target service
Those steps are detailed below.
Configuration steps
1. Application Registration
Before using OAuth2 with Elements Connect, the first step is to register Elements Connect as an Application with the service.
This is done through a registration form, where the following information shall be provided:
- Application Name: to identify the Application, i.e.: Elements Connect
- Callback URL: https://<jira_base_url>/nfeed/admin/models/datasources/oauth/_callback
- Grant types: Authorization code and Refresh token
- Granted scopes: to set the access level of Elements Connect
Once the Application is created and configured, the Client secret and Client ID are generated.
Those values will be needed at the next step.
2. Configure OAuth2 parameters
From Elements Connect administration page, create a new Datasource of type "URL".
From the datasource configuration page, select OAuth2 Authentication and click the Configure button.
This will open the following dialog:
Every REST API has specific parameters:
| Parameter | Description |
|---|---|
Client ID | Unique Client identifier that you obtained during the Step 1, described above. |
| Client Secret | Secret code provided at the same time as the Client identifier above. |
| Authorize URL | The Authorization endpoint provided by the service. Usually the endpoint ends with /authorize. |
| Token URL | The token endpoint provided by the service. Usually the endpoint ends with /token. |
| Scopes(optional) | Specifies the access level that Elements Connect is requesting. |
If your service supports OpenID Connect specifications, the offline_access scope must be part of the requested scopes to get a refresh token.
3. Credential retrieving
The next step is to get a credential from the remote service for Elements Connect.
- If all parameters are filled in correctly, you can click on 'Get new credential'.
- If you don't have an active session (already connected to your service), you will be redirected to an authorization prompt.
- If you grant Elements Connect the access, you are finally redirected back to Elements Connect and you should see the dialog again with your parameters and a success message :
You can now close the dialog.
The datasource Authorization section should now display AUTHORIZED
Once you click on Save button, The received tokens will be stored next to the datasource configuration in the database.
If the access token has an expiration you need to provide refresh token so Elements Connect can request new valid access token.
Once the refresh token expires, you need to relaunch the flow by clicking on 'Get new credentials'.
Other
Clear credential
If for any reason you want to clear the credentials stored by Elements Connect, you can click 'Clear credential'.
The parameters in the form will remain unchanged, but any authorization token obtained from the remote service will be deleted.
You will need to get new credentials again for the datasource to work properly.
The datasource must be saved for the changes to be taken into account.
Authorization status
In the datasource page, in the Authentication section, you have a status marker displayed. The status can be :
- AUTHORIZED Elements Connect has a credential stored.
- NOT AUTHORIZED Elements Connect does not have any valid credential.
- NOT CONFIGURED The OAuth2 parameters are not provided yet.
- ERROR Error while trying to test the status.
See the JIRA log files for details.
The information AUTHORIZED only denotes that there is a credential stored. We do not test if this credential is still valid against the remote service.
If a field using this datasource displays an access error and the Authorization status indicates AUTHORIZED, try to get a new credential.