Deploy the Identity Service

Identity Service implements OAuth 2.0 in Creatio.

note

If you use Creatio in the cloud, the Identity Service is deployed out of the box. Proceed to getting OAuth 2.0 credentials. Instructions: Generate OAuth 2.0 client credentials.

Install the Identity Service

This is a one-time procedure. Before you install the Identity Service, deploy the database and Creatio application servers.

You can install the Identity Service in multiple ways:

• Using IIS. Read more >>>
• Using Docker. Read more >>>

Install the Identity Service using IIS

Install the Identity Service into the Creatio application server. Each Creatio instance needs an individual Identity Service.

To install the Identity Service using IIS:

1. Install additional components.

   .NET 6 Runtime. Download the install file

   .NET 6 Hosting Bundle. Download the install file

2. Restart the IIS.

3. Extract the IdentityService.zip archive to an arbitrary directory in the root Creatio directory. For example, "IdentityService."

4. Add the Identity Service application pool to the IIS. Use dedicated application pool for every Creatio instance.

   1. Open the Application Pools section in the Connections area of the IIS.

   2. Select Add Application Pool... in the Actions area (Fig. 1). This opens the Add Application Pool window.

      Fig. 1 Add the pool to the IIS

      

   3. Fill out the settings.

      Setting	Setting value
      Name	Must be unique. For example, "IDServicePool."
      .NET CLR Version	No Managed Code
      Managed pipeline mode	Integrated

   4. Save the changes.

   As a result, the "IDServicePool" pool will be added (Fig. 2).

   Fig. 2 Identity Service pool

   

5. Set up access to the application pool (optional for development environment). By default, the Windows user accesses the application pool.

   1. Select "IDServicePool" in the Application Pools area.

   2. Click in the Identity setting of the Advanced Settings window (Fig. 3). This opens the Application Pool Identity window.

      Fig. 3 Set up access

      

   3. Select the Custom account checkbox and click Set... (Fig. 4). This opens the Set Credentials window.

      Fig. 4 Add a new user

      

   4. Fill out the User name, Password, Confirm password user settings.

   5. Save the changes.

6. Create the Identity Service website in the IIS.

   1. Click Sites → Add Website in the Connections area of the IIS. This opens the Add Website window.

   2. Fill out the website settings.

      Setting	Setting value
      Site name	An arbitrary website name. For example, "IDServiceWebsite."
      Application pool	Click Select... and select the "IDServicePool" in the Application pool setting.
      Physical path	The path to the root Identity Service directory.
      Port	The port for the Identity Service. Must be unique. For example, "8090."

   3. Save the changes.

   As a result, the website for Identity Service will be created (Fig. 5).

   Fig. 5 Website for Identity Service

   

7. Connect the website to your Creatio DBMS.

   1. Open the appsettings.json file in the root Identity Service directory.

   2. Modify the file parameters.

      Parameter	Parameter value
      DbProvider	"MsSqlServer" or "Postgres"
      DatabaseConnectionString	Use the same connection string you specified in the connectionString attribute of the ConnectionStrings.config file. Use escaped characters.

      The user that connects to the database must have permissions to create and update the tables.

      If you need to connect the Identity Service to Creatio that uses Oracle DBMS, deploy an additional PostgreSQL or Microsoft SQL database instance.

   3. Save the changes.

8. Set up the Identity Service system client.

   1. Open the appsettings.json file in the root Identity Service directory.

   2. Modify the file parameters. The Identity Service uses these values to interact with Creatio. All parameters support uppercase and lowercase letters, numbers, and special characters, for example, brackets or punctuation marks.

      Parameter	Parameter value	Requirements for parameter value
      ClientId	An arbitrary client ID. For example, "IdServiceUser."	16 characters
      ClientName	An arbitrary client name. For example, "MyIdentityServiceApp."	Any number of characters
      Secrets	An arbitrary client secret. For example, "ItIsMyPasswordForIdentityService."	32 characters

      appsettings.json file

      "[{\"ClientId\":\"SOME_CLIENT_ID\",\"ClientName\":\"SOME_CLIENT_NAME\",\"Secrets\":[\"SOME_CLIENT_SECRET\"],\"AllowedGrantTypes\":[\"implicit\",\"client_credentials\"],\"RedirectUris\":[\"http://localhost:8090\",\"http://localhost:8090/lib\",\"http://localhost:8090/lib/\"],\"PostLogoutRedirectUris\":[\"http://localhost:8090\"],\"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\"]}]",

   3. Save the changes.

9. Set up the access to openssl.pfx certificate.

   1. Open the appsettings.json file in the root Identity Service directory.
   2. Specify the full path to openssl.pfx certificate from the root Identity Service directory in the X509CertificatePath parameter. Use escaped characters.
   3. Save the changes.

10. Switch the Identity Service to HTTPS (optional for development environment). The setup process is similar to switching Creatio to HTTPS. Instructions: Switch a Creatio website from HTTP to HTTPS.

11. Set up the Identity Service logging. Enable logging to verify that the Identity Service operates as expected. For optimal performance, enable logging only while testing and debugging.

    1. Open the web.config file in the root Identity Service directory.

    2. Set the stdoutLogEnabled parameter to "true."

    3. Specify the directory to store the Identity Service logs in the stdoutLogFile parameter. You can leave default parameter value. The directory will be created automatically when you first launch the IdentityService.dll library.

    4. Save the changes.

    5. Open the appsettings.json file in the root Identity Service directory.

    6. Configure the log level.

       appsettings.json file

       "Logging": {
         "LogLevel": {
           "Default": "Debug"
         }
       }

       Specify the log level based on your business goals. Learn more: Define the log rules (developer documentation).

    7. Save the changes.

As a result:

• The application pool and website for Identity Service will be created.
• The Identity Service will be launched.
• The Identity Service will create a set of database tables (Fig. 6).
• The client settings from the appsettings.json file will be added to the "Clients" database table.

Fig. 6 Database tables created by Identity Service

If you need to change the client settings:

1. Delete the record from "Clients," "ClientScopes," "ClientSecrets," "ClientClaims" Identity Service database tables.
2. Relaunch the IdentityService.dll library.
3. Restart the Identity Service application pool.
4. Test the Identity Service.

Install the Identity Service using Docker

1. Extract the IdentityService.zip archive to an arbitrary directory in the root Creatio directory. For example, "IdentityService."

2. Connect the website to your Creatio DBMS. You can do this in multiple ways:

   • Modify the appsettings.json file in the Identity Service root directory before building.
   • Modify the Dockerfile-OAuth file and add environment variables using the ENV directive. For example, specify "Postgres" in the ENV DbProvider parameter. The parameter value will be set when the container starts.
   • Specify the environment variables when running the container. For example, use the docker run --env=DbProvider=Postgres command.

   Regardless of the chosen method, configure the following parameters:

   Parameter	Parameter value
   DbProvider	"MsSqlServer" or "Postgres"
   MsSqlConnection or PostgresConnection	Use the same connection string you specified in the connectionString attribute of the ConnectionStrings.config file.

   The user that connects to the database must have permissions to create and update the tables.

   If you need to connect the Identity Service to Creatio that uses Oracle DBMS, deploy an additional PostgreSQL or Microsoft SQL database instance.

3. Set up the Identity Service system client. To do this, modify the file parameters. The Identity Service uses these values to interact with Creatio. All parameters support uppercase and lowercase letters, numbers, and special characters, for example, brackets or punctuation marks.

   Parameter	Parameter value	Requirements for parameter value
   ClientId	An arbitrary client ID. For example, "IdServiceUser."	16 characters
   ClientName	An arbitrary client name. For example, "MyIdentityServiceApp."	Any number of characters
   Secrets	An arbitrary client secret. For example, "ItIsMyPasswordForIdentityService."	32 characters

   Example that sets up the Identity Service system client

   "[{\"ClientId\":\"SOME_CLIENT_ID\",\"ClientName\":\"SOME_CLIENT_NAME\",\"Secrets\":[\"SOME_CLIENT_SECRET\"],\"AllowedGrantTypes\":[\"implicit\",\"client_credentials\"],\"RedirectUris\":[\"http://localhost:8090\",\"http://localhost:8090/lib\",\"http://localhost:8090/lib/\"],\"PostLogoutRedirectUris\":[\"http://localhost:8090\"],\"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\"]}]",

4. Build the Docker image. To do this, run the docker build -t creatio-identity-service -f ./Dockerfile-OAuth . command.

5. Run the container using the following command:

   docker run --env=PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin 
   --env=ASPNETCORE_URLS=http://+:80 --env=DOTNET_RUNNING_IN_CONTAINER=true 
   --env=DOTNET_VERSION=6.0.15 --env=ASPNET_VERSION=6.0.15 --workdir=/app 
   -p 80:80 -d creatio-identity-service:latest

6. Switch the Identity Service to HTTPS.

   1. Obtain a digital certificate from the certification center. Instructions: Windows using Linux containers (vendor documentation).

   2. Run the following command:

      docker run --env=PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin 
      -e ASPNETCORE_URLS="https://+;http://+" -e ASPNETCORE_HTTPS_PORT=443 
      -e DOTNET_RUNNING_IN_CONTAINER=true -e DOTNET_VERSION=6.0.15 
      -e ASPNET_VERSION=6.0.15 -e ASPNETCORE_Kestrel__Certificates__Default__Password=SOME_CERTIFICATE_PASSWORD 
      -e ASPNETCORE_Kestrel__Certificates__Default__Path=/https/aspnetapp.pfx 
      -v %USERPROFILE%\.aspnet\https:/https/ --workdir=/app -p SOME_HTTP_PORT:80 -p SOME_HTTPS_PORT:443 
      -d creatio-identity-service:latest

      Parameter	Parameter value	Parameter description
      -e ASPNETCORE_URLS	https://+;http://+	Environment variable that switches the Identity Service to HTTPS
      -e ASPNETCORE_HTTPS_PORT	443	Environment variable that sets the port number for HTTPS
      -e DOTNET_RUNNING_IN_CONTAINER	true	Variables for working via .NET
      -e DOTNET_VERSION	6.0.15
      -e ASPNET_VERSION	6.0.15
      -e ASPNETCORE_Kestrel__Certificates__Default__Password	SOME_CERTIFICATE_PASSWORD	Password for the openssl.pfx certificate
      -e ASPNETCORE_Kestrel__Certificates__Default__Path	SOME_CERTIFICATE_PATH. For example, "/https/aspnetapp.pfx."	Path to the openssl.pfx certificate
      -v %USERPROFILE%.aspnet\https:/https/		Path to the certificate storage
      --workdir	/app	Working directory
      -p SOME_HTTP_PORT:80		Port numbers that map the container to Docker environment. Docker serves the HTTP version of Identity Service via this port.
      -p SOME_HTTPS_PORT:443		Port numbers that map the container to Docker environment. Docker serves the HTTPS version of Identity Service via this port.
      -d		A container startup format. Does not depend on the process that runs the container.
      creatio-identity-service:latest		The name of the Docker image to run.

7. Set up the Identity Service logging. Enable logging to verify that the Identity Service operates as expected. For optimal performance, enable logging only while testing and debugging.

   1. Open the appsettings.json file in the root Identity Service directory.

   2. Configure the log level.

      appsettings.json file

      "Logging": {
        "LogLevel": {
          "Default": "Debug"
        }
      }

      Specify the log level based on your business goals. Learn more: Define the log rules (developer documentation).

   3. Save the changes.

As a result:

• The application pool and website for Identity Service will be created.
• The Identity Service will be launched.
• The Identity Service will create a set of database tables (Fig. 6).
• The client settings from the appsettings.json file will be added to the "Clients" database table.

If you need to change the client settings:

1. Delete the record from "Clients," "ClientScopes," "ClientSecrets," "ClientClaims" Identity Service database tables.
2. Relaunch the IdentityService.dll library.
3. Restart the Identity Service application pool.
4. Test the Identity Service.

2. Test the Identity Service (optional)

To test the Identity Service, access the [Identity Service URL]/.well-known/openid-configuration URL from the browser.

As a result, the list of Identity Service settings will be displayed.

You can set up automated monitoring systems based on OAuth health monitoring. Instructions: OAuth health monitoring. If needed, use Postman to test the Identity Service and check the health of OAuth functionality. The Postman request collection that tests requests is available in Creatio API documentation.

Now you can connect the Identity Service to Creatio. Instructions: Connect the Identity Service to Creatio.

---

See also

Connect the Identity Service to Creatio

Generate OAuth 2.0 client credentials

OAuth health monitoring

Authorize external requests using OAuth 2.0 (developer documentation)

NLog (developer documentation)

---

E-learning courses

Tech Hour - Integrate like a boss with Creatio, part 2 (Odata)