Identity Tile (version 24)

• Total Users – total number of “Canary” users created within the Identity service
• Active Users – total number of Canary users who are currently logged in to a Canary application (Canary Admin, Axiom, or Excel Add-In)
• Identity Providers – total number of providers enabled/configured (Windows AD, Anonymous, Azure, etc.)
• Applications – total number of client applications configured. Default is three (Canary Admin, Axiom, and Excel Add-In).
• Version – version number of the Identity service

The Identity service is responsible for managing the users/groups that connect to the Canary system. By supporting several identity providers (IDP), the Identity service authenticates those users whenever they log in using a Canary application (Canary Admin, Axiom, or Excel Add-In). Additionally, the Identity service contains all the access control lists (ACLs) that other Canary services utilize when needing to authorize a particular user. API tokens are also generated here for use in other Canary services.

Configuration Screen

Providers

The main purpose of the Providers screen is to add or enable the identity provider (IDP) for which all other users will use to authenticate and connect. By default, the Identity service uses Windows AD but supports several others using OAuth 2.0/OpenID Connect. (See How to Add an OpenID Connect Provider.)

APPLICATIONS

There are three client applications that require authentication upon connecting:

1. Canary Admin
2. Axiom
3. Excel Add-In

Clients connecting via API or ODBC will use an API token. See How to Create an API Token.

Upon connecting with one of these applications, the user will be presented with a login screen where they will choose how to authenticate based upon the IDPs configured.

In the screenshot above, the user is given the choice between Windows AD and Anonymous when they log in to Axiom as both are enabled within the Identity service.

• ADD - creates a new client application. Realistically, this would only be needed in an architecture where two Axiom services (a Prod and Dev environment perhaps) are pointed to the same Identity service (which is to be expected as only one Identity service is needed per network). In that case, each Axiom client would have its own unique Client ID and Redirect URI. (There is no scenario where multiple Canary Admin or Excel Add-In clients are needed.)

  

  Axiom clients use a Web application type, whereas the Canary Admin and Excel Add-In use the Native application type.
• EDIT - modifies the selected client application. Users can edit a client application if wishing to change the Display Name or Redirect URI (Axiom only) but should avoid changing the Client ID unless there are multiple Axiom clients which need to be unique.
• REMOVE - removes the selected client application

• CLIENT ID – the ID the client uses when connecting to the Identity service. Client ID’s must be unique.
• DISPLAY NAME – the name that is presented to the user when connecting with the client application
• REDIRECT URIS – the URI the user is redirected to upon connecting. The Canary Admin and Excel Add-In use the loopback IP address of 127.0.0.1 as the client is local to their machine and should not need changed. Axiom, on the other hand, is web-based. If wishing to use a different URI for users to connect to, it can be included along with the default https://localhost and https://[serverName] by editing the Axiom client application. (*Note, it is expected that the new URI is a legitimate domain which users can access.)

OPENID CONNECT PROVIDERS

Displays any external OpenID Connect Providers that have been added along with its properties. By default, Canary uses Windows AD so no providers will be listed here until one has been configured. (See How to Configure an OpenID Connect Provider for more information.)

• AUTHENTICATE – authenticates with an OIDC provider to get claims once the provider has been added
• ADD – adds a new OIDC provider
• EDIT – modifies the selected OIDC provider
• REMOVE – removes the selected OIDC provider

Selecting the ADD or EDIT button will open the following window for the user to configure the OIDC provider.

• PROVIDER DISPLAY NAME – name of the external IDP. This does not have to match anything coming from the IDP but should be intuitive so that it is obvious who the IDP is.
• PROVIDER URL – endpoint of the external IDP used for OIDC authentication
• CLIENT ID – unique identifier of the external identity application
• CLIENT SECRET – secret of the external identity application
• USER ID CLAIM – name of the user id claim used by the external IDP
• USER NAME CLAIM – name of the user name claim used by the external IDP
• GROUP ID CLAIM – name of the group id claim used by the external IDP

EXTERNAL PROVIDER OPTIONS

• Enable Anonymous – (Disabled by default) allows users to log in anonymously without providing credentials
• Enable Kerberos – (Disabled by default) passes in the user’s current credentials they used to sign in to their machine
• Enable Active Directory – (Enabled by default) allows the user to authenticate using their Windows credentials

Endpoints

• IPC - endpoint used by other Canary services that are local to the Identity service to handle user authorization
• gRPC Admin (55354) - endpoint used specifically by the local Admin service for configuring settings and requesting status information
• gRPC API (55351) - similar to the IPC endpoint, this endpoint is used by other Canary services that are remote from the Identity service to handle user authorization
• REST API (55353) - the Identity service's OpenID Connect endpoint. All authentication goes through this endpoint regardless of whether the user is authenticating with an external OpenID Connect provider or not.

CERTIFICATE (HTTPS)

By default, Canary generates a self-signed certificate for its services that require a secure connection. These can be reconfigured if wishing to use a different certificate that has been installed on the server. Clicking the INFO button will open a new window displaying the certificate's details.

• Kind - the kind of certificate the Identity service is configured to use
  • SelfSignedCertificate - this is the default certificate that Canary uses. It is stored in the Local Computer\Personal store.
  • Certificate - use this option if wishing to upload your own certificate. Doing so will present more options to configure.

    

    • Store Name - the local computer store name where the certificate is installed
    • Find Type - criteria by which the Identity service searches for the certificate
      • FindBySubjectName
      • FindByThumbprint
      • FindByTemplateName
• Subject Name - set to default if using the SelfSignedCertificate option. Otherwise, the value of the Subject, Thumbprint, or Template name if using the Certificate setting.

Settings

SERVICE SETTINGS

• Security Key - used for encrypting and signing tokens the Identity service creates. There is no reason to change this key; however, in the event you want to install a redundant Identity service, this key can be copied to the other Identity service as both will need to use the same key.

DATABASE SETTINGS

• Provider -
  • SQLite - by default, the Identity service stores its information regarding users/groups/ACLs/API Tokens in a SQLite database (C:\ProgramData\Canary\Identity\identity.sqlite).
  • MSSQL - select this option if wishing to install a redundant Identity service. In this case, both Identity services must use the same security key and be pointed to the same MSSQL database.

    

    • Server - name of the server where the MSSQL database is located
    • Name - name of the database where the Identity service will store its information
    • User/Password - credentials of the user that has read/write access to the database

Security Screen

Access Control Lists

The Access Control Lists screen is used to allow/deny access to specific functions for users/groups. The ACLs only contain internal "Canary" users/groups which are mapped to an external user/group coming from an IDP or an API token. A user will first appear on an ACL in a Request state if they did not have prior access, wherein they can be allowed or denied.

• ADD - allows a Canary user/group to be added to the ACL
• EDIT - allows the access state of the Canary user/group to be changed to Allow/Deny
• REMOVE - removes the Canary user/group from the ACL

Users

The Users screen is used to configure internal "Canary" users and map them to an external username or an API token. When a user initially logs in with a Canary client application (Canary Admin, Axiom, or Excel Add-In) an internal Canary user is generated on their behalf and linked to their external username. The Anonymous user is also available if the Anonymous provider is enabled from the Configuration>Providers screen.

Canary Users

• ADD - adds a new Canary user
• EDIT - modifies the selected Canary user if wishing to change the user name. If the original user name is already on an ACL, it will be automatically updated to match the new user name.
• REMOVE - removes the selected Canary user. Removing a user from this list will, in turn, remove the corresponding external user it is mapped to from the External Users list. Similarly, the user will be removed from any ACL they were a part of.

• CANARY USER ID - unique identifier of the Canary user
• USER NAME - friendly name of the Canary user. If two external users would have the same name, the Canary name would be incremented by 1 for the 2nd user.

External Users

• EDIT - modifies the selected external user if wishing to map it to a different Canary user
• REMOVE - removes the selected external user. Doing so does NOT remove the corresponding Canary user it is mapped to from the Canary Users list.

• PROVIDER ID - identity provider (IDP) of the external user
• EXTERNAL ID - unique identifier of the external user as provided by the IDP
• CANARY USER ID - unique Canary identifier the external user is mapped to
• USER NAME - friendly Canary name the external user is mapped to

Groups

The Groups screen is used to create "Canary" groups and map them to an external group coming from the IDP. When a user logs in to Canary, the Identity service discovers ALL of the external groups that user is a member of. Canary groups can be created as needed and linked to one or more of these external groups. Multiple external groups can be linked to a single Canary group. By default, Canary uses the Everyone group which includes ALL Canary users as well as the domain Administrators group.

Canary Groups

• ADD GROUP - add a new Canary group
• EDIT GROUP - modifies the selected Canary group if wishing to change its name. Group names will also be updated with this change if they already exist in an ACL.
• REMOVE GROUP(S) - removes the selected Canary group(s)
• ADD USER - adds a Canary user to the group. This may be needed if wishing to add a user who is not a member of the external group the Canary group is mapped to.
• REMOVE USER - removes a user from the Canary group

• CANARY GROUP ID -  unique identifier of the Canary group
• GROUP NAME - name of the Canary group
• USERS - list of Canary users associated with the Canary group. These users are in addition to who is in the external group (if an external group is mapped to the Canary group).

External Groups

• EDIT GROUP - modifies the selected external group if wishing to map it to a new or different Canary group
• REMOVE GROUP(S) - removes the selected external group(s). Groups will be rediscovered if a user who is a member of them signs into Canary again.

• PROVIDER ID - provider of the external group
• EXTERNAL NAME - name of the external group, if available from the IDP
• EXTERNAL ID - unique identifier of the external group as provided by the IDP
• CANARY GROUP ID - unique identifier of the mapped Canary group
• CANARY GROUP -  name of the mapped Canary group
• USERS - list of external users associated with the external group who have logged in using one of Canary's client applications

API Tokens

The API Tokens screen is used to create/modify API tokens and map them to existing Canary users which can be placed on an ACL for authorization purposes. Tokens can be long-lived, set to expire automatically, or manually revoked at any time.

• ADD - used to add an API token

  

  API Token Description - description of what the token is used for
  User Name - Canary user the token will be mapped to
  Token State - set to Allow or Deny
  Expiration Policy - set to Never or specify a Date
   
• EDIT - used to modify the selected API token
• REMOVE - removes the selected API token
• INFO - displays who created the token and its description
   

API tokens are used for the following purposes within the Canary system:

Views (Read) API

These tokens are equivalent to those configured in Views>Configuration>Tokens in pre-24 versions. The API token must be specified using the 'apiToken' parameter when making a call to the Read API. Preexisting tokens will be migrated when upgrading to version 24 and appear on this list. (See https://readapi.canarylabs.com for more Read API documentation.)

The Canary user must be given Read permissions to the appropriate node/level within Identity>Security>Tag Security if Tag Security is enabled.

SaF (Write) API

Similar to the Read API, the user must specify the API token using the 'apiToken' parameter when making a call to the Write API. (See https://writeapi.canarylabs.com for more Write API documentation.)

If Tag Security is enabled, the Canary user mapped to the API token must be given Write permissions to the appropriate node/level within Identity>Security>Tag Security.

SaF to a Remote Historian where Tag Security is Enabled

If a Collector server using the new SaF (Store and Forward) service is logging data to a remote Historian where Tag Security is enabled, the SaF service will need to use an API token. The user must update the Store and Forward>Configuration>Settings>Identity Application Token on the Collector server to use this token.

Also, the Canary user mapped to the API token must be given Write permissions to the appropriate node/level within Identity>Security>Tag Security.

Adding a Remote Historian to Views

If needing to add a remote Historian view to the Views service, the Views service must be configured to use an API token through the Views>Configuration>Settings screen.

Also, the Canary user mapped to the API token must be given access on the Historian Access ACL.

Authenticating with the ODBC Client

To make a secure connection with the ODBC client, set the username to 'apitoken' and the password to the token itself.

The Canary user mapped to the API token must be given access on the Views Access ACL if the Everyone group is not already listed.

Likewise, the Canary user must also be given Read access to the appropriate node/level within Identity>Security>Tag Security if security is enabled.

Authenticating with the Excel Add-in (optional)

By default, a user is prompted to authenticate through a browser window each time they open the Excel Add-in to use one of its functions. This workflow may become cumbersome. If they would like to bypass this authentication process, the Add-in can be configured to use a token instead by selecting the Settings gear icon from the ribbon.

When a token is applied, the user will no longer be prompted to authenticate by the browser window.

 The Canary user mapped to the API token must be given access on the Views Access ACL if the Everyone group is not already listed.

Likewise, the Canary user must also be given Read access to the appropriate node/level within Identity>Security>Tag Security if security is enabled.

Running Automated Reports from a Remote Axiom Service

If Axiom is installed remotely from the Identity service, it must be configured to use an API token to run Automated Reports. By default, Canary generates a token and Canary user (Axiom Report Service Account) for this specific purpose.

The token must be placed in the Axiom tile>Configuration>Settings>Identity API Token field where the Axiom service is installed.

Upgrading a Remote Axiom/Views Server from v23

When upgrading the Canary system from v23, it is expected that the server containing the Identity service is upgraded first as other Canary services require the Identity service. In most cases, the Identity service will reside alongside the Historian. Once the Identity service is in place, other remote Canary servers can be upgraded. In the event that Axiom or Views are remote from the Identity service, an API token is required when updating the software to v24. By default, Canary generates a token and Canary user (Installer Migration Service Account) for this specific purpose.

The token is used on the Product Migration screen of the install.

Tag Security

The Tag Security screen is used to set permissions at any level within the BROWSE panel to limit or grant read/write access to Canary users/groups when security is enabled. Each view can be expanded if wishing to set permissions at a lower level, all the way down to the tags themselves.

VIEWS ENDPOINT

The Identity service can connect to multiple Views services individually to set permissions for each one. This is necessary in an architecture that requires multiple Views services in a single network. Only one Identity service is needed for one network; therefore, it must be able to connect to all of them.

• Host - address of the Views service to configure tag security on
• Port - port of the Views service the Identity service connects to. If Views is remote from the Identity service, use 55321 to connect to the gRPC API endpoint.

  

CONFIGURATION

• Enable Tag Security - check the box to enable Tag Security. Doing so will apply the permissions that are configured within the BROWSE panel. Ensure permissions are properly set before enabling as this could prevent users from accessing data.

BROWSE

The BROWSE panel contains a hierarchical view of the entire tag structure available to the end user, including both local/remote Historian views and any virtual views that may be created. Each view can be expanded to show lower subnodes within the model. Permissions can be applied at any level throughout the structure to restrict what the end user is able to see.

EXPLICIT PERMISSIONS

The EXPLICIT PERMISSIONS panel displays the access a Canary user/group has at that particular node/level selected in the BROWSE panel.

• ADD - used to set permissions for a given Canary user/group for the selected node
• EDIT - modifies the permissions for the selected Canary user/group
• REMOVE - removes the selected Canary user/group
• COPY - copies the selected Canary user/group and its access to the clipboard
• PASTE - pastes the copied Canary user/group and its access from the clipboard

Canary users/groups can be rearranged within the panel by a click-and-drag. Order matters. If a user is explicitly added and is also a member of an explicit group that is already on the list, then the user should be listed above the group. If not, the message "Unreachable Permission Detected!" will display. Similarly, if a user is a part of two groups, the first group to appear in the list will take precedence over the second.

INHERITED PERMISSIONS

The INHERITED PERMISSIONS panel displays the access level for any Canary users/groups that have been passed along from a parent node/level. Explicit permissions will always override any inherited permissions for a user/group.

EFFECTIVE PERMISSION

Using the drop-down box, select a Canary user from the list to see what access they have at that particular node/level.