Client connections are used to handle external client authentication requests using the Hyland IdP server. Each external client using the Hyland IdP server to authenticate needs a client connection configured on the Hyland IdP server to handle those requests.
The Hyland IdP server handles client connections using the OpenID Connect standard. For complete details on configuring client connections using these properties, see the information provided by the developer of the external client you are configuring a connection for.
To configure a client connection on the Hyland IdP server:
-
Launch the Hyland IdP Administration client and log in (see Accessing the Hyland IdP Administration Client).
Upon successfully logging in, the tenant, provider, client connection, and API resource information is displayed. In a wide display, the tenant information is in the left pane and the providers, client connections, and API resources configured for that tenant are listed in the right pane. In a narrow display, the tenant information is at the top of the page and the provider, client connection, and API resource information is below it.
-
Click the Clients tab to view the client connections currently configured for the tenant. The number of client connections configured is displayed in parenthesis in the tab heading.
-
If this is a new client connection, click Add New at the upper right of the client connections list.
If you are configuring an existing client connection, click its name in the list of clients.
The Client configuration page is displayed. It is divided into several areas. In a wide display, the client details area is displayed on the left of the page. In a narrow display, click the Client Details tab to display the Client Details area:
-
At the top of the Client Details tab, or under the Basic Settings area, make sure Enabled is selected then configure the following options.
Option
Description
Client ID
The unique ID of the client connection.
Note:This value should not be changed. For new client connections, the value is generated automatically when the client connection is saved.
Client Name
Note:This value is required.
The display name of this client connection, which is used for logging purposes.
Client Description
A brief description of the client connection used to help identify the clients that can use it to connect.
Protocol Type
The specification used for authorization.
This value should always be set to oidc(the OpenID Connect standard).
Redirect URLs
The allowed URLs to return tokens or authorization codes to.
To add a new URL to the list, type the URL in the field and press Enter. To remove a configured URL, click the cancel symbol next to the URL value.
Note the following:
-
URLs are not validated by the Hyland IdP Administration client.
-
To enable native client applications (such as mobile or desktop clients) to receive loopback authentication redirects, include the loopback address http://127.0.0.1 in this list as well as in the Post Logout Redirect URLs list. Additional client configuration may be required; see the documentation for the client.
Allowed Frame Ancestors
A list of the URIs allowed to produce a frame for the Hyland IdP to authenticate.
This setting provides configuration values for the Content-Security-Policy HTTP response header's frame-ancestors directive. For more information, see the public specification for Content Security Policy (CSP).
Note the following:
-
URI values must be origins only; do not include trailing slashes, paths, or queries.
-
Wildcards and ports are allowed.
-
As a best practice, use HTTPS instead of HTTP.
Examples:
-
https://www.example.org
-
https://*.domain.net
Include X-Frame-Options
Select this option to include the X-Frame-Options HTTP response header to allow cross-domain communication using the ALLOW-FROM directive, such as authenticating embedded content in an iframe.
Note:This option should only be used to support non-standard behavior in web browsers that do not fully support the Content-Security-Policy response header, including Internet Explorer and other older browsers.
Note the following:
-
If this option selected, you must also specify the parent domain URL in the Allowed Frame Ancestors setting.
-
Only one domain value is supported when using X-Frame-Options; any additional domains beyond the first one entered will be ignored.
-
Wildcards are not supported in the domain URL when using X-Frame-Options.
-
-
Under Authentication Restriction Settings, select the Allowed Grant Types the client can use. You must select one or more of the grant types listed:
-
Authorization Code
-
Implicit
-
FHIR JWT Bearer Authorization
Note: The FHIR JWT Bearer Authorization grant type is only available when a FHIR JWT Bearer provider type is configured on the Hyland IdP server. For more information on configuring this provider type, see Configuring a FHIR JWT Bearer Provider. -
Client Credentials
-
Hybrid
-
Password
-
Device Code
Note: For information on this grant type, see Device Code Authorization Flow. -
Token Exchange
-
Addendum Exchange
Note: You must enter a redirect URL in the Redirect URLs field if either the Authorization Code, Implicit, or Hybrid grant types are selected. -
-
If Authorization Code is selected as a grant type, the Pkce options are displayed. Configure the following options for PKCE.
Option
Description
Require PKCE
Select this option to require clients to send a proof key for code exchange (PKCE).
Allow PKCE with a plaintext code challenge
Select this option to allow clients using PKCE to send a plain-text code challenge.
Tip:Allowing a plain-text code challenge is not recommended.
-
Under Authentication Restriction Settings, configure the following options.
Option
Description
Allowed Scopes
Note:This value is required.
The resources this client connection can request a grant for.
By default a client has no access to any resources. Most client connections use the openid resource. To return the group memberships of a user in the access token, include the group scope.
To add a resource to the list, type its name and press Enter. To remove a resource, click the cancel symbol next to the resource name.
Note:Resource names are not validated by the Hyland IdP Administration client.
Allowed Identity Providers
The external IdPs that can be used with this client. Select from the list of configured external IdPs in the drop-down list.
Note: See Configuring Providers for information on configuring external IdPs in the Hyland IdP server.Leave this value empty to allow all IdPs. The default value is empty (all external IdPs are allowed).
User SSO Lifetime
The maximum time allowed since the user was last authenticated. The time is configured in seconds.
Allow users to log in locally
Select to allow this client connection to use local accounts. If this option is deselected, this client connection can only use external IdPs.
The option is selected by default.
Allow clients to request a refresh token
Select to allow the client to request refresh tokens.
Note:If this option is selected, the offline_access scope must also be configured under Allowed Scopes.
Allow issuing access tokens to browsers
Select to transmit access tokens through the browser.
This option is not selected by default.
-
Under Logout, configure the following options.
Option
Description
Post Logout Redirect URLs
The allowed URLs to redirect to after logging out.
To add a new URL to the list, type the URL and press Enter. To remove a configured URL, click the cancel symbol next to the URL value.
Note the following:
-
URLs are not validated by the Hyland IdP Administration client.
-
To enable native client applications (such as mobile or desktop clients) to receive loopback authentication redirects, include the loopback address http://127.0.0.1 in this list as well as in the Redirect URLs list. Additional client configuration may be required; see the documentation for the client.
Front Channel Logout URL
The allowed URLs to redirect to after logging out for HTTP-based front-channel logouts.
To add a new URL to the list, type the URL and press Enter. To remove a configured URL, click the cancel symbol next to the URL value.
Note:URLs are not validated by the Hyland IdP Administration client.
Front Channel Logout requires session ID
Select this option to send session ID of the user to the URL configured as the Front Channel Logout URL.
Back Channel Logout URL
The allowed URLs to redirect to after logging out for HTTP-based back-channel logouts.
To add a new URL to the list, type the URL and press Enter. To remove a configured URL, click the cancel symbol next to the URL value.
Note:URLs are not validated by the Hyland IdP Administration client.
Back Channel Logout requires session ID
Select this option to send session ID of the user to the URL configured as the Back Channel Logout URL.
-
-
Under Token, configure the following options.
Option
Description
Identity Token Lifetime
The lifetime of the identity token, in seconds.
The default value is 300 (five minutes).
Access Token Lifetime
The lifetime of the access token, in seconds.
The default value is 3600 (one hour).
Authorization Code Lifetime
The lifetime of the authorization code, in seconds.
The default value is 300 (five minutes).
Absolute Refresh Token Lifetime
The maximum lifetime of a refresh token, in seconds. The default value is 2592000 (thirty days).
Sliding Refresh Token Lifetime
The sliding lifetime of a refresh token, in seconds. The default value is 1296000 (fifteen days).
Refresh Token Usage
Whether or not the refresh-token handle is updated when the token is refreshed. Select ReUse to use the same handle or OneTime to update the handle.
The default value is ReUse.
Refresh Token Expiration
Sets the expiration behavior of the refresh token. Select one of the following options:
-
Absolute: Forces the refresh token to expire at a fixed point in time that is defined by the Absolute Refresh Token Lifetime value.
-
Sliding: Renew the lifetime of the refresh token by an amount of time defined by the Sliding Refresh Token Lifetime value.
In either case, the length of time will not exceed the amount of time defined in the Absolute Refresh Token Lifetime value.
The default value is Sliding.
Update access token claims upon refresh
Select this option to update the access token and its claims with a refresh-token request.
Access Token Type
Set the type of access token. Select Reference if it is a reference token or Jwt if it is a self-contained JWT token.
The default value is Jwt.
Include unique ID in JWT access token
Select this option to embed a unique ID from the claim in JWT access tokens.
Include user claims in ID token
Select to include user claims with the id token. If this is not selected, the client is required to use the userinfo endpoint.
This option is not selected by default.
Pairwise Subject Salt
The salt value used when generating the pair-wise subject ID for this client connection.
-
-
Under Security, configure the following options.
Option
Description
Allowed Cors Origins
If a client has a cross-origin URL from the Hyland IdP server, meaning the client is under a different domain from the server, you can configure the URL of the client as an Allowed Cors Origin value.
Note:You cannot configure a wildcard (*) as an origin value.
This option is only required if cross-origin URLs are not already listed under the Redirect URLs or the Post Logout Redirect URLs options.
Type a URL origin value and press Enter to add it to the list.
Note:Origin values are not validated by the Hyland IdP Administration client.
Origin values must be entered using the following format, where my.domain is the domain name of the client and xxxx is the port number of the URL: https://my.domain.com:xxxx
Note:Port numbers are only required if the client is accessed with a port in the URL.
To remove an origin, click the cancel symbol next to its value.
-
Under Secret, select Client Secret must be present to require a client secret with requests.
If Client Secret must be present is selected you must add at least one Client Secrets configuration. See Configuring Client Secrets.
- Click Save in the lower right corner of the page.
- Recycle the application pool of the Hyland IdP server in IIS for the changes to take effect.
- Complete the required configuration for the external client so it can use the client connection to the Hyland IdP server for authentication.