search string side menu

Modules > Examples of ELMA365 integration modules / Custom OAuth2 module for authentication via an external service

Custom OAuth2 module for authentication via an external service

By default, users sign in to ELMA365 or external portals using their login and password, but you can set up registration and authentication via external services. To do that, you need to create and configure an OAuth2 custom module. When the module is enabled, a new sign-in method will become available to users in ELMA365. You can also enable it for the company’s portals.

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

Only users included in the Administrators group can create and configure modules.

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

This article describes how you can create an OAuth2 module. As an example, we are going to set up authentication with Google. There are three main steps to configuring the module:

  1. Creating and configuring a custom module in ELMA365.
  2. Configuring the application in the Google Developer Console.
  3. Adding a script to the module and finishing its configuration.

Create and configure the module

To create a new module, go to Administration > Modules and click +Module. Select Create. Enter information about the module and click the Create button. Read more in the Create a custom module article.

For integration with Google, you will later need your ELMA365 company’s URL and the module’s ID. You can copy the company’s URL on any page in the system. To get the ID of the module, open its page and copy the set of symbols after “ext_” from the address bar.

Add parameters

Add the necessary settings to the module. These are global parameters that will be used in the module’s scripts.

Go to the Settings tab, click +Add and create String type properties that will store the values of the module’s settings. For the module to work correctly, add the following properties:

  • Client ID (client_id). ID of the application that will request data on the external service. You will get it when you register your application on the external service.
  • Client secret (client_secret). Secret of the application. You will get it when you register your application on the external service. It is used along with the client_id to get an access token for the external service’s API.
  • Authentication URL (auth_url). URL of the authentication page of the external service. The user will be redirected to this page from the application.
  • Token URL (token_url). URL on the service’s side. The request for an API access key (access token) will be sent to this address. The request will contain client_id and client_secret.
  • Scopes (scopes). Access that will be granted to the application in the external service by the access token. Scopes are separated with spaces. You must request access to some data that can uniquely identify a user (for example, the email).
  • Automatic sign-up (auto_signup). A Yes/No switch type property. If this parameter is set to Yes, users that don’t exist in the system will be automatically created when they sign in using the external service.

The codes used as property names have to be the same as specified in brackets in the list above, as the system uses them to recognize the module’s type. Display names can be custom.

You can also create other properties you need and set any names you want for them.

When you add all the properties, go to the Main tab and click Save.

Configure the module’s connection page and the default values

By default, all the settings you create for a module are added to its connection page. The user sees them when clicking on the module’s name in the Administration workspace.

It is recommended that you make a connection page that includes only parameters that the user enters manually when configuring the module. To find out which parameters have to be set manually and which need to have default values, read the developer’s documentation of the external authentication service.

Let’s see how to set up a connection page for our Google OAuth2 module. The list of its parameters can be found in the previous section of this article. By default, all of them are displayed on the module’s page.

To configure the connection page so that it contains only the parameters set manually by the user, do the following:

  1. On the Settings tab, click the Change Form button. The interface designer will open. Here you need to edit the module settings page.

external-oauth2-integration-1

  1. Delete the standard item form: select the widget, click the recycle bin icon, and confirm deletion.
  2. Since the user will have to enter the Client ID and the Client secret manually, add them to the form. You also need to add the Automatic sign-up property, as the user will need to set its value. To add the fields to the form, on the right-side panel of the designer, switch to the Properties tab and drag them to the canvas.
    external-oauth2-integration-2
  1. Click Publish.

Now, on the module connection page, the user will only see the parameters that they need to enter manually:

external-oauth2-integration-3

  1. Set the default values for the rest of the parameters. To add a value, go to the Settings tab and click a property’s name. In the window that opens, set the desired value for it in the Default field.
    external-oauth2-integration-4

For example, for the Google OAuth2 module, the default values will be the following:

  • Authentication URL: https://accounts.google.com/o/oauth2/v2/auth.
  • Token URL: https://www.googleapis.com/oauth2/v4/token.
  • Scopes: https://www.googleapis.com/auth/userinfo.email.
  1. Go to the Main tab and click Save.

Configure the application on the external service

On the external service, you need to get the Client ID and the Client secret to use them as values for the module’s parameters. You also need to specify the address where the user needs to be redirected after successful authentication.

To configure the integration in Google, do the following:

  1. Go to console.developers.google.com.
  2. Create a project or select an existing one. Learn about creating projects in the official Google documentation.
  3. Configure the OAuth consent screen if you haven’t done so before. Learn more in the official Google documentation.
  4. In the left-hand menu, select Credentials.
  5. At the top of the page, click +Create Credentials and select OAuth client ID in the drop-down.
  6. In the Application type field, select Web application.
  7. In the Authorized redirect URIs section, click +Add URI and enter the redirect URL of the following format: <host>/_oauth2/post-message?provider=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX. As <host>, paste your company’s ID. As the provider’s ID, use the module’s ID.
  8. Click Create.
  9. In the window that opens, copy the Client ID and the Client secret.

Finish configuration and add a script to the module

The preparatory configuration is finished. Now you can fill out the module’s parameters and write a script that will form requests.

First, open the module’s page and click Enable. When you registered your application on the external service, you got the Client ID and Client secret. Enter them in the corresponding fields on the module’s connection page. Set the value of the Automatic sign‑up field.

Now you need to add a script to the module. This script reads the values of the module’s settings and forms an authorization request. The request is sent to the external service that returns the user’s ID. The ID is compared with the one in the ELMA365 database. If they match, the user is signed in.

In the script, the request is sent and the response is received using the oauth2_profile() method. Note that you cannot change the method’s name, as the system uses it to recognize the module’s type.

To add a script:

 

  1. Open the module’s settings, go to the API Methods tab, and click Edit. The methods editor will open.
  2. Go to the Scripts tab and write a script based on the following template:

interface AccessTokenData { // data structure to store the access token of the external service 
    access_token: string;
    refresh_token: string;
    token_type: string;
    expires_in: number;
}
 
interface OAuth2Profile {  // data structure to store the user’s ID
 
    user_id: string;
}
 
interface OAuth2ResponseFail { // data structure to store the error message
    error: string;
    error_description: string; 
}
 
async function oauth2_profile (tokenData: AccessTokenData): Promise<OAuth2Profile | OAuth2ResponseFail> {
    code of the method that returns the user’s ID or the error message text from the OAuth2 provider
}

 

  1. Save and publish the script.

Example script for the Google authentication module

interface AccessTokenData {
    access_token: string;
    refresh_token: string;
    token_type: string;
    expires_in: number;
}
 
interface OAuth2Profile {
    user_id: string;
    email: string;
}
 
interface OAuth2ResponseFail {
    error: string;
    error_description: string;
}
 
// logout interface
interface OAuth2LogoutResponse {
    redirect_url: string;
}
 
 
async function oauth2_profile (tokenData: AccessTokenData): Promise<OAuth2Profile | OAuth2ResponseFail> {
    const resp = await fetch(`https://www.googleapis.com/oauth2/v1/userinfo?alt=json&access_token=${tokenData.access_token.toString()}`)
 
    if (resp.ok) {
        const result = await resp.json()
        return <OAuth2Profile>{
            user_id: result.id.toString(),
            email: result.email.toString()
        }
    }
    else {
        return <OAuth2ResponseFail>{
            error: "user_not_found",
            error_description: await resp.text()
        }
    }
}
// logout
async function oauth2_logout(): Promise<OAuth2LogoutResponse | OAuth2ResponseFail> {
    return <OAuth2LogoutResponse> {
            redirect_url: "https://www.google.com/accounts/Logout"            
        };
}

The module’s configuration is finished. Now users can sign in to ELMA365 using their account on the external service.

If you want to connect the module to an external portal set up in your company, go to the workspace the portal is created in. Open the portal page and click the gear icon next to the portal’s name. In the settings window that opens, go to the Authentication tab and check the box next to the module’s name.
external-oauth2-integration-5

For security purposes, you can disable the option to sign in with a login and password. To do that, set the Allow sign‑in with login/password switch to No. With this option, users will only be able to sign in to the portal using external services.

Configure logout in the OAuth2 module

For additional security, you can set up the logout mechanism in your custom OAuth2 module. With this mechanism the user will be logged out of the linked external provider’s account when they sign out of ELMA365.

To configure logout for the module, do the following:

  1. On the module’s settings page, open the API Methods tab and click Edit. The method editor will open.
  2. Go to the Scripts tab and describe the logout interface:

interface OAuth2LogoutResponse {
    redirect_url: string;
}

  1. After that, add the oauth2_logout method:

async function oauth2_logout(): Promise<OAuth2LogoutResponse | OAuth2ResponseFail> {
    return <OAuth2LogoutResponse> {
        redirect_url: "https://my_idp.com/logout"            
    };
}

As the redirect_url, use the external provider’s address. A logout request will be sent from ELMA365 to this address.

  1. Save and publish the script.

Now when a user clicks Sign out in ELMA365, they will be redirected to the logout page of the OAuth2 provider.

You can also add a redirect in the OAuth2 provider’s settings so that the user is redirected back to the ELMA365 login page after signing out.

Link an OAuth2 account to an ELMA365 profile using scripts

You can use scripts to manage account linking, that is, how ELMA365 profiles are bound with accounts in the OAuth2 provider's system. The following methods are available:

  • createWithAuthData. The method allows you to create a new ELMA365 user, automatically linking their profile to an existing account in the external provider’s system. Users added with this method are automatically assigned the Active status.

Note that a user added in this way will only be able to sign in to ELMA365 using the OAuth2 provider’s login details. Other authentication methods will not be available.

  • addOAuth2Data. This method allows you to link an account in the OAuth2 provider’s system to an existing ELMA365 profile. After that the user will be able to sign in to ELMA365 using their external provider’s login details. The method is an alternative to manually adding the external account in the user’s profile settings on the Authentication tab.
  • removeOAuth2Data. This method unbinds an external account from an ELMA365 profile. It is an alternative to removing the linked account in the user’s profile settings.

Read more about these methods in ELMA365 TS SDK in the User object article.

Example of using the module

Let’s see how a user can register on the portal and sign in using the Google authentication module that we’ve created. You can install the module and try it for yourself. To do that, download the .e365 file with the ready-to-use module.

Install and prepare the module

To install the module and fill in the parameters:

  1. Go to Administration > Modules.
  2. Click the +Module button.
  3. In the window that opens, click the Upload file link.
  4. Select the downloaded file on the local drive.
  5. Click Next until the module is installed.
  6. Register the module on the external service and copy the Client ID and the Client secret as described above.
  7. Go back to ELMA365, open Administration > Modules, open the Google OAuth2 module, and click Enable.
  8. On the connection page, specify the Client ID and the Client secret you copied.

external-oauth2-integration-6

  1. Save the settings.
  2. Go to the workspace that the external portal is set up in.
  3. In the portal settings window, on the Authentication tab, check the box next to the Google OAuth2 module.
  4. Save the settings.

How the module works

Let’s see how the module works. We’ll take signing in to the external portal as an example.

  1. The user follows the invite link to the portal and clicks Use a different sign‑in method.

external-oauth2-integration-7

  1. In the window listing the available external services, the user clicks Google OAuth2.

external-oauth2-integration-8

  1. In the Google sign-in window, the user selects their Google account.

external-oauth2-integration-9

  1. In the next window, the user needs to allow access to the account.
  2. Then the portal invite page opens. The user enters their name and clicks Save.

The registration is complete. Now the user only needs to sign in to their Google account to sign in to the portal.

360009906679.html sms-integration.html

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