Skip to main content
Version: 4.3.0

Configuring an OpenID Connect provider

If you have selected Open ID Connect (sometimes abbreviated to "OIDC") as authentication type for your Administrator site, you also need to configure an OIDC provider. Configuration is performed with PowerShell cmdlets which are available in the iCore.Administrator.Configuration module.

note

To import the iCore.Administrator.Configuration module, run the Load-AdminModules.ps1 script from the correct Administrator version subdirectory, for example C:\Program Files (x86)\iCore Administrator\{Version}\Load-AdminModules.ps1. See also Directory structure.

note

To be able to configure an OIDC provider, the Authentication type for the Administrator site needs to be set to "OpenIdConnect". Authentication type can be set during installation of the site, or with the Set-iCoreWebAdminAuthentication cmdlet.

If you want to see examples of how you can configure Azure AD as your OIDC provider, see Configuring Azure AD as OIDC provider, examples.

Configuring an OpenID Connect provider

To configure an OIDC provider, run the PowerShell cmdlet Set-iCoreWebAdminOidcProvider with parameters identifying your OIDC authentication provider, for example Microsoft Azure Active Directory (AD) or Google.

This example shows how you configure an Azure AD as your OIDC provider:

Set-iCoreWebAdminOidcProvider -SiteName "My iCore Site" `
-Authority "https://login.microsoftonline.com/912a9f3b-7938-4aFD-9c17-318ebc612398/v2.0" `
-ClientId "22a8cb8c-3a79-432a-b7fc-0b89730cd544" `
-RedirectUri "https://myicoresite.example" `
-IdentifierClaims "preferred_username"
  • Before running above cmdlet, replace the Authority and ClientId parameter values with the unique values provided by your authentication provider.
  • Replace the value of the RedirectUri parameter with the base URL (and optionally port) for where the Administrator site is hosted. In the example, the Administrator site is hosted at https://myicoresite.example. iCore Administrator will automatically complete this URL with /RedirectLogin. If the OIDC provider requires configuration of redirect URIs, these need to be registered. For more information, see Redirect URIs below.
  • For the IdentifierClaims parameter, add the claim types that are to be used for authenticating the user, e.g. email address or an ID/GUID provided by your OIDC provider.
  • Optionally you can also request additional scopes by adding Scopes as a parameter. The Scopes "openid" and "profile" are always requested and do not need to be added.
  • If the Administrator site was installed as a web application in an existing site, you must also provide the ApplicationName parameter specifying the name of the application.

Redirect URIs

When performing login and logout requests via OIDC, the Administrator uses two endpoints (referred to as "redirect URIs") which are passed on to the OIDC provider along with the application URI. If the authentication provider requires configuration of redirect URIs (and if they do not already exist), these endpoints needs to be registered in the application at the provider. For more information of how to determine which redirect URIs you need to register, see Register redirect URIs.

Redirect URIs for Azure Application Gateway

If the Administrator site is behind a load balancer or reverse proxy which implements the HTTP headers X-Original-Host and X-Original-URL, for example Azure Application Gateway, you need to decide how to handle redirect URIs during OIDC login and logout. You need to set a DynamicRedirectUriType, which can be set to one of the following options:

  • UseOriginalHostAsStateParameter
  • UseEncryptedOriginalHostAsStateParameter
  • UseOriginalHostInUrl
  • None

DynamicRedirectUriType is set with the cmdlet Set-iCoreAdminOidcSettings. For examples on how to do this, see Configuring Azure AD as OIDC provider, examples.

note

If you choose the options UseOriginalHostAsStateParameter or UseEncryptedOriginalHostAsStateParameter, iCore Administrator will use two additional redirect URIs during authentication, which also need to be registered with the provider. For more information, see Register redirect URIs.

Additional examples can be found in the iCore.Administrator.Configuration module.

Setting a client secret

If your authentication provider requires a client secret, it can be set with the cmdlet Set-iCoreWebAdminOidcClientSecret.

Set-iCoreWebAdminOidcClientSecret -SiteName "My iCore Site" -ClientSecret "ClientSecretValue"
Client secret expiration

The Client secret is likely to expire at some point. Before this happens, make sure to update the configuration with a new client secret. Use Set-iCoreWebAdminOidcClientSecret to set the new client secret.

Configuring authorization using an Azure AD provider

If you have configured Azure AD as your OIDC provider for authentication, you can also configure an Azure AD provider for authorization which allows for RBAC (role-based access configuration) within the Administrator based on group membership from your Azure AD.

note

OIDC provider authorization will still be carried out first, but if the authenticated user cannot be mapped to a configured Administrator site user and role, Azure AD group membership authorization via Microsoft Graph API will be performed instead.

An Azure AD provider is configured with the cmdlet Set-iCoreAdminAzureAdProvider and requires a tenant ID and a client ID from your Azure AD application.

This example uses the same Azure AD application as the example above.

Set-iCoreAdminAzureAdProvider -SiteName "My iCore Site" `
-TenantId "912a9f3b-7938-4aFD-9c17-318ebc612398" `
-ClientId "22a8cb8c-3a79-432a-b7fc-0b89730cd544" `
-Scopes @("User.Read", "GroupMember.Read.All")
  • Running the cmdlet with these parameters will configure and activate Azure AD authorization when OIDC authorization is unable to authorize a user.
  • Replace the values with values provided by your Azure AD application.
  • The Scopes "User.Read" and "GroupMember.Read.All" are generally required for allowing data about user and group memberships to be acquired via Microsoft Graph API. Cmdlets for managing Scopes for Azure AD provider are also available, see iCore.Administrator.Configuration module.
  • To configure mappings between Administrator role and Azure AD group, see Authorization using Azure AD groups.

See also

Configuring Azure AD as OIDC provider, examples
User authentication
Managing Roles and Users
iCore PowerShell cmdlets
Using cmdlets