Enable and Configure an External Database for Enrollments

Instant ID as a Service supports using records on an external Oracle, SQL Server, MySQL, or PostgreSQL database to issue credentials. Instant ID as a Service accesses the database(s) with Entrust Identity as a Service Gateway, allowing administrators to connect the fields of an enrollment design to a table in an external database and assuring secure communication between Instant ID as a Service and the database.

Note: Entrust does not support applications or databases that are no longer supported by their vendor.

Note: Microsoft Azure SQL Cloud Database connectivity is not supported as an Instant ID as a Service Issuance External Database.

For more information on configuring external databases, refer to the How to use an External Database - Instant IDaaS video tutorial.

Note: Connecting two external database sources to one Enrollment Design field can have unexpected results and is not recommended.

The external database feature is only available with the Professional version of Instant ID as a Service.

Note: Using an external database requires installing Entrust Identity as a Service Gateway. For more information, refer to Manage Gateways

Allowable image-file sizes depend on the limits of the external database in use. Instant ID as a Service can read and store images as BINARY, BLOB, BYTEA, LONGBLOB, LONGVARBINARY, MEDIUMBLOB, TINYBLOB, or VARBINARY data types, depending on the external database in use. Refer to Supported Data Types to see which types Instant ID as a Service supports for each database.

Instant ID as a Service supports connecting Smart Card Profiles to Enrollment Designs configured for use with an external database. Refer to Enable and Configure Smart Card Profiles and to Connect an External Database to a Smart Card Profile for more information.

Instant ID as a Service supports connecting Mobile Flash Pass Designs to Enrollment Designs configured for use with an external database. Refer to Design Mobile Flash Passes and to Configure an Enrollment Design for Both Mobile Flash Pass and External Database for more information.

Instant ID as a Service supports writing to an external database with an Issuance API with permissions to create, read, update, and/or delete enrollments. Refer to Add an Issuance API and to the Entrust Instant ID as a Service Issuance API Administration Guide for more information.

Instant ID as a Service does not support exporting records from an external database.

Support for Reading and Writing Images as Files on a File System

Instant ID as a Service allows you to read and write images as files in your file system instead of storing them as BLOBs (Binary Large Objects). If you have images stored in an existing shared drive, you can mount the shared drive to an external database from the Identity as a Service Gateway via Linux. Refer to Install Identity as a Service Gateway to install the Gateway.

Instant ID as a Service supports images reading and writing images as files if the shared drive containing the image files is mounted to an external database. Refer to Mount a Shared Drive Connection to an External Database after the Identity as a Service Gateway is installed.

Install Identity as a Service Gateway

Note: Only administrators with Enterprise Gateway and Agents Management permission to administer Gateways. For Enterprise Service Gateways that connect to Instant ID as a Service, you must configure your firewall to allow connections to your Instant ID as a Service account over HTTPS on port 443. If you whitelist outbound connections, you need to whitelist entrust.net, entrust.us.trustedauth.com, and the URL for your Identity as a Service account for the Gateway to function refer to Manage Gateways for more information.

  1. Click Main Menu menu button > Administration > Resources > Gateways. The Gateways List page opens.
  2. Click the Identity as a Service Gateway button. The Identity as a Service Gateway Download URL dialog box appears.
  3. Click either the VMWARE VSPHERE button or the MICROSOFT HYPER-V button to download an image file on either platform.
  4. Install the image file.

Note: Consult the VMWare vSphere or Microsoft Hyper-V documentation for more information.

Add a Gateway to Instant ID as a Service

  1. Click Main Menu menu button > Administration > Resources > Gateways. The Gateways List page opens.
  2. Click Add on the Gateways List page in Instant ID as a Service. The Add Gateway dialog box appears.
  3. Enter a Gateway Name.
  4. Click Add to add the gateway. The Add Gateway dialog box displays the Registration Code.
  5. Click the Copy to Clipboard to copy the Registration Code.
  6. Open the Identity as a Service Gateway web interface or application to configure the gateway. For more information on creating and adding and managing gateways, refer to Manage Gateways.
  7. Paste the Registration Code into the registration parameters for the gateway.
  8. Save the configuration and register the gateway.

Add an External Database

  1. Click Main Menu menu button > External Databases. The External Databases page opens.
  2. Click the Add icon . The Add External Database dialog box appears.
  3. Enter a Name to identify the database in Instant ID as a Service.
  4. Select a Type from the list of supported database engines.
  5. Enter the URL of the database, or select the checkbox beside Configure individual properties?.  
    1. If the checkbox beside Configure individual properties? has been selected: 
      1. Enter the Server name or IP address. For SQL Server databases, use the instance port number instead of the instance name.

        2. Note: Set the portNumber when connecting to a named instance.

      2. Enter the Port.
      3. Enter the Database for a MySQL, PostgreSQL, or SQL Server database, or the Service for Oracle databases.
  6. Enter the Schema of the database. (The field does not appear for MySQL databases.)
  7. Enter your Username.
  8. Enter your Password. 
  9. (Optional) Select the checkbox beside Use SSL? to secure communication between the gateway and database.
    1. Upload the required certificates for the database type. For more information, refer to Secure an External Database Connection.
  10. Click Add.

Mount a Shared Drive Connection to an External Database

Instant ID as a Service allows the option to read and write images to a file system by mounting a shared drive connection to an external database via previously installed Gateway. Refer to Install Identity as a Service Gateway to install a Gateway. Refer to Add a Gateway to Instant ID as a Service to add the Gateway to Instant ID as a Service.

  1. Log into the Gateway via web browser and select Terminal from the left hand navigation menu. If this puts you in the Configuration Tool, type "exit" to exit to a shell.
  2. Create a mount point:
    1. sudo mkdir /mnt/share
  3. Create a credentials file for Samba with user credentials that have read/write access to the share:

    1. tee /home/entrust/.smbcredentials<<EOF 

      username=<shareuser>

      password=<sharepassword>

      domain=<domain or workgroupname>

      EOF

  1. Replace the placeholder values (e.g, <shareuser>, <sharepassword>, <domain>, and <workgroupname>) with those of an authorized account. To use a local user of the server with the share, set domain=<fully distinguished server name>.

  2. Change the access permissions and special mode flags of file system objects.

chmod 0600 /home/entrust/.smbcredentials

Note: Follow the steps in this note to further edit .smbcredentials:

vi /home/entrust/.smbcredentials

  1. To save and exit, press Esc + w + q.

    or

  2. To exit without making changes, press Esc + q + !.

     

  1. Add a network share mount point to the file system table. The first example (6a.) is for Windows, the second example (6b.) is for Linux/Unix.  Note: The "//<server>/<path> /mnt/share cifs credentials=/home/entrust/.smbcredentials,uid=acsservice,gid=acsservice 0 0" command in step (6a.) must be written on one line.

    1. sudo tee -a /etc/fstab <<EOF

      //<server>/<path> /mnt/share cifs credentials=/home/entrust/.smbcredentials,uid=acsservice,gid=acsservice 0 0 

      EOF

    2. sudo tee -a /etc/fstab <<EOF

      <server>:/<path> /mnt/share nf nosuid,rw,sync,hard,intr 0 0

      EOF

Note: Do not forget to enter "-a" as referenced in the Windows and Linux examples above. Replace the placeholder value <server> with the fully distinguished server name or IP address. Replace the placeholder value <path> with the path on the server to the images, not including a drive letter.

Note: Above commands are to add entry in /etc/fstab file. To update (add/remove entries) /etc/fstab, use standard Linux commands, for example:

  1. sudo su

  2. Enter password

  3. vi /etc/fstab

    To save and exit, press Esc + w + q.

    or

    To exit without making changes, press Esc + q + !.

 

  1. Reload the daemon to apply the changes made to the file.

    1. sudo systemctl daemon-reload

  2. Mount the network share. This will mount the entries added in /etc/fstab:
    1. sudo mount -av

    If the credentials are wrong, or Enterprise Service Gateway cannot access the path, there will be errors while mounting. Verify the credentials in .smbcredentials or verify the server path.

  3. Verify the contents of the network share. The following command should return the file names of all the files on the actual shared drive:
    1. ls -al /mnt/share

Note: Mount multiple folders by repeating step 2. Next, follow step 6 (a.) or 6 (b.), step 7 to mount the network share, and then step 8 to verify the contents. Of course, use a different mount name than /mnt/share (e.g, /mnt/share2).

Note: Instant ID as a Service users cannot upgrade from versions 5.32 to 5.33. After installing the new 5.33 gateway, users must complete the entire file mount operation.

 

Configure an Enrollment Design

  1. Click Main Menu menu button > Enrollment Designs. The Enrollment Designs page opens.
  2. Select the Enrollment Design to link with an external database.
  3. Click Settings Enrollment Design Settings.
  4. Select Use External Database? .
  5. Choose an External Database from the drop-down list. A confirmation dialog box appears.

    6. Note: Changing an enrollment design to use an external database will result in the loss of any enrollment data in the cloud.

  6. Click Save.
  7. Remove any Quick start primary key column in the Enrollment Design previously connected to the cloud database.
    1. Open the Enrollment Design.
    2. Click on the Quick Start primary key field.
    3. Press the Delete key on your keyboard.
    4. Click SaveSave Enrollment Design.

Note: Bulk operations (import and export) are not supported for enrollment designs configured to use an external database.

Configure Field Connections

  1. Open the Field Connections page for the Enrollment Design linked to an external database.
  2. Ensure the Source has been set to External Database.
  3. Click the Table drop-down menu to choose a table from the database. The Connect fields from the source to the Enrollment Design panel displays the table's columns.
  4. Connect the Table Columns to the desired fields of the Enrollment Design.

    5. Note: Fields connected to an Identity primary key column should be set to read-only.

  5. Click Save.

Note: Connecting two external database sources to one Enrollment Design field can have unexpected results and is not recommended.

For more information, refer to Field Connections.

Connect an External Database to a Smart Card Profile

  1. Click Main Menumenu button >Enrollment Designs. The Enrollment Designs page opens.
  2. Select the Enrollment Design with fields connected to a Smart Card Profile to link with an external database.
  3. Click SettingsEnrollment Design Settings.
  4. Select Use External Database?.
  5. Choose an External Database from the drop-down list. A confirmation dialog box appears.
  6. Click Save.
  7. Return to the Enrollment Designs page.
  8. Select Field ConnectionsField Connections to edit the field connections for that enrollment design. The Field Connections page opens.
  9. Verify the source field connections from the Enrollment Design column display the tables from the external database.
  10. Click the Table drop-down menu to choose a table from the database.
  11. Verify the fields from the chosen table appear in the Table column. The Connect fields from the source to the Enrollment Design panel displays the table's columns.
  12. Connect the Table Columns to the desired fields of the Enrollment Design connected to the Smart Card Profile.

For more information, refer to Enable and Configure Smart Card Profiles.

Configure an Enrollment Design for Both Mobile Flash Pass and External Database

  1. Click Main Menumenu button >Enrollment Designs. The Enrollment Designs page opens.
  2. Select the Enrollment Design with fields connected to a Mobile Flash Pass Design to link with an external database. For more information, refer to Map Mobile Flash Pass Fields.
  3. Click SettingsEnrollment Design Settings.
  4. In the Database Settings section:
    1. Select Use External Database?.
    2. Choose an External Database from the drop-down list. A confirmation dialog box appears.

      3. Note: For more information on how to further customize the permissions Instant ID as a Service has with enrollment data, refer to Configure Enrollment Design Settings.

  5. Click Save Save Enrollment Design. A confirmation dialog box appears.
  6. Return to the Enrollment Designs page.
  7. Select Field ConnectionsField Connections to edit the field connections for that enrollment design. The Field Connections page opens.
  8. Set the Source to External Database.
    1. Follow the steps in Configure Field Connections to link the enrollment design to the external database selected in Step 6.

      2. Note: If the Table that was selected does not have a primary key, designate one of the columns to be the primary key.

  9. Click Save .
  10. Set the Source to Mobile Flash Pass Design.
  11. Select the desired Mobile Flash Pass Design from the drop-down menu.
  12. Connect the Mobile Flash Pass Fields to the desired fields of the Enrollment Design connected to the external database.
  13. Click Save.

Note: The Managed Mobile Flash Pass feature will not work for External Database enrollment records if the primary key value of the enrollment record is changed after sending the Mobile Flash Pass.

Troubleshooting

Instant ID as a Service may return an error "The requested operation could not be performed" when attempting to write data to an external database. This occurs when the external database rejects the incoming data due to a discrepancy such as a duplicate primary key.

  1. Log into Entrust Identity as a Service Gateway.
  2. Navigate to Logs.
  3. Select Recent, Everything, and agent-database-proxy. This will show the most recent log entries in reverse-chronological order.
  4. Search the logs for the term "Database error".
  5. Interpret the SQL error.

SQL errors are usually caused by a configuration error in the Enrollment Design setup. The most common errors and their causes include:

  • Conversion failed: Typically caused by data entered that didn’t comply with the field type connected to a given database column (e.g., alphabetic characters entered in a column connected to a date field)

  • Incorrect Syntax near the keyword ‘null’: Typically caused by an incorrect Schema name in external database configuration.

  • Cannot insert explicit value for identity column in table: Typically caused by not setting as "Ready Only" a field connected to a column containing the database table's auto-generated primary keys for the database table is auto-generated by database

Supported Data Types

Oracle MySQL SQL Server PostgreSQL
BLOB BIGINT BINARY BIGINT

CHAR

 BLOB BIGINT BYTEA
CLOB CHAR CHAR CHARACTER VARYING
DATE DATE DATE DATE
LONG DATETIME DATETIME DECIMAL
NCHAR DECIMAL DATETIME2 INTEGER
NCLOB DOUBLE DATETIMEOFFSET NUMERIC
NVARCHAR2 FLOAT DECIMAL REAL
VARCHAR2 INTEGER FLOAT SMALLINT
  LONGBLOB INT TEXT
  LONGTEXT NUMERIC TIME
  MEDIUMBLOB NVARCHAR(MAX) TIMESTAMP
  MEDIUMINT REAL  
  MEDIUMTEXT SMALLDATETIME  
  SMALLINT SMALLINT  
  TEXT TINYINT  
  TIME VARBINARY(MAX)  
  TIMESTAMP VARBINARY  
  TINYINT VARCHAR  
  VARCHAR VARCHAR(MAX)

 

IMPORTANT: When connected to a SQL Server database, Instant ID as a Service does not support columns of NTEXT, TEXT, or IMAGE data types because they will be removed in a future version of SQL Server. Use NVARCHAR(MAX), VARCHAR(MAX), and VARBINARY(MAX) instead.

Note: Instant ID as a Service supports Oracle Database 19c, PostgreSQL 16.1, MySQL 8.0.27, and SQL Server versions 2019, 2017, and 2016.

Note: Entrust does not support applications or databases that are no longer supported by their vendor.

Note: Microsoft Azure SQL Cloud Database connectivity is not supported as an Instant ID as a Service Issuance External Database.

Note:Instant ID as a Service restricts using MySQL 8 keywords and reserved words as field names for credentials. Vendor-specific MySQL 8 keywords and reserved words used in table names and schemas in external databases will also cause errors. Refer to the list of MySQL 8 keywords and reserved words.