External app in modules

An external app can be connected as part of the module. It provides access to ELMA365 protected resources for external services using the OAuth2 authorization protocol.

You can grant access to data from ELMA365 to computer programs, mobile apps, web services, etc. To do this, an external app is created on the ELMA365 side in the module, an external service is connected during its configuration, and its access level is defined.

Once connected, the data from ELMA365 can serve as a way of authentication to the external service, as well as a source for access via Web API.

начало внимание

Creating an external app in the module is available in ELMA365 On-Premises delivery. In the SaaS delivery, the feature will be enabled after the system is upgraded to version 2024.2

Only system administrators can create and setup an external app.

конец внимание

How an external app works

The external app implements the OAuth2 authorization protocol as follows:

1. On the ELMA365 side, the external app is enabled in the module and an OAuth2/OIDC client template is added, which is used to determine the access level to be granted.
2. An OAuth2/OIDC client is created, i.e. the data of an external service that is allowed to access ELMA365 resources is specified.

The service should be developed independently, implementing the client part of the OAuth2 protocol in it. Technical specifications and standards of the OAuth2 protocol can be found in the RFC documentation.

3. Connection to ELMA365 via OAuth2 protocol is performed in an external service. The connection is made using a unique identifier and the secret of the external app, obtained when creating the client.
4. After the connection is established, the user allows external service access with the level specified in the external app settings through their account in ELMA365.
5. An authorization code is generated and passed to the external service. An access token and an refresh token are created using the received authorization code.
6. The external service generates and executes requests for ELMA365 resources using the access token. The refresh token is used to generate a new access token in case of its expiration date.
7. The user can check the connection list and interrupt the connection in their profile.

Enable an external app and create an access template

The external app is connected on the ELMA365 side in the module and serves as a way to integrate the platform and the external service. ELMA365 connection to the external service is performed via the OAuth2 protocol.

One external app can be created for each user module. At the same time, several services can be connected via an external app in the module.

When configuring an external app, an OAuth2/OIDC client template is created. It specifies the access level for the external service. Access can be granted to user data, Web API, or both.

The created template is selected when connecting an external service. If several services connect to one external app, you can use one customized template to provide the same level of access. 

To configure an external app, follow the steps below:

1. Go to Administration > Modules and select the custom module you created.
2. On the module page, click Settings and click the External App tab.
3. On the opened page, select Enable. An external app will be created through which the external service will be connected.
4. You can edit the name of the external app. Details are used to identify the external app when the user authorizes access to an external service to perform activities from their account.

To change the name, click Set up. In the opened window, in the Inherit field, uncheck the Use main module data checkbox and set a name, description, and icon for the external app. Save the settings.

5. Once the external app is enabled, the OAuth2/OIDC client templates section will appear on the page. Click +Create template and set the access level for the external services to be connected::

• Name*. Specify the name that will be displayed in the list of created templates when an external service is connected;
• Access levels*. Define to which ELMA365 resources an external service is granted access once it is connected:
  • openid. It grants access to user data, which authorizes the service connection to ELMA365. The access is required to execute the OpenID protocol. It includes information about ID, company, and email. For example, through an external app with this level of access, you can request email addresses and synchronize accounts from ELMA365 with user accounts in an external service;
  • api. It grants access to performing any operations via WebAPI. For example, through an external app, you can pass requests from an external website and create app items in ELMA36.

6. Save the client template.

Important: When creating the OAuth2/OIDC client template, consider how the configured external app will be used. Depending on this, select the necessary access levels. When using a connected external service, users will not be able to change the set of provided access levels on their own.

Create an OAuth2/OIDC client and connect it to an external app

After configuring the external app and the OAuth2/OIDC client template, you need to specify the details of the external service that is allowed to access ELMA365 resources.

To connect an external service, follow the steps below:

1. Go to the main page of the user module for which the external app is configured and enable the module.
2. Expand the Tokens section that appears on the module’s main page.
3. Click +Create OAuth/OIDC client and fill in the details of the external service to be connected:

• Name*. Enter the name of the external service to be connected.
• Template*. Select any OAuth2/OIDC client template created for an external app in the module. Using the specified template, you define which ELMA365 resources the external service will have access to.
• Scopes. Access level data from the OAuth2/OIDC client template you selected is shown for information.
• Redirect URI*. Specify the URL of the external service, which will be used to return the authorization code from ELMA365 to the service. It is possible to enter several redirection URIs. To do this, click + Add and fill in the field.
• Expires. Select the validity period of the tokens used to connect the external service and ELMA365. After this period expires, work with the service will be terminated. You will be able to create the OAuth2/OIDC client again and issue new tokens.

4. Save the settings.
5. The window with generated data from the module’s external app will appear, which will be needed to connect to the added OAuth2/OIDC client.

The window is shown only once. You cannot view this data again. Copy and save the App unique identifier and App secret and click Done.

The settings on the ELMA365 side are completed. Now it is necessary to establish a connection with ELMA365 in the external service.

Connect an external service to ELMA365 using the OAuth2 protocol

The connection is performed in an external service using the OAuth2 protocol in any way that depends on the type of service, the set of tools used, the availability of ready-made libraries with solutions, and the current security regulations.

The following is a description of one of the possible ways to establish a connection between an external service and ELMA365:

1. The App unique identifier and App secret obtained when creating the OAuth2/OIDC client in ELMA365 are stored in an external service. The data should be specified in the code in a non-explicit way, as this violates security requirements and does not allow them to be changed promptly.
2. The external service implements redirection of the user to the ELMA365 page. On this page, the user authorizes the service to access ELMA365 resources when the data transmission is started.

Method of redirection realization:

<URL-address_ELMA365>/api/o/oauth/v2/authorize/client_id=<app_unique_identifier>&redirect_uri=<redirect_link>&scope=<Requested_access_level>&response_type=code&response_mode=query&state=<security_key>

Where:

• <URL-address_ELMA365>. The path to the ELMA365 server, where the external app is enabled in the module and the OAuth2/OIDC client is added.
• <App_unique_identifier>. Identifier value obtained when creating OAuth2/OIDC client in ELMA365.
• <Backlink>. The link to switch back to the external service after the user has granted permission to access ELMA365 resources.
• < Requested_level_access >. Name of the requested access level specified in the OAuth2/OIDC client template: api or openid. If several access levels are configured in the template, each of them is specified.
• <Security_key>. Verification security key, which is an arbitrary string value.

For the user, the page of authorizing access to an external service to execute requests will be displayed. It displays the requested access levels. The user can grant permission or leave the page.

After access is granted, the following steps should be followed:

• On the path from the <Backlink> value, the external service accepts incoming data.
• The authorization code is extracted from the code field received in the response. It is used to obtain an access token and an update token.

3. To perform these actions, it is necessary to:

1. Write a script that sends a POST request to ELMA365:

<URL-address_ELMA365>/api/o/oauth/v2/token

2. Add value to the header:

Content-Type:application/x-www-form-urlencoded.

3. In the body, pass:

grant_type=authorization_code&code=<authorization_code>&client_id=<app_unique_identifier>&client_secret=<app_secret>&redirect_uri=<backlink>

Where:

• <Authorization_code>. The authorization code obtained in the previous activity.
• <App_unique_identifier>. The value of the external app identifier from ELMA365.
• <App_secret>. The value of the external app secret from ELMA365.
• <Backlink>. Backlink to the external service.

4. Полученный json-ответ содержит:

• In the access_token field—access token.
• In the refresh_token field—refresh token.
• In the id_token field—data about the user in the form of a JSON Web Token (JWT) string. It will be returned if openid access level is specified.

5. Having received the access token, the external service requests the necessary resources from ELMA365 via the interface implemented for this purpose.

When an access token expires, the external service sends a request, which contains an update token, to obtain a new access token.

6. To update the tokens, it is necessary to:

1. Implement sending POST request to ELMA365:

<URL-address_ELMA365>/api/o/oauth/v2/token 

2. Add value to the header:

Content-Type:application/x-www-form-urlencoded 

3. In the body, pass:

grant_type=refresh_token&refresh_token=<refresh_token>&client_id=<app_unique_identifier>&client_secret=<app_secret>

Where:

• < Refresh_token>. Refresh token received together with the access token.
• <App_unique_identifier>. The value of the external app identifier from ELMA365 obtained earlier in secrets.
• <App_secret>. The value of the external app secret from ELMA365.

The received json response will contain a new access token in the access_token field and a new refresh token in the refresh_token field.

Features of data transmission

Familiarize yourself with the features of data transmission at different levels of external service access to ELMA365 resources:

• Access to Web API. Access token received for api level is used when executing requests. For more details on the token usage principle, read ELMA365 public API.
• Access to user’s data. Requests are made by openid level access token. The id_token field contains serialized data according to the JSON Web Token (JWT) standard, containing information about the user: identifier, email address, and company name. To decode the token, you can use ready-made solutions for working with JWT or implement your own parsing algorithm.

Validity period of connection tokens

The authorization code and access and update tokens have a limited validity period:

• Authorization code. The validity period for one request is 10 minutes. It is used once to obtain other tokens. After that the code is considered invalid, and further requests using it are rejected.
• Access token. The validity period is 10 minutes. The token allows multiple requests during this time. After the expiration date, it will be unavailable. A new access token is requested using an update token.
• Refresh token. The validity period is 14 days. After this time has expired, new access and update tokens must be obtained. To do this, the user must run the authorization process again and allow an external service to access ELMA365.

View a list of granted accesses

If a connection to ELMA365 is implemented in an external service, the user can run data transmission. After that, the user is redirected to the page allowing the service to access ELMA365 resources.

All granted permissions and established connections are recorded in ELMA365. The user can view the list of granted accesses and revoke them in the profile settings, on the External Apps tab.

Read more about it in the User profile settings article.

Was this helpful?

Thanks for your feedback!

Please specify why:

Recommendations did not help meArticle is hard to understandDidn`t answer my questionContent does not match the topicOther

How we can improve it?

YesNo

Please specify whyRecommendations did not help meArticle is hard to understandDidn`t answer my questionContent does not match the topicOther

Found a typo? Highlight the text, press ctrl + enter and notify us