The Identity service is used for three main purposes:

1. Authenticating users that connect using Canary’s client tools
2. Authorizing other Canary services
3. Managing API Tokens

Authenticating Users

The Identity service operates as an OAuth 2.0/OpenID Connect (OIDC) server for Canary’s client tools: the Canary Admin, Axiom, and the Excel Add-in. Upon connecting, a browser window will appear prompting the user to log in via https.

By default, the Identity service is configured to utilize Windows AD as this was the primary method for authenticating prior to v24. However, with the integration of OIDC, the Identity service now supports several other identity providers (IDP) in addition to Windows AD such as:

• Azure/Entra ID
• Microsoft AD Federation
• Okta/Auth0
• Google
• Kerberos
• Customer-defined OAuth Providers
• An Anonymous option is also available

When a user connects, a “Canary user” is automatically generated on their behalf which is mapped to the external user from the IDP. Additionally, the Identity service is made aware of any external group the user is a member of. Therein, a “Canary group” can be created and linked to an external group from the IDP as needed. The Identity service is responsible for managing these internal Canary users/groups.

Consider the following example where the external user, ebyers, signs into Canary using one of the client tools (Canary Admin, Axiom, or Excel Add-In).

1. A Canary user, Edward Byers, is generated based upon the external username and mapped to the external ID.
2. The Identity service discovers all of the domain groups which Edward is a member of.
3. Afterwards, the Canary group, Canary Admins, is manually created.
4. The external group, OT_ADMINS, is then linked to the Canary group, Canary Admins.

Authorizing Other Canary Services

The Identity service contains all of the access control lists (ACLs) for each Canary service that requires authorization.

• Administrator
• Axiom
• Historian
• Identity
• Store and Forward (SaF)
• Views

Canary services query the Identity service to ask about user membership in an ACL. These ACLs use only the internal “Canary” users/groups that are linked to the external users/groups that come from the IDP. Users are allowed/denied access as needed.

Both flat and hierarchical ACLs are supported depending on the service. Hierarchical ACLs would be used when applying Tag Security with read/write access (the Views service handled this prior to v24).

Using the example from above, the Canary user (Edward Byers) and Canary group (Canary Admins) can now be used within the ACLs. Canary Admins is granted access to the Axiom>Logon ACL and Edward Byers is granted scripting capabilities on the Axiom>Script ACL.

Managing API Tokens

API tokens are used for secure authorization without the need for user credentials. They must be linked to a “Canary” user which can then be added to an ACL. Tokens can be long-lived, set to expire at a certain time, or revoked manually. Tokens are used when:

• Reading data out of the Historian using the Views (Read) API
• Writing data to the Historian using the SaF (Write) API
• Logging data from a remote Collector/SaF server when Tag Security has been enabled within the Identity service
• Adding a remote Historian view to a Views service through a secure connection
• Connecting securely with the ODBC client
• Running Automated Reports from a remote Identity service
• Upgrading a Remote Axiom/Views server from v23

Consider the following example where an API token is created for the specific purpose of reading data via the Views API.

1. A Canary user, Read API Client, is created that is NOT linked to any external user. It is for internal purposes only. (An API token could be linked to an existing Canary user that is mapped to actual external user, but in this example it is not.)

   

2. An API token is then created and linked to the Canary user, Read API Client. The token is given an intuitive description and set to Never expire.

   

3. The Canary user is given Read permissions at the root level of Views within the Tag Security ACL.