Set up OAuth 2.0 authorization for integrated applications

Use OAuth 2.0 protocol to securely authorize third-party applications and web services you integrate with Creatio. This technology does not pass Creatio logins and passwords to third-party applications. OAuth 2.0 also lets you restrict Creatio permissions for the integrated applications.

Install and set up the Identity Service 

Deploy the database and Creatio application servers before installing and configuring the Identity Service. To install the Identity Service:

1. Access the Creatio application server.
2. Install the .NET Core runtime 2.2. Download the install file
3. Install the .NET Core Hosting Bundle. Download the install file
4. Restart the IIS.
5. Navigate to the Creatio install file folder, find the IdentityService.zip archive, and unzip it.
6. Add the Identity Service application pool to the IIS.
   1. Go to the Application Pools section in the Connections area of the IIS management window.
   2. Select Add Application Pool… in the Actions area.
      Fig. 1 Add the pool to the IIS

      
   3. Specify the pool name in the pool settings window, for example, “IdentityServicePool.” Set the .NET CLR Version field to “No Managed Code.”
      Fig. 2 Set up the Identity Service pool

      
7. Set up access to the application pool:
   1. Right-click the newly-created pool. Select Advanced Settings… in the context menu.
   2. Specify the user with Identity Service directory access permissions in the Identity field of the newly-opened window.
8. Create a new Identity Service site in the IIS.

   1. Click Sites on the IIS control panel and select Add Website from the context menu.

   2. Specify the site name, the pool and the path to the Identity Service root directory.

      Fig. 3 Set up the site in the IIS

      

9. Connect the site to your Creatio DBMS. To do so, edit the appSettings.json configuration file in the Identity Service root directory:

   1. Set the “DbProvider” parameter to “MsSqlServer” or “Postgres.”

   2. Specify the connection string in the “MsSqlConnection” or “PostgresConnection” setting. We recommend using the same connection string you specified in Creatio. The user that connects to the database must have permissions to create and update the tables.

      Note. To connect the Identity Service to Creatio with Oracle DBMS, deploy an additional PostgreSQL or Microsoft SQL database instance.

10. Set up the Identity Service system user. To do so, specify the unique ClientId, ClientName, and ClientSecret values in the “Clients” block of the appSettings.json configuration file. The file is located in the Identity Service root catalog. Creatio and the Identity Service will use these values to interact with each other. All parameters support uppercase and lowercase letters, numbers, and special characters, for example, brackets or punctuation marks.

    Recommended parameters:

    ClientId — 16 characters.

    ClientSecret — 32 characters.

    ClientName — any number of characters.

    “Clients” block setup example:

    "[{\"ClientId\":\"{generate ClientId}\",\"ClientName\":\"{generate name}\",\"Secrets\":[\"{generate ClientSecret}\"],\"AllowedGrantTypes\":[\"implicit\",\"client_credentials\"],\"RedirectUris\":[\"http://localhost:8080\",\"http://localhost:8080/lib\",\"http://localhost:8080/lib/\"],\"PostLogoutRedirectUris\":[\"http://localhost:8080\"],\"IdentityTokenLifetime\": 300,\"AccessTokenLifetime\": 3600,\"Properties\": {\"AllowedQueryParameters\": \"[\\\"invitationHash\\\",\\\"targetSubject\\\"]\"},\"AllowedScopes\": [\"register_own_resource\", \"get_resource_list\", \"get_client_info\",\"find_clients\",\"remove_client\",\"update_client\", \"add_registrar_client\", \"IdentityServerApi\"]}]" 

    Note. To avoid errors on Identity Service launch, specify the full path to openssl.pfx in the “X509CertificatePath” setting of the appsettings.json file. openssl.pfx is located in the root of the Identity Service directory.

11. Switch the Identity Service to HTTPS. The setup process is similar to switching Creatio to HTTPS. Read more: Switch Creatio website from HTTP to HTTPS.
12. Enable the Identity Service logging.
    1. Navigate to the Identity Service directory, open the web.config file, and set the “stdoutLogEnabled” parameter to “true.”
    2. Specify where you would like to store the Identity Service logs in the file's “stdoutLogFile” parameter.
    3. Open the appsettings.json file in the Identity Service root directory and configure the log level:

       "Logging": { 
       
         "LogLevel": { 
       
           "Default": "Error" 
       
         } 
       
       } 
       

Set up the Identity Service integration on Creatio's end 

1. Enable the OAuth 2.0 integration in Creatio. To do so, execute this script in your Creatio database. Use it for both Microsoft SQL and PostgreSql.

   UPDATE "AdminUnitFeatureState" 
   
       SET "FeatureState" = 1 
   
   WHERE "FeatureId" = ( 
   
       SELECT 
   
           "Id" 
   
       FROM "Feature" 
   
       WHERE "Code" = 'OAuth20Integration')

2. Fill in the system settings in the “OAuth 2.0” group:
   1. “Authorization server Url for OAuth 2.0 integrations” (“OAuth20IdentityServerUrl” code) — the IdentityServer URL, for instance, http://isEnpointExample.
   2. “Client id for OAuth 2.0 integrations” (“OAuth20IdentityServerClientId” code) — the Identity Service user ID you specified in the “ClientId” parameter of the appSettings.json file when setting up the IdentityServer.
   3. “Client secret for OAuth 2.0 integrations” (“OAuth20IdentityServerClientSecret” code) — the Identity Service user's secret key you specified in the “ClientSecret” parameter of the appSettings.json file when setting up the IdentityServer.
3. Create a default resource. You only need to perform this action once when setting up the Identity Service integration.
   1. Click to open the System Designer.
   2. Open the OAuth 2.0 integrated applications section.
   3. Select Create default resource in the Actions menu.
      Fig. 4 Add a default resource

      

This will create a default resource record with your Identity Service account details.

Set up the OAuth 2.0 authorization 

Once you install the Identity Service and connect it to Creatio, add a client record for each application you are going to authorize with OAuth 2.0. To do so:

1. Click to open the System Designer.
2. Open the OAuth 2.0 integrated applications section.
3. Click New.
4. Fill in the client parameters for the relevant application on the newly-opened page.
   1. Name — the title that the integration list and the logs will use.
   2. Application URL — the URL of the integrated application or the web service.
   3. Description — the purpose of the integration.
   4. Active — enables and disables the integration.

   5. System user — the Creatio user with sufficient permissions for this integration. We recommend permitting this user to only read and edit the fields the integrated application or the web service need to change. For example, if you are integrating a web service that passes the currency exchange rates to Creatio, grant permissions to only read and edit the Rate and Start fields of the Currency lookup.

      Creatio automatically populates the client account details (the ID and the secret).

      Fig. 5 Set the client

      
5. Save the record.
6. Repeat steps 3-6 for all applications you need to authorize with OAuth 2.0.