Using cmdlets

This topic includes examples of how Cmdlets can be used to configure an iCore system and edit entities.

note

In some of the examples the backquote character(`) is used to allow for oneline expressions to multiline.

Using cmdlets to configure a system

Authentication with Open ID Connect (OIDC)

For more information about user authentication with OIDC, see User authentication.

Update system configuration

This example shows how to configure an iCore system for authentication with OIDC. Users from the OIDC provider (OP) are mapped to iCore system Users through one or several claim(s) of the OP user.

In the example, users are matched based on a combination of the claims tid (tenant ID) and userPrincipalName (user principal name).

$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")

tip

The default value for parameter AuthenticationEnabled is True and can be omitted if the authentication provider is to be enabled immediately.

Enable/Disable

OIDC authentication can be enabled or disabled with Set-iCoreAuthenticationProvider and the parameters listed below.

Parameter	Value	Remark
AuthenticationEnabled	$True	OIDC authentication is enabled using the current configuration.
AuthenticationEnabled	$False	OIDC authentication is disabled. The current configuration is kept.
ResetConfiguration		OIDC authentication is disabled. The current configuration is deleted.

Set-iCoreAuthenticationProvider -ID 10 -Username BobTheAdmin -Password abc123456 -ResetConfiguration

Set-iCoreAuthenticationProvider -ID 10 -Username BobTheAdmin -Password abc123456 -AuthenticationEnabled $False

Update client secret

When the client secret is about to expire and a new one has been issued by the OP, the system configuration needs to be updated with the new client secret.

Set-iCoreAuthenticationProvider -ID 10 -Username BobTheAdmin -Password abc123456 -ClientSecret "E0A27985394B"

Authorization with Azure AD

For more information about user authorization with Azure AD, see User authorization with Azure AD.

Update system configuration

Set-iCoreAzureADSystemConfiguration -SystemID 10 -Username BobTheAdmin -Password abc123456 `
   -ClientId "b9a31ea9-5cd6-4280-8d54-f2737529647a" `
   -TenantId "CC6B8A18-BFD9-45F1-8F98-96BE095F63B0" `
   -ClientSecret "778F07FF-F4CC-4344-B37C-D70C2F7574AE" `
   -Scopes @("User.Read", "GroupMember.Read.All") `
   -IdentificationClaims `
      @([iCore.PS.Commands.IdentificationClaim]::New("someclaim", `
         [iCore.PS.Commands.IdentificationClaimSource]::IdentificationToken), `
         [iCore.PS.Commands.IdentificationClaim]::New("someotherclaim", `
         [iCore.PS.Commands.IdentificationClaimSource]::UserInformation)) `
   -AuthorizationEnabled $True

Configure User group

In this example the iCore User group Users with Id A0CB60FA-A865-4356-8E57-C31ABBA3ADEB is associated with the Azure AD group with OID 621596AD-4672-4697-9439-FBFEAB7C9BE7.

Set-iCoreAzureADUserGroup -SystemID 10 -Username BobTheAdmin -password abc123456 `
   -UserGroupId "A0CB60FA-A865-4356-8E57-C31ABBA3ADEB" `
   -ClaimValue "621596AD-4672-4697-9439-FBFEAB7C9BE7"

Enable/Disable

Authorization is enabled/disabled by setting the AuthorizationEnabled parameter to $True or $False.

Set-iCoreAzureADSystemConfiguration -SystemID 10 -Username BobTheAdmin -Password abc123456 `
   -AuthorizationEnabled $True

Using cmdlets to configure the Administrator site

Authentication with Open ID Connect (OIDC)

For more information about user authentication with OIDC, see Configuring an OpenID Connect provider.

Update site configuration

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/v2.0" `
                              -ClientId "22a8cb8c-3a79-432a-b7fc-0b89730cd544" `
                              -RedirectUri "https://myicoresite.example" `
                              -IdentifierClaims "preferred_username"

Set authentication type

    Set-iCoreWebAdminAuthentication -Site "iCoreWebAdmin" -Authentication "OpenIdConnect"

Update client secret

When the client secret is about to expire and a new one has been issued by the OP, the site configuration needs to be updated with the new client secret.

Set-iCoreWebAdminOidcClientSecret -SiteName "My iCore Site" -ClientSecret "E0A27DB667DC"

Authorization with Azure AD

For more information about user authorization with Azure AD, see to Configuring authorization using an Azure AD provider.

Update site configuration

Set-iCoreAdminAzureAdProvider -SiteName "My iCore Site" `
                              -TenantId "912a9f3b-7938-4aFD-9c17-318ebc612398" `
                              -ClientId "22a8cb8c-3a79-432a-b7fc-0b89730cd544" `
                              -Scopes "User.Read" "GroupMember.Read.All"

Using cmdlets to edit entities

Some entities are "crudable" (CRUD = Create, Read, Update, and Delete) using Cmdlets. For example, it is possible to add or remove Users or add a new Application pool to a Server.

note

Even if an entity is crudable, it does not necessarily mean that all its properties can be configured. For example, attempting to modify a Category on a Setting will generate an error. Also, the command New-iCoreSubEntity is not applicable to all subentities since a limited amount of IEnumerables are currently supported. For more information, use the Get-Help command. 

Listing crudable entities

    Get-iCoreEntityType -Crudable

Creating a new User

The example below shows how to create a new user ("John"), and add it to a User group called Developer.

$SystemId = 998
$SystemUserName = 'SethAdmin'
$SystemPassword = 'MyPassword123'

$NewUserName = 'PeterGriffin'
$NewUserPassword = 'AnotherPassword123'

$newUser = New-iCoreEntity -SystemID $SystemId -Username $SystemUserName -Password $SystemPassword -Type User  
$newUser.Name = $NewUserName  
$newUser.Password = $NewUserPassword
Save-iCoreEntity -Entity $newUser  

Add-iCoreUserToUserGroup -SystemID $SystemId -Username $SystemUserName -Password $SystemPassword -Name $newUser.Name -GroupNames "Developer"

Once the new user has been saved to the database, you can use the Get-iCoreEntity command to view its properties:

    Get-iCoreEntity -id $SystemId -Username $SystemUserName -Password $SystemPassword -Type User | Where-Object { $_.Name -eq "PeterGriffin"}

Which, in the example, results in:

Group                    : iCore.Public.Entities.Implementation.UserGroup  
Name                     : PeterGriffin  
Description              :  
Password                 :  
CreatedDate              : 2021-03-27 14:58:13  
ModifiedDate             : 2021-03-27 14:58:13  
Id                       : 3a9f71c1-fece-410b-a34e-0b48724eebb0  
Key                      : User \[153\]  
SystemInternal           : False  
RestrictedOperations     : None  
IsDisabled               : False  
PasswordNeverExpires     : False  
IsPasswordChangeRequired : False  
AuthenticationType       : iCoreSystem

Alternatively, you can create a User that authenticates via an third-party OpenID Connect provider:

    $SystemId = 998
    $SystemUserName = 'SethAdmin'
    $SystemPassword = 'MyPassword123'

    $newUser = New-iCoreEntity -SystemID $SystemId -Username $SystemUserName -Password $SystemPassword -Type User
    $newUser.Name = 'john.doe@company.com'
    $newUser.AuthenticationType = [iCore.Public.Entities.UserAuthenticationType]::OpenIDConnect    
    Save-iCoreEntity -Entity $newUser
    Add-iCoreUserToUserGroup -SystemID $SystemId -Username $SystemUserName -Password $SystemPassword -Name $newUser.Name -GroupNames "Developer"

note

When adding a User that authenticates with Open ID Connect, the following applies:

• The Password property should not be set.
• The AuthenticationType property should be set to OpenIDConnect.
• The Name property should be set to a value that matches the username claim value of the user from the OP (Open ID Connect Provider) that the iCore User is to be connected to. For more information, see Authentication provider configuration.

Adding a User to a User group

The example below shows how to add the User created in the previous example to a User group:

Add-iCoreUserToUserGroup -ID 10 -Username BobTheAdmin -Password 123abcde -Name $newUser.Name -GroupNames "Developer"  

Alternatively, you can use the previously created User as a parameter:

    Add-iCoreUserToUserGroup -User $newUser -GroupNames "Developer" 

Adding a User to multiple User groups

The example below shows how to add the User created in the previous example to multiple User groups:

    Add-iCoreUserToUserGroup -ID 10 -Username BobTheAdmin -Password 123abcde -Name $newUser.Name -GroupNames "Developer", "User" 

Alternatively, you can use the previously created User as a parameter:

 Add-iCoreUserToUserGroup -User $newUser -GroupNames "Developer", "User"  

Removing a User

To remove the User created in previous example:

    Remove-iCoreEntity (Get-iCoreEntity -ID 10 -Username BobTheAdmin -Password 123abcde -Type User | Where-Object { $_.Name -eq "John"} )

Removing a User from a User group

The example below shows how to remove the User created in the previous example from a User group:

    Remove-iCoreUserFromUserGroup -ID 10 -Username BobTheAdmin -Password 123abcde -Name $newUser.Name -GroupNames "Developer" 

Alternatively, you can use the previously created User as a parameter:

    Remove-iCoreUserFromUserGroup -User $newUser -GroupNames "Developer"

Removing a User from multiple User groups

The example below shows how to remove the User created in the previous example from multiple User groups:

Remove-iCoreUserFromUserGroup -ID 10 -Username BobTheAdmin -Password 123abcde -Name $newUser.Name -GroupNames "Developer", "User"  

Alternatively, you can use the previously created User as parameter:

    Remove-iCoreUserFromUserGroup -User $newUser -GroupNames "Developer", "User" 

Adding an Application pool to a Server

The example shows how to add an Application pool implementation.

    Get-iCoreEntity -ID 10 -Username BobTheAdmin -Password 123abcde -Type server
    $server = Get-iCoreEntity -ID 10 -Username BobTheAdmin -Password 123abcde -Type server | where-object { $_.Name -eq "Server 1" }
    $newAppPollImpl = New-iCoreSubEntity -EntityCollection $server.ApplicationPoolImplementations
    $newAppPollImpl.ApplicationPool = Get-iCoreEntity -ID 10 -Username BobTheAdmin -Password 123abcde -Type ApplicationPool | where-object { $_.Name -eq "Primary Session AppPool" }

note

A subentity (in this case, the Application pool) is saved by saving its "parent" (the Server). In other words, the Server instance holds the Application pool instances.

Adding a Setting

The following example shows how to add a new Setting via variables.

    $newUnsavedSetting = New-iCoreEntity -ID 10 -Username BobTheAdmin -Password 123abcde -Type Setting
    $newUnsavedSetting.Name = "EmergencyErrorSetting"
    $identityCollection = $newUnsavedSetting.Identities
    $identityCollection.Add("EmergencyError")
    $newAttributeGroup = New-iCoreSubEntity $newUnsavedSetting.Groups
    $newAttributeGroup.AttributeGroupType = Get-iCoreEntity -ID 10 -Username BobTheAdmin -Password 123abcde SettingAttributeGroupType | where {$_.Name -eq "ContactData"}

The properties of the AttributeGroup object ("pre-save"):

Collection         : {ContactData}  
Attributes         : {}  
AttributeGroupType :
iCore.Public.Entities.Implementation.SettingAttributeGroupType  
Id                 : 0528babb-5c2d-4181-bd97-9c4d006c5439  
Name               : ContactData  
Key                : Setting attribute group
\[0528babb-5c2d-4181-bd97-9c4d006c5439\]  
SystemInternal     : False

Now, to populate the attributes of the new AttributeGroup (based on the GroupType set), the Setting must be saved:

    $savedSetting = Save-iCoreEntity $newUnsavedSetting

Once the Setting has been saved, the variables $newUnsavedSetting and $savedSetting point to the same object and the properties of AttributeGroup will be:

<span class="Monospaced">Collection         :
{ContactData}</span><span class="Monospaced">  
Attributes         : {FullName,
PhoneNumber}</span><span class="Monospaced">  
AttributeGroupType :
iCore.Public.Entities.Implementation.SettingAttributeGroupType</span><span class="Monospaced">  
Id                 :
0528babb-5c2d-4181-bd97-9c4d006c5439</span><span class="Monospaced">  
Name               : ContactData</span><span class="Monospaced">  
Key                : Setting attribute group
\[0528babb-5c2d-4181-bd97-9c4d006c5439\]</span>  
<span class="Monospaced">SystemInternal     : False</span>

To modify default attribute value "FullName":

    $attribute = $newAttributeGroup.Attributes | Where-Object {$_.Name -eq "FullName"} | Select-Object -first 1
    $attribute.Value = "John Smith"

To save the new attribute value, the Setting must be saved again:

    $savedSetting = Save-iCoreEntity $savedSetting

Removing a Setting

    $settingToRemove = Get-iCoreEntity -ID 10 -Username BobTheAdmin -Password 123abcde Setting | where {$_.Name -eq "EmergencyErrorSetting"}
    Remove-iCoreEntity $settingToRemove

Adding a Partner

Adding a Partner is very similar to adding a Setting, as shown in this example:

    $newUnsavedPartner = New-iCoreEntity -ID 10 -Username BobTheAdmin -Password 123abcde -Type Partner
    $newUnsavedPartner.Name = "Company_1"
    $identityCollection = $newUnsavedPartner.Identities
    $identityCollection.Add("C1")
    $newAttributeGroup = New-iCoreSubEntity $newUnsavedSetting.Groups
    $newAttributeGroup.AttributeGroupType = Get-iCoreEntity -ID 10 -Username BobTheAdmin -Password 123abcde PartnerAttributeGroupType | where {$_.Name -eq "ContactData"}
    $savedPartner = Save-iCoreEntity $newUnsavedPartner

Removing a Partner

    $partnerToRemove = Get-iCoreEntity -ID 10 -Username BobTheAdmin -Password 123abcde Partner | where {$_.Name -eq "Company_1"}
    Remove-iCoreEntity $partnerToRemove

See Also

PowerShell

iCore PowerShell cmdlets
iCore PowerShell Console

Entities

User
Server
Application pool

Security

User authentication
User authorization with Azure AD

Administrator installation

Configuring an OpenID Connect provider