Setting Up the Hyland IdP Server From the Command Line - Identity and Access Management Services - 4.4 - 4.4 - Ready - Other - external

Identity and Access Management Services
Platform
Other
Product
Identity and Access Management Services
Release
4.4
License

After preparing the environment for initialization, you must set up the Hyland IdP server by completing the base configuration for it.

Note:

It is assumed that the environment has already been prepared for setting up the Hyland IdP server. If you have not yet prepared the environment, first complete the instructions under Preparing the Environment for Initialization.

Configuration can be completed using the Hyland.Identity.Server.Initialization.dll command line utility. This section includes the instructions to use the command line utility.

Tip:

The same actions can also be completed using the graphical initialization client. See Setting Up the Hyland IdP Server.

To set up the base configuration for the Hyland IdP server:

  1. Open a Windows command prompt with elevated administrator privileges.
    Tip:

    It is recommended to use Windows PowerShell to run command line operations.

  2. Change to the directory where the Hyland.Identity.Server.Initialization.dll is saved. In a default installation, the DLL is located in C:\Program Files\Hyland\Hyland Identity Provider Server Initialization Utility\.
  3. Type the initialize command, but do not run it yet.
    dotnet Hyland.Identity.Server.Initialization.dll initialize
  4. Append the following switches and their values to the initialize command. Be sure to enclose the values in double quotation marks.

    Switch

    Value

    --publicorigin

    The root URL of the server in IIS hosting the Hyland IdP server. Do not include the virtual directory of the Hyland IdP server in the Public Origin value.

    For example, if the URL of the Hyland IdP server is https://server.domain.com/identityprovider, then the Public Origin value is https://server.domain.com

    Note:

    The Hyland IdP server must be configured for secure connections (HTTPS).

    --issuer

    The URL of the Hyland IdP server.

    For example, if the public origin of the Hyland IdP server is https://server.domain.com and the default application name is used, then the Issuer value is https://server.domain.com/identityprovider

    Note:

    The Hyland IdP server must be configured for secure connections (HTTPS).

    --config

    The full file path of the idpconfig.json configuration file. In a default installation, the configuration file is located at:

    C:\Program Files\Hyland\identityprovider\idpconfig.json

    In load-balanced environments, each server should use the same idpconfig.json file. If a single, shared file cannot be used, the idpconfig.json files must be exactly the same between servers.

    Note: This setting is required for each server in a load-balanced environment.

    Enter a valid UNC path to the location of the idpconfig.json configuration file if the file is located on a remote server.

    Note:

    The identity running the Hyland IdP server application pool must have Modify access to the idpconfig.json file.

    --useidpmanagedsigningcert

    Allows Hyland IdP to automatically generate and manage the signing certificate. Hyland IdP uses the auto-generated signing certificate to sign the newly-issued tokens.

    For example, an initialization command with the --useidpmanagedsigningcert switch set to true may look like the following:

    dotnet Hyland.Identity.Server.Initialization.dll initialize  --publicorigin "https://server.domain.com"  --issuer "https://server.domain.com/ identityprovider"  --config " C:\Program Files\Hyland\identityprovider\idpconfig.json "  --scimclientsettingsproxy ""  --keyfilepersistencelocation "%LOCALAPPDATA%\ASP.NET\DataProtection-Keys \" "  --keyencryptioncertificatethumbprint ""  --appsettings "C:\test\InitializaTest\appsettings.json"  --useidpmanagedsigningcert "TRUE"

    Similarly, an initialization command with the --useidpmanagedsigningcert switch set to true and a preset signing certificate may look like the following:

    dotnet Hyland.Identity.Server.Initialization.dll initialize  --publicorigin "https://server.domain.com"  --issuer "https://server.domain.com/ identityprovider"  --config " C:\Program Files\Hyland\identityprovider\idpconfig.json "  --signingcertificate "<certificate thumbprint>"  --scimclientsettingsproxy ""  --keyfilepersistencelocation "%LOCALAPPDATA%\ASP.NET\DataProtection-Keys \" "  --keyencryptioncertificatethumbprint ""  --appsettings "C:\test\InitializaTest\appsettings.json"  --useidpmanagedsigningcert "true"
    Note: The --useidpmanagedsigningcert flag can only be set to true or false.

    --signingcertificate

    The RSA certificate being used for encryption, which can be found in the IIS bindings or in the Windows Certificate Store. The certificate must include digital signatures key usage and be placed in the personal store of the local machine.

    Note:

    The IIS_IUSRS account must have Read access to the private key of the signing certificate. For details on configuring certificate permissions, see the documentation provided by Microsoft for Manage Computer Certificates.

    --scimclientsettingsproxy

    The proxy behavior the Hyland IdP server uses to communicate with the Hyland SCIM server.

    Enter Default to use the proxy behavior defined by .NET Core, NoProxy to always bypass the proxy, or System to use Microsoft Internet Explorer settings to define the URLs that bypass the proxy.

    By default, the Hyland IdP server uses the proxy behavior defined by .NET Core.

    --keyfilepersistencelocation

    The fully qualified UNC path of the common directory where the keyfile used for encrypting and decrypting cookies, tokens, and other values is stored. In load-balanced environments, each server must use the same keyfile location.

    Note: This setting is required for each server in a load-balanced environment.

    By default, the ASP.NET\DataProtection-Keys directory within the local application data directory is used, but that location is not accessible by other servers.

    Note:

    The identity running the Hyland IdP server application pool must have Modify access to the keyfile location in order to create and store keyfiles.

    --keyencryptioncertificatethumbprint

    The thumbprint of the RSA certificate being used for encryption, which can be found in the IIS bindings or in the Windows Certificate Store.

    The encryption certificate must include digital signatures key usage and be placed in the personal store of the local machine. The same certificate must be used for each Hyland IdP server in a load-balanced environment.

    Note: This setting is required for each server in a load-balanced environment.
    Note:

    The identity running the Hyland IdP server application pool must have Read access to the private key of the encryption certificate. For details on configuring certificate permissions, see the documentation provided by Microsoft for the Certificate Manager tool.

    --appsettings

    The full file path of the appsettings.json file. In a default installation, the full path of the appsettings file is C:\Program Files\Hyland\identityprovider\config\appsettings.json

    For example, a completed initialize command may look like the following:

    dotnet Hyland.Identity.Server.Initialization.dll initialize --publicorigin                        
                    
    "https://server.domain.com" --issuer "https://server.domain.com/identityprovider" --config "C:\Program Files\Hyland\identityprovider\idpconfig.json" --signingcertificate "<signing certificate>" --scimclientsettingsproxy "<proxy setting>" --keyfilepersistencelocation "%LOCALAPPDATA%\ASP.NET\DataProtection-Keys\" --keyencryptioncertificatethumbprint "<RSA certificate thumbprint>" --appsettings "C:\Program Files\Hyland\identityprovider\config\appsettings.json"
  5. Press the Enter key to run the initialize command.
    If any errors are reported, they must be corrected and the command run again. The command returns the Service Account Client ID and its secret if no errors are encountered. See Service Account Client for details.
  6. Type the add-tenant command, but do not run it yet.
    dotnet Hyland.Identity.Server.Initialization.dll add-tenant
  7. Append the following switches and their values to the add-tenant command. Be sure to enclose the values in double quotation marks.

    Switch

    Value

    --tenant

    The name of the tenant used by the Hyland IdP server. The tenant name must not contain any special characters such as spaces, comma, dot, or slashes.

    Note:

    If your solution uses the Hyland SCIM server, the Tenant Name must match the Name of the datasource configured for the connection string on the Hyland SCIM server. For example, if the SCIM datasource name is MyDBTenant then the tenant Name must also be MyDBTenant.

    --scimurl

    If your solution uses the Hyland SCIM server, enter the URL of the SCIM server endpoint on the Hyland API Server.

    Note:

    The SCIM Url only needs to be configured for OnBase environments. It can be left empty for other environments.

    The SCIM endpoint is the API Server URL with /onbase/SCIM appended to it. For example, if the root URL of the Hyland API Server is https://server.domain.com and the default application name was used, then the Scim Url value is https://server.domain.com/ApiServer/onbase/SCIM

    Note:

    Make sure the use of HTTP or HTTPS matches the configuration of your domain in IIS. The Hyland IdP server must be configured for secure connections (HTTPS).

    --admins

    The user names of those authorized to make configuration changes in the IdP Administration Client.

    Note:

    You must configure at least one user name as an administrative user using the --admins command or at least one user group name as an administrative user using the --admingroups command for each tenant. See the --admingroups switch listed in this table for more information on configuring a user group as an administrative user.

    User names must be entered as a space-separated list, with the user names placed in quotes. For example, if you are entering the user names of manager, John Doe, and user1, they must be entered as "manager" "John Doe" "user1"

    Note:

    The --admins command can be run multiple times to edit the list of administrative users. Every time the command is run, the previous user name entries are replaced with the new user name entries.

    --admingroups

    The user group names of the user groups authorized to make configuration changes in the IdP Administration Client.

    Note:

    You must configure at least one user name as an administrative user using the --admins command or at least one user group name as an administrative user using the --admingroups command for each tenant. See the --admins switch listed in this table for more information on configuring a user as an administrative user.

    User group names must be entered as a space-separated list, with the user group names in quotes. For example, if you enter user group names such as, idpadmins, IIS admins, and managers, they must be entered as "idpadmins" "IIS admins" "managers"

    Note:

    The --admingroups command can be run multiple times to edit the list of administrative user groups. Every time the command is run, the previous user group entries are replaced with the new user group entries.

    --config

    The full file path of the idpconfig.json configuration file. In a default installation, the configuration file is located at:

    C:\Program Files\Hyland\identityprovider\idpconfig.json

    For example, a completed add-tenant command may look like the following:

    dotnet Hyland.Identity.Server.Initialization.dll add-tenant --tenant "MyDBTenant" --scimurl "https://server.domain.com/ApiServer/onbase/SCIM" --admins "manager "John Doe"" --admingroups "idpadmins" "managers" --config "C:\Program Files\Hyland\identityprovider\idpconfig.json"
  8. Press the Enter key to run the add-tenant command.
    If any errors are reported, they must be corrected and the command run again. The command will return nothing if no errors are encountered.
  9. Next, complete the instructions under Creating and Configuring the Operational Database From the Command Line.