User Authentication

User authentication is the process of verifying the identity of a person who attempts to access an iCore system. It is possible to configure an iCore System to support the following types of user authentication:

• Username and password
  OR
• Open ID Connect (OIDC)

note

Authentication is often confused with authorization, which describes what the user is allowed to do once they have been authenticated and has access to the system. In an iCore system, authorization is handled with User groups, or externally in an Azure AD.

The process of configuring User authentication in the iCore system is described in the topic Configuring a system. This topic mainly contains information for those who want to configure authentication with Open ID Connect (OIDC).

Authentication with username and password

Authenticating with username and password does not require any advanced configuration in iCIS. However, each User that should authenticate with username and password must be configured for that purpose, see Configuring a system.

Authentication with Open ID Connect (OIDC)

OIDC is a standard for delegation of user authentication, which is supported by several well-known authentication providers. The term Open ID Connect provider is often referred to as "OP". There are many factors to consider when selecting an OP for user authentication, which is why we cannot make any specific recommendations. However, if an OP is already used for other applications in your organization, it may be the natural choice to use for user authentication in iCore systems as well.

For more information about OIDC, see https://openid.net/connect/.

1. Gather required information from your OP

Refer to your selected OP documentation and application configuration and retrieve the information listed below regarding the application that is to be used to authenticate iCore Users. If no application exists, it must first be created.

Information	Comment
Application display name	Only used for display purposes by iCore.
Client id	May also be referred to as "application id".
Client secret	Optional
Authority URI	The URI that is used for authorization, may be referred to as "authorization endpoint". For some providers the web-finger endpoint will also work, may also be referred to as "OIDC metadata endpoint".
Authority display name	Only used for display purposes by iCore.
Token endpoint	The URI of the endpoint from which tokens are retrieved. Not mandatory if the authorization provider supports endpoint-discovery, i.e. all standard endpoints, which includes token endpoint, can be retrieved from the authority URI. Endpoint discovery is part of the Open ID Connect specification but it is not mandatory for OP to implement it.
Username claim	The first time a user logs in with OIDC to an iCore system, it will be connected to an existing iCore User in the system. iCore Users are given a name that is used to connect them to users from the OP. This connection is done by matching the iCore User’s Name property to a certain claim value of the authenticated user. Decide what claim from the user info endpoint will be used during the connection process. This claim should be retrievable from the OP's user info endpoint and should uniquely identify the user within the OP (see illustration below).
Identification claims	Once an OP user has been connected to an iCore User, it is identified based on the subject claim (sub) that is received in the identity token from the OP. However, in some scenarios this is not enough – for example when the subject claim is not the same across multiple OP applications that is used for the iCore systems that a user needs access to. Identify what claim (or combination of claims) that can be used to identify a user across applications. Claims can originate either from the identity token or from the user info endpoint.
Scopes	A scope specifies a set of claims that can be requested from an OP. Depending on what Username claim and Identification claim is used, you may need to specify the scopes associated with these claims. By default, the "profile" scope is always requested, and all claims associated with it will be available. For example, if the email claim is to be used as Username claim, then a scope called "email" must be requested. Which scopes (and claims) are available is provider-specific. The user will be asked for their consent to share the user information implied by the specified scopes with iCore.
Contents of Id-token	Is c_hash (access code hash) included? Is at_hash (access token hash) included? Is Id-token signed? The OIDC system login will perform certain validation of the id-tokens that are received from the OP. Some claims of the id-token that may be validated are not mandatory and validation can be configured accordingly. For available validation options, see the Authorization provider configuration section in the System settings
Refresh tokens	Is Id-token included?
Transport security	Do all endpoints support https?

Remarks

Client secret expiration

If a client secret is used by the OP, it is likely to expire at some point. Before this happens, make sure to update the configuration with a new client secret. For more information about updating the client secret with Powershell cmdlets, see Using cmdlets.

Identification claims

Examples of claims that can be specified:

• Claims tid (from identity token) + oid (from identity token) can be used for Azure if cross-application sign-in is allowed.
• Claims aud (from identity token) + sub (from identity token) can be used for Azure if cross-application sign-in is not allowed without the user authenticating for each system (application) that they access.

This illustration shows how an authenticated OP user is connected to an iCore User at first login to an iCore System.

 

note

The selected claim must be able to uniquely identify the iCore User and the OP user.

If the authentication provider application requires configuration of redirect URIs (and if they do not already exist) they need to be added as follows:

Purpose	Type	URI
Tools and PowerShell cmdlets	Public/native client	http://localhost
Administrator	Web	https://address.to.your.site/RedirectLogin

2. Configure an authentication provider

Open the System settings and enter the information that was retrieved in the previous step or use the Set-iCoreAuthenticationProvider cmdlet.

Powershell example

$identificationClaim1 = New-Object iCore.PS.Commands.IdentificationClaim
$identificationClaim1.ClaimName = "tid"
$identificationClaim1.ClaimSource = [iCore.PS.Commands.IdentificationClaimSource]::IdentificationToken
$identificationClaim2 = New-Object iCore.PS.Commands.IdentificationClaim
$identificationClaim2.ClaimName = " userPrincipalName"
$identificationClaim2.ClaimSource = [iCore.PS.Commands.IdentificationClaimSource]::UserInformation
Set-iCoreAuthenticationProvider -ID 10 -Username BobTheAdmin -Password abc123456 `
   -ApplicationName "iCore systems" `
   -Authority "https://login.microsoftonline.com/481FA1D4/v2.0/.well-known/openid-configuration" `
   -AuthorityDisplayName "Microsoft" `
   -ClientId "553D122D-6E29-4A26-B9A9-A455E1604618" `
   -ClientSecret "F6CAACF86768" `
   -UserNameClaim "userPrincipalName" `
   -IdentificationClaims @($identificationClaim1, $identificationClaim2) `
   –ValidateIssuerName $false `
   -Scopes @("openid", "email")

3. Configure Users

To enable OIDC login for a User, set the Authentication Type property on the User to Open ID Connect and assign the username claim value of an OP user to the Name property of the iCore User.

User configuration can either be done manually in the Administrator or with PowerShell cmdlets.

Powershell example

An existing iCore user is configured to login with OIDC. The user name is set to the user princpal name of the corresponding OP user.

$user = Get-iCoreEntity -id 10 -Username BobTheAdmin -Password abc123456 -Type User | Where-Object { $_.Name -eq "JohnDoe"}
$user.AuthenticationType = [iCore.Public.Entities.UserAuthenticationType]::OpenIDConnect 
$user.Name = "john.doe@theProvider.net"
Save-iCoreEntity $user

OIDC login from Administrator

If an iCore system is configured with an OP, OIDC authentication will be the default authentication method when logging on to the system in the Administrator tool. If a user clicks the node of such a system in the system explorer tree, they will be automatically redirected to the system's configured OP and then redirected back to the Administrator after successful authentication. If a matching iCore System User is found (see above), the user will be logged on to the system (with the authorization of the matched iCore System User, see User Groups).

If a user is already authenticated with the configured OP from a previous session, they would generally not be prompted for authentication again. However, this may depend on the third-party OP implementation.

When a user logs out from an OP-configured iCore system, they can choose to only log out from the selected system in the Administrator (default), or to log out from the OP entirely which means logging out from all systems that use the OP for authentication.

OIDC login from the Administrator makes use of two endpoints which are passed on to the OP together with application URI (commonly named "redirect URI") when performing login and logout requests. The endpoints are:

• /systems/OidcSystemLoginRedirect
• /systems/OidcSystemLogoutRedirect

note

If the OP requires you to pre-register redirect URIs you must register these endpoints or the redirect back to the Administrator will fail. For example, if the Administrator is installed at http://localhost/admin, you need to register the following redirect URIs:

• http://localhost/admin/systems/OidcSystemLoginRedirect
• http://localhost/admin/systems/OidcSystemLogoutRedirect

note

If your Administrator site is behind a load balancer or reverse proxy which implements the HTTP headers X-Original-Host and X-Original-URL you can use the cmdlet Set-iCoreAdminOidcSettings with parameter DynamicRedirectUriType to pass the original host name via OIDC state ("UseOriginalHostAsStateParameter" or "UseEncryptedOriginalHostAsStateParameter") or alter redirect URL ("UseOriginalHostInUrl"). You also need to set parameter RedirectUri which is the address the Administrator application is hosted at.

If you choose to send the original host name via state parameter you will also need to add the following redirects for your Azure AD application:

• https://myicoresite.example/RedirectLoginProxy
• https://myicoresite.example/RedirectLogoutProxy

Single Sign-On (SSO) with OIDC in Administrator

To achieve Single Sign-On (SSO) for the Administrator, you need to configure the same OP for both the Administrator site login as well as for the System login.

When both the site and the system(s) are configured to use the same OP, the user will only be prompted for authentication when logging on to the Administrator site. The user will be automatically authenticated for any system that uses the OP when they select the system node in the System explorer tree (provided that the user is authorized to view the system, see User Groups).

If cookies are allowed to be stored in the browser between sessions, the user will not be prompted for authentication the next time they access the Administrator via the (same) browser.

OIDC login from iCore tools

When starting an iCore tool (for example, the Developer tool) from the Windows explorer or from the command line, the user will be prompted to log in. If the selected System is configured with an OP, there will also be an option to log in using OIDC. If the OIDC options is used, the tool launches a system web browser (i.e. the browser that is selected as the default web browser in the operating system), and the OP's sign-in page is displayed. After the user has successfully authenticated with the OP, the browser is closed and the user will be logged in to the iCore system.

note

Note that some browsers (for example Opera and Firefox v73.0 and later) may not close automatically. If that is the case, the user is prompted to close the browser manually after successful authentication.

Remarks about browser support

Supported system-default browsers are:

• Edge (chromium-based only (released in january 2020). Earlier versions of Edge are not supported)
• Internet Explorer (IE)
• Chrome
• Firefox
• Opera

The browser that is launched is started in "private mode" (may be called Private, Incognito, or InPrivate mode depending on the browser), which means it will not be possible to reuse any existing sessions with the OP that may have been initialized from another instance of the browser. If you are having problems launching the system browser and decide to start a different browser, carefully consider if you are on a machine/user session where you may not want to share the authenticated session in the web browser, i.e. if the browser is to be started in private mode or not. You may want to sign out from the OP after authentication is complete if you are on a machine/user session that is not your own.

If you experience problems with launching a browser during user authentication from an iCore tool, contact iCore support.

See Also

System settings
iCore PowerShell cmdlets
Using cmdlets

Entities

User

Administrator

Configuring a system