1. Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2
1.1 User Sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.1.1 Managing Users and Roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
1.1.2 Internal Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
1.1.3 Database Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
1.1.4 Active Directory Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
1.1.5 AD Internal Hybrid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
1.1.6 AD Database Hybrid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
1.1.7 Fallback Cache Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
1.1.8 Verifying a User Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
1.2 Identity Providers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
1.2.1 Configuring Identity Providers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
1.2.2 User Attribute Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
1.2.3 Security Level Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
1.2.4 User Grants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
1.2.5 Test Login and Logout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
1.3 Security Levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
1.4 Security Zones . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
1.5 User Schedules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
1.6 Project Security in Designer and Gateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
1.7 Using SSL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
1.8 Audit Profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
1.8.1 Alarm Notification Auditing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
1.8.2 Audit Log Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
1.9 Common Security Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
1.9.1 OpenID Connect 1.0 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
1.9.2 SAML Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
1.9.3 Troubleshooting Identity Providers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
Security
Security options in Ignition provide many ways to safeguard your data and applications. You control
not only who accesses your systems, but when and where they can access them. You can add as
many user sources as you need. For users, you can store detailed information beyond just a user
name and password, such as schedules, roles, phone numbers, and more. At the core of Ignition's On this page
security are users and the roles of users.

At its simplest, setting up security in Ignition follows this pattern: ...

1. Have a user source for logging in (one or more users). Security Setup
2. Set up roles that define the types of access users may need (for example, Administrator, User Sources
Supervisor, Operator, or Guest). Roles and
3. Establish security on Ignition Projects, the Gateway, the Designer, Vision components, Security Levels
Perspective Views, and so forth. Project and
4. Assign roles to the individual users. Component
Security
The diagram below illustrates how Perspective and Vision access user sources and shows some of Gateway
the differences between Federated IdPs, external AD authorization, and internal Ignition Security
authorization. A few notable points: Security with User
Sources
Vision clients only use User Sources. Roles in Vision clients are automatically pushed into
Security with Identity
the Designer.
Providers
The Perspective module gets users and roles from an IdP. Roles must be then set up in S
ecurity Levels in order to be available to the security screens in the Designer.
Perspective sessions can be made available to all users (Security Level - Public) or set to
require user authentication.

Security Setup
Security in Ignition falls into a few categories, and the bulk of the setup happens in the Gateway Webpage. Under Security in the Config
section of the Gateway Webpage, you'll find pages for authentication, role mappings, zones, and more.
User Sources
User Sources can be created and stored in Ignition, they can access user info from an external database, or from an Active Directory
(AD) profile.
In Ignition 8.0 with the Perspective module, users can also come from Ignition's internal Identity Providers (IdP) or an external IdP
using trusted federated identity technologies such as OpenID Connect or Security Assertion Markup Language (SAML).

Roles and Security Levels

Roles are created and then assigned to users. Roles can be stored in Ignition or roles can be linked to AD Groups.
In Ignition 8.0 with the Perspective module, Security Levels are established to connect users with roles. Security Levels are assigned
to users through Security Level Rules or User Grants.

Project and Component Security

All Projects have security settings indicating what roles can publish, view, save, delete, or access Project resources.
In the Vision module, you can set security for managing alarms, editing Tags and a host of other functions. You can also set security
 on Vision components and windows .
In Ignition 8.0 with the Perspective module, you can set security on projects and views. You can also set permissions in event
Actions.

Gateway Security
The primary purpose of Gateway security is to protect access to the two most critical areas of Ignition: the Designer and the
Gateway. Many important resources are configured in these areas, so access to each Gateway section (Status and Config), as well
as the Designer, can be limited by role.
Through the Gateway security settings you can also choose to use Secure Sockets Layer (SSL), a widely adapted encryption
protocol used all over the world.
Through the Gateway you can also set up Audit Profiles, which cause Ignition to record details about specific events that occurred.
For more information, see Project Auditing and Alarm Notification Auditing.

Security with User Sources

Role-based security works under the concept that each user may be assigned to various roles. Security policies are then defined in terms of
these roles, rather than defined for specific users. An example of roles could be an Administrator role that has access to the Designer and the
client or session or an Operator roles that have access only to windows or views that pertain to their jobs. Roles allow users to be reassigned,
removed, and added without affecting the logic of the security policy.

The users and their roles are stored in User Sources. An Ignition Gateway may have many different User Sources defined, each governing
the security of different aspects of the Gateway. For example, logging into the Gateway might be governed by one User Source, while
the security in a project is governed by another. The example below shows the Users and Roles screen after user "Arthur" has been updated.

There are several types of User Sources that offer various features. For example, the Internal User Source offers the ultimate in ease-of-use:
you simply define the users, their passwords, and the roles within the Ignition Gateway configuration web interface. In contrast, the Active-Dir
ectory User Source offers the power of integrating Ignition with a corporate security infrastructure. Users, passwords, and roles would be
managed centrally by the IT department.

Security with Identity Providers

Identity Providers and Security Levels are currently only available for use with the Perspective module.

Identity Providers ( IdP) offer user authentication as a service. An IdP creates, maintains, and manages identity information for principals
while providing authentication services to relying party applications within a federation or distributed network. Authentication of the user is
handled by the IdP. Ignition can connect to these three different types of IdPs:

Ignition's internal IdP

OpenID Connect 1.0
Security Assertion Markup Language (SAML)

IdPs are set up at the Gateway level. Security Levels are also set through the Gateway. The Security Levels enable you to define a hierarchy
of access inside a Perspective Session.

In This Section ...

User Sources

User Sources
User sources (previously known as Authentication Profiles), are a collection of users, roles, and
other user data, such as contact information or schedule. When a new user or role is created, it is
applied and stored in the user source. Projects and the Gateway are assigned a User Source to
authenticate against. This determines which users have access to which project(s). On this page
There are several types of user sources: single-storage types with varying storage mediums,
"hybrids" that combine features of the previous three types, and a cache type used in Local Client ...
Fallback systems.
User Sources
Single-Storage
If you have Ignition 8.0 with the Perspective module, authentication is handled instead by Hybrid
Identity Providers. Fallback Cache
Shared Functionality
Main Properties
The Default User
Single-Storage Source
Which User Source
Users and roles are stored in a single location. The single-storage users sources are: Controls What?

Internal Authentication - Users and roles are stored internally to Ignition.

Database Authentication - Users and roles are stored in a SQL database. Managing users
is done via direct interaction with the database.
Active Directory Authentication - Users and roles are managed by Active Directory. Users
are authenticated through the LDAP protocol.

Hybrid

Users in hybrid user sources authenticate against Active Directory, meaning that user names and passwords are checked against those
stored in Active Directory. However, roles are stored either internally in Ignition or in a SQL database, so it is possible to make a role change
without have to contact your Active Directory administrator. This way, Active Directory can be consulted to see if a user is valid, but the
management of roles does not require coordination with the IT department, who typically control the Active Directory system. This "best of
both worlds" approach is popular for many users of Active Directory.

Active Directory-Internal Hybrid - Users managed by Active Directory and roles stored to Ignition internally.
Active Directory-Database Hybrid - Users managed by Active Directory and roles stored in an SQL database.

Fallback Cache

This User Source was developed specifically for a system that is using Local Client Fallback, and allows you to cache the login credentials
from a remote user source. This means your users can still log in with their normal username/password on a Local Client Fallback project,
even when the network connection is unavailable.

More information can be found on the Fallback Cache Authentication page.

Shared Functionality
Regardless of type, all User Sources have the following functionality:

Failover Source: If the User Source is unavailable for authentication, then a backup User Source can be specified. The type of the
fail-over User Source can differ from the primary, so configurations where an internal-type fails over to a database-type are possible.
Schedule Restrictions: The User Source can prevent users from logging in when they are off schedule, meaning that the schedule
assigned to the user determines when the user may login.

Main Properties
All User Sources have a section of properties that are categorized as "Main". Below is a description of these properties.

Name Description

Name The name of the User Source. This is how other systems in Ignition reference the user source. Note that every User
Source must have a unique name.

Description An optional description of the user source. Useful for noting which database connection or AD server the User Source may
be referencing.

Schedule Forces schedule restrictions on users. Specifically, if a user attempts to log into a client while they are off schedule, the
Restricted login will fail. Utilizes User Schedules.
 Failover Allows authentication attempts against this User Source to failover to another User Source in the event of a network
Source outage, or some other connection issue. Useful with database or Active Directory user sources, as connection failures to
the database/AD server will prevent users from logging in.

This property is initially set to None, meaning a failover User Source is not configured.

Failover When a Failover Source is configured, this property determines when the failover User Source should be consulted. The
Mode following options are available:

Hard: The Failover User Source is only consulted when this User Source is unreachable.

Soft: The Failover User Source will be consulted if the user's credentials fail authentication, meaning that the user typed in
credentials that are unrecognized or incorrect.

Cache The amount of time between cache updates of the User Source.
Validation
Timeout

The Default User Source

When Ignition is installed for the first time, an internal User Source named 'default' is created. You can manage the default User Source by
navigating to the Config > Security > Users, Roles section of the Gateway. The manage users link next to the 'default' user source allows
you to add new users, modify roles and passwords for existing users, remove users, and add/remove roles from the user source. Choosing to
edit a user will bring you to the following page allowing you to make any necessary changes to that user.

When you open the 'default' user source for the first time, you will see the first user that was created at installation. This is the administrator
account that has full privileges.
 Which User Source Controls What?
With potentially multiple User Sources defined, you need to understand which User Sources are controlling which aspects of Ignition. To
determine what kind of User Source is governing what, do the following:

1. To manage users and passwords for logging into the Gateway Configuration section, you'll need to see what User Source is currently
set as the Gateway's User Source. You can check this under Config > System > Gateway Settings by looking at the System User
Source field and the Gateway Config Role(s) field.
2. To manage users and passwords for logging into the Designer, you follow the same steps as in #1, except that you need to look at
the Designer Role(s) field to see what roles are allowed to log into the Designer.
3. To manage users and passwords for logging into a Vision Client or Perspective Session, go to the Config > System > Projects secti
on. Look at the project in question and you can find its User Source listed under Authentication, or click edit and look at Authentica
tion Profile.
4. Now that you know what User Source you need to manage, you can find out what kind it is under in the Security > Users, Roles sec
tion.

In This Section ...

Managing Users and Roles

Users and Roles
On this page
Security is based on the roles that are assigned to specific users. Roles do not have any structure
or hierarchy by default, but can be created. You can create a hierarchy based on users with a
greater role being assigned all matching lesser roles. ...
There isn't a built-in restriction to the number of roles a user can have, so each user can have Users and Roles
access to many roles, or none at all. Creating a Role
Assigning Roles
to Users
Role Hierarchy
Roles and Security Managing Users
It's important to think about the different roles in your project and how they affect the User Management
security of your project. For instance, what level of access a particular area of a project Component
needs may determine the functional type roles that you create, and the different users Using the User
assigned to each role. Management
Component in the
You can manage users and roles using either the Gateway interface, or using the User Designer and
Management component inside the Designer or Client. This section shows how to manage users Vision Client
and roles using the Gateway interface. Save Failed. You
are not
authorized...
When using role-based security in a project, the project stores the name of the role as a
string. This means that if you were to modify the name of the role in the Gateway, the
role-based security in your project will not update to reflect the new name, and instead
will try searching for a role with the original name. Be very careful when modifying the
names of roles.

Creating a Role

1. On the Gateway Webpage, go to the Config section, and choose Security > Users, Roles from the menu on the left.
The User Sources page is displayed.

2. Click on the manage users link for the User Source you want to manage.

3. Click the Roles tab. Look for the blue arrow at the bottom, and click the Add Role link.

4. Name the role by entering it in the Role Name field, and click on the Add Role button.
The role is now available to be associated with specific users.
Assigning Roles to Users

1. On the Gateway Webpage, go to the Config tab, and choose Security > Users, Roles from the menu on the left.
The User Sources page is displayed.

2. Click on the manage users link for the User Source you want to manage.

3. Click the Edit link for the User you want to edit, or click the blue Add User link to add a new user. (When adding a new user, you can
also add their roles at the same time).

4. If you're creating a new user, the Add User window will open. Enter the user's properties including the roles you want this user to
have. If no roles have been created, then follow the instructions in the Creating a Role section from above. If your user already exists
 4.

and you simply want to modify their roles, the Edit User window will open. (The Edit User window and the Add User window look
identical).

To assign a role, there is a Roles property with a list of roles that have already been created. Select the role(s) that you want this
user to have. (It's not required for a user to have a role, but be aware that they might not have access to an area of the project that
requires them to have a role).

Administrator Role
When a project is first created, the Administrator role is the only role available, and no other roles will appear until they
are created. When more roles are created, they appear as check boxes just like the Administrator option.

5. Click either Add User if you adding a new user, or Save Changes if you are modifying a user's role(s).
The user now has the privileges associated with the selected role(s).

Role Hierarchy

Often you might want to have one role that includes all the permissions for another role, i.e., Supervisor can do everything that Administration
and Maintenance roles can do. In the Designer, access to Components can be restricted to specific security roles. You can give any
Supervisor both of the Administration and Maintenance.

Managing Users

User Sources support managing the users and roles from within Ignition to varying degrees. Some User Sources are fully manageable,
meaning that you can administer the users, roles, contact info, and so on from within the Ignition Gateway, as well as inside a Vision Client.
Other User Sources do not support this at all, while yet others only partially support it. Make sure you understand how and where
the administration takes place before you choose a User Source type.

For User Sources that support it, you can manage the users and roles from within the Ignition Gateway's web configure interface under Confi
g > Security > Users, Roles. Click on the manage users link for the User Source you want to administer.

Often, it is desirable to let some management or administrative users of a Vision project manage other users without having to log into the
Gateway's Configure section. To do this for a User Source that supports being managed, you can simply use the built-in User Management
Panel that comes with the Vision Module.

User Management Component

Ignition has a special User Management component in the Vision Module that allows you to add, modify, and delete users and roles (and
more) inside the Designer and the Client. This is simple to set up and use.

Using the User Management Component in the Designer and Vision Client

1. In Designer, go to the Project Browser and then to Vision.

2. Create a new Window or open an existing one.
3. Drag a User Management component to your window. This component will automatically point to the default user source being used
by your project. You can change the User Source property if needed.
4. If you already have some users and roles setup using the Gateway Webpage, you will see them in the User Management
component. If you don't have any users or roles setup, you can create them here. Use the icons on the right side to add, edit, or
delete a user or role.
5. To add a new user, put the Designer in Preview Mode. Click the the plus

icon next next to the user section.

6. The Add User window will open. At a minimum, enter the Username and Password. All other properties are optional. When finished,
click Save.
7. To add a new role, make sure the Designer is in Preview Mode. Click the the plus

icon next to the role.

The Add Role window will open.
8. Enter the name of the new role. Click Save.
9. Now you can see the user and role that were just added in the User Management window.
 Save Failed. You are not authorized...

By default, changes to the system's user source may not be made from this component. This prevents users from locking themselves out of
the Gateway, or give themselves access to the Gateway.

However, this behavior can be overridden from the Gateway: Config > System > Gateway Settings page, and setting the checkbox for the
Allow User Admin property. This allows for the administration of the Gateway's system user source from the Designer and the Client. Unless
this is enabled, the Vision Module's User Management component is prevented from modifying the Gateway system's selected user source
and you will see an error at the bottom of the component if it is attempted.

Alternatively, you can simply have a separate User Source for the Gateway. This allows you to have a User Source containing all users that
should have client access, and a Gateway-specific User Source that allows access to the Gateway and Designer. This would potentially entail
changing the System's User Source: Config > System > Gateway Settings > System User Source in the Gateway Webpage.

Related Topics ...

User Sources
Internal Authentication
User Management
User Schedules

Internal Authentication

Internal User Sources

An Internal type User Source stores user information internally in the Gateway's database. This
means that Internal User Sources are included in Gateway Backup files, and don't require an
external SQL database, or other external user management system.

When Ignition is first installed, the default User Source that initially grants access to the Gateway On this page
and Design is an Internal type User Source. You can, of course, continue to use this default
internal User Source for your project(s), or you may choose to use other User Sources instead.
...
The Internal User Source is fully manageable from within Ignition. You can access User Sources
from the Gateway Webpage under the Config section, Security > User, Roles, and click the edit Internal User
button. Sources
Property Reference
Main Properties
Password
Policies
Properties

Internal
Authentication
Watch the Video

Property Reference

This section details Internal User Source properties, organized by category.

Main Properties

Details on the Main Properties can be found on the User Sources page.

Password Policies Properties

The Internal User Source has password policies that are configurable from within the Gateway to provide an extra layer of security by
ensuring that good password practices are used.

1. From the Config tab in the Gateway Webpage, select Users, Roles.
2. Click the Edit button for the User Source you want to update.
3. Scroll down to the Password Policy section. You can change the default password policies by entering the appropriate password
values to support your password policies.
Below is a description of the Password Policy properties.

Name Description

Password The maximum age in days that the password will still be valid. After the number of days has past, when the user tries to
Maximum login, it will prompt them to change their password. A value of 0 will disable this feature.
Age

Password The minimum amount of characters that a password must contain to be considered valid. If the user tries to make a shorter
Minimum password, it will not allow it, and let them know that it does not meet the minimum length requirements.
Length

Password This determines how complex a password must be. There are four character types: lowercase letter, uppercase letter,
Complexity digits, and special characters. The value here determines how many of those character types must be present at least
once in the password for it to be considered valid.

Password Determines the number of previously used passwords to store. When users make a new password, old passwords can not
History be re-used. A value of zero disables this functionality. History is only stored while this setting is turned on, so any
passwords used while this is off can be re-used when history is turned back on.

Related Topics ...

Database Authentication
Active Directory Authentication
AD Internal Hybrid Authentication
AD Database Hybrid Authentication
Identity Providers
User Management
Managing Users and Roles
Security

Database Authentication

Database User Source

The Database Authentication type uses an external database instead of storing data inside Ignition.
Managing users is done via direct interaction with the database. This section addresses how to
setup a database user source. The Database Authentication type requires you have a connection
to an existing database, like SQL Server, Oracle, or MySQL. It stores all users, roles, schedules,
and and more in the database, and uses queries to check login credentials. When you create a
database user source, you have the option of setting it up in Automatic or Manual mode. On this page
Automatic Mode
...
In Automatic mode, Ignition will create and manage the database tables for you. You can specify a
prefix for the tables that are created automatically for you, but their names after the prefix are Database User
chosen by the user source. In this mode, the user source will be fully manageable in Ignition. Source
Property Reference
Manual Mode Main Properties
Automatic Mode
In Manual mode, you must provide SQL queries for various functions of the user source. In this
Properties
mode, the user source will not be manageable from the Gateway or the Clients. You'll have to
Manual Mode
manage the users directly through the database. Examples for each of the queries are given on the
To Create a
user source setup page. Read each query description carefully to make sure you design your
Database User
queries to return all the columns that are defined in the query's description as shown below.
Source

Property Reference

Database User Sources have the following properties, organized by category

Main Properties

Details on the Main Properties can be found on the User Sources page. The Database User
Source also has the following properties: Database
Authentication
Name Description

Database The database connection this User Source

Watch the Video
will retrieve user information from.

Mode How the Gateway should manage the

database tables. Has two settings:

Automatic: The gateway will automatically

create the database tables necessary, and all
interactions with the table will use the built-in
queries. When this option is set, the Tablena
me Prefix property is utilized.

Manual: The Gateway will not automatically

create any database tables, nor will it
automatically modify users or roles. When set
to manual, it is assumed that you want to
manually write the queries that update the
tables, or are utilizing another system. When
Mode is set to this option, the Manual Mode
properties are used to determine how the
Gateway should query user data.

Automatic Mode Properties

Name Description

Tablename When set to Automatic mode, this property determines the prefix that will be used on all automatically created tables.
Prefix Useful when multiple database User Sources are connected to the same database scheme.

Manual Mode

Name Description
Authentication A query that must return a row if the given username and password combination provided is valid. The query will run
Query as a prepared statement, so use the question mark character (?) to represent username first and then password. The
returned row may contain the user's basic properties under the column names: [firstname, lastname, schedule,
language, notes]

Note that the Gateway will pass both the username and password the user typed in, so this query MUST utilize exactly
two question marks, otherwise an exception will occur.

List Roles A query that returns all possible roles that any user could be a member of. The role names must be returned in the first
Query column of the query's results.

User's Roles A query that returns all of the roles that the provided user belongs to. The roles must be strings and must be in the first
Query column of the query's results. The query will be run as a prepared statement with one parameter: the username.

List Users A query that returns a row containing each username. There must be at least one column: the username. Other
Query columns are optional, supported columns are: [username, firstname, lastname, schedule, language, notes].

Contact Info A query that returns all of the contact info for the user. The first column must be the contact type, the second column
Query the contact value. Optional, may be blank.

Schedule A query that returns the upcoming schedule adjustments for the user. This property is optional, and may be left blank.
Adjustment
Query The results set expects the following columns:

Start(date)
End(date)
Available(boolean)
Note(string)

Extra A query that returns name, value pairs of extra properties for the user. Will be run with one parameter: the username.
Properties Optional, may be blank.
Query

To Create a Database User Source

1. On the Gateway Webpage under the Config tab, go Security > Users, Roles.
The User Sources page will be displayed. Click the blue arrow, Create new User Source.

2. Choose the Database authentication type, and click Next.

3. The New User Source window will open. Some properties are optional, but if you're using Automatic mode, enter the following
properties as appropriate.

Name: DBAuth - name of the user source.

Failover Source: default - failover user source ('default' is the internal user source).
Failover Mode: Hard - if the source is unreachable, then use the failover source. (Can choose the Hard or Soft option).
Database: MySQL - external database.
Mode: Automatic - tables in the external database will be automatically created when needed.
Tablename Prefix: 'auth_' is the prefix for all the tables that get created. (You can leave this field blank, but if you use a
prefix when the tables get created, they will contain the specified prefix in their name).
When finished, click Create New User Source.
 Table Creation
The tables in the database will not be created in the database until they are needed. For example, as soon as a
user or role is added, the associated tables will automatically get created.

4. Now that your Authentication profile is created, add a user. On the right, click on the More > Manage Users link. Click on the Add
User link and fill in the required fields.

5. Now that your tables are created we can verify them. To view the tables, go into Designer and from the menu bar, select Tools > Da
tabase Query Browser.
You will see all the tables that were created beginning with 'auth_' when the user and role get created.

6. Double click on any of tables beginning with 'auth_', and click Execute. In this example, you will see the tables associated with
'roles' and 'users' displayed in the Schema area.

Related Topics ...

Internal Authentication
Active Directory Authentication
AD Internal Hybrid Authentication
AD Database Hybrid Authentication
Identity Providers
Database Query Browser

Active Directory Authentication

Active Directory User Source

The Active Directory Authentication profile uses Microsoft's Active Directory over LDAP (Lightweigh
t Directory Access Protocol) to store all the users, roles, and more that make up an Authentication
profile. Active Directory Groups are used for Ignition's roles and user-role mappings. On this page
While using an Active Directory User Source, administration of users and roles is through Active
Directory itself, and not manageable within Ignition. Thus adding new users to an Active Directory ...
User Source, or modifying pre existing users, requires the modifications be made from Active
Directory, usually through an AD Administrator. Active Directory
User Source
Property Reference
Main Properties
Property Reference Active Directory
Properties
Active Directory User Sources have the following properties, organized by category LDAP Search
Properties
To Create an Active
Certain properties in the Active Directory User Source allow you to filter users, such as
Directory User
the User List Filter. These filters only determine which users will be displayed on
Source
screen. They are not authentication filters, so even if a user does not show in the list they
can still authenticate and may have access to unintended areas. Be sure to configure pro
ject security appropriately to prevent this from happening!

Main Properties

Details on the Main Properties can be found on the User Sources page.

Active Directory
Authentication
Watch the Video

Active Directory Properties

Name Description

Domain The Windows Domain your active Active Directory server is running on. If you aren't sure of your domain, ask
your network administrator.

Leave blank to set advanced properties manually.

Gateway The login name for the Gateway to use when querying Active Directory. Used for retrieving the list of users and
Username roles via LDAP.

Password The password for the above username.

Primary Domain The IP address or hostname of your primary domain controller. Example: "192.168.1.4" or "MainServer"
Controller Host

Primary Domain The port number for the primary domain controller's LDAP interface.
Controller Port

Secondary Domain The IP address or hostname of your secondary domain controller (optional). Example: "192.168.1.4" or
Controller Host "MainServer"

Secondary Domain The port number for the secondary domain controller's LDAP interface.
Controller Port

SSO Enabled Whether or not to use Single-Sign-On (SSO) to authenticate AD users. This gives you the ability to log into the
Client or Designer automatically with the password you logged into windows with.

For Client SSO login, each project must also have the SSO Login Project Property enabled.

For Designer SSO login, Allow Designer SSO must be set in the Gateway Settings.

SSO Domain The domain that Windows users must match in order to use SSO. If blank, the main "Domain" property will be
used.
LDAP Search Properties

Name Description

Username This prefix will be prepended to the username before an Active Directory bind is attempted for authentication.
Prefix

Username This suffix will be appended to the username before an Active Directory bind is attempted for authentication.
Suffix

Automatic If this option is checked, and the suffix is left blank, then the suffix will automatically be assigned a value of
Suffix "@<domain>".

User Search The base folder to search for users under, such as:
Base
DC=MyCompany,DC=com

The entire subtree under this folder will be searched using the User Search Filter.

Multiple subtrees can be specified by putting them in parenthesis, like so:

(OU=Administrators,DC=MyCompany,DC=com)(OU=Operators,DC=MyCompany,DC=com)

User Search The LDAP search filter that will be used to find a specific user. Use the placeholder {0} as a standin for the login name.
Filter

User List The LDAP search filter used when querying for the list of all users. Should restrict the type to user.
Filter

User Name The attribute on the User object to define the username.
Attribute

User Role Attributes of this name on the User object will define the user's roles.
Attribute

Role Name The attribute of this name on the Role object will define the role's name. Leave blank to use the raw value of the
Attribute attribute defined by the User Role Attribute property.

Full Name The attribute on the User object to define the full name of the user.
Attribute

Phone The attribute name on the user object that represents the user's phone number.
Attribute

Email The attribute name on the user object that represents the user's email address.
Attribute

SMS Attribute The attribute name on the user object that represents the phone number that this user receives text messages on.

Read Timeout The read timeout in milliseconds for LDAP operations.

Results Page The number of entries returned per page of results in a query.
Size

Role Search The base folder to search for roles under, such as:
Base
OU=Roles,DC=MyCompany,DC=com

The entire subtree under this folder will be searched using the Role Search Filter. If you specify the root of your tree
structure, the search may take a very long time.

Multiple subtrees can be specified by putting them in parenthesis, like so:

(OU=Builtin,DC=MyCompany,DC=com)(OU=Users,DC=MyCompany,DC=com)

If you leave this blank the whole subtree of the domain controller will be searched.

Role Search The LDAP search filter that will be used to locate roles.
Filter
 Allow Determines whether the Gateway will accept blank usernames and passwords for authentication. Note that this check
Anonymous takes place on the Gateway, prior to handing off any credentials to the AD server. If Security Authentication is set to
None, then this property should be enabled, otherwise, blank passwords will be rejected by the Gateway.

If true, authentication attempts with blank passwords will be passed through to LDAP, which may choose to accept
them.

Use SSL Works in conjunctions with the Domain Controller Host and Domain Controller Port properties in the Active
Directory Properties section. Disable to use "ldap://" protocol, enable to use "ldaps://"

Security Specifies the security protocol between the Gateway and AD server. The following options are available:
Protocol
AUTO: No security protocol is explicitly used or requested by the Gateway.

SSL: SSL should be used for the connection.

Security This property specifies how usernames and passwords are used to bind to LDAP. The following options are available:
Authentication
AUTO: Unspecified from the Gateway side, meaning the LDAP implementation will choose.

NONE: Anonymous access.

SIMPLE: Plaintext username and passwords will be used.

STRONG: Usernames and passwords will be encrypted.

To Create an Active Directory User Source

To configure an Active Directory User Source, you must specify the host that is acting as your primary domain controller. You can also use a
secondary domain controller in case the primary is unavailable. You'll also need to specify the name of the domain and credentials for the
Gateway itself to use: the Gateway needs a user account to interact with the AD server, even when it's simply querying for a list of roles.

May need to contact your internal IT Department

When using Active Directory User Source, you may need to consult with your internal IT Department to get the required information
to complete your user source setup. These settings are common to AD (not specific to Ignition), and your IT department will know
what values to supply to each property.

1. On the Gateway Webpage, under the Config tab, go to Security > Users, Roles.
The User Sources page will be displayed. Click the blue arrow, Create new User Source.

2. Choose the Active Directory authentication type, and click Next.

3. The New User Source window will open. Note that some properties are optional. In the very least, you must specify the following: Do
main, Gateway Username, Password, Primary Domain Controller Host.
4. If you plan on using Single-Sign-On, then you will need to enable the SSO Enabled property, and continue on to the next step. In
either case, click the Create New User Source button to create the User Source.
5. If you plan on using Single-Sign-On, you need to enable it per project by modifying the project's settings: in the Designer under Proj
ect > Properties.
Under Vision > Login, mark the checkbox for Enable SSO Login. Click OK.

Enable Single-Sign-On (SSO)

SSO is enabled on a per project basis. You have to configure it in the Active Directory authentication profile, and enable it
for each project you want to use SSO with.
 Related Topics ...

Internal Authentication
Database Authentication
AD Internal Hybrid Authentication
AD Database Hybrid Authentication
Identity Providers
User Sources
Project Security in Designer and Gateway

AD Internal Hybrid

AD/Internal User Source

The Active Directory/Internal Hybrid authentication profile type combines the Internal User Source
type with the Active Directory User Source type. Active Directory is used to find all of the users, and
to check their credentials when they attempt to log in. However, it allows assigning of roles, contact
info, and other meta-information about a user through Ignition, then stores all this information as if it
were an Internal User Source. This way, Active Directory can be consulted to see if a
username/password is valid, but the management of roles does not require coordination with your On this page
IT Department, who typically controls the Active Directory system. This "best of both worlds"
approach is popular for many users of Active Directory.
...
The AD/Internal Hybrid User Source is partially manageable in Ignition. Users cannot be added or
removed, and their usernames and passwords cannot be changed. This is because this information AD/Internal User
resides in Active Directory, not within Ignition. Other information, such as user roles, contact info, Source
schedules, are manageable in Ignition. Property Reference
Creating an
AD/Internal Hybrid
Gateway Settings User Source
Before you can use the User Management component to manage roles, contact info,
etc., you first have to go into Gateway Settings, and mark the checkbox to 'Allow User
Admin.' This allows for the administration of the Gateway's system user source from the
Designer and the Client. Unless this is enabled, the Vision Module's User Management
component is prevented from modifying the Gateway system's user source.

Property Reference

This User Source shares many properties with the AD User Source. Please see the Active AD Internal Hybrid
Directory Authentication page for a list of properties.
Watch the Video

Creating an AD/Internal Hybrid User Source

To set up an AD/Internal Hybrid User Source, you must specify the host that is acting as your primary domain controller. You can also use a
secondary domain controller in case the primary is unavailable. You'll also need to specify the name of the domain and credentials for the
Gateway itself to use for authentication for when it queries the list of roles.

May need to contact your internal IT Department for...

When using AD/Internal Hybrid User Source, you may need to consult with your internal IT Department to get the required
information to complete your user source setup.

1. On the Gateway Webpage, under the Config tab, go to Security > Users, Roles.
The User Sources page will be displayed. Click the blue arrow, Create new User Source.

2. Choose the AD/Internal Hybrid authentication type, and click Next.

3. The New User Source window will open. Some properties are optional depending on how you setup your profile.
Related Topics ...
 Internal Authentication
Database Authentication
Active Directory Authentication
AD Database Hybrid Authentication
Identity Providers
User Management Component

AD Database Hybrid

AD/Database User Source

On this page
This AD/Database Hybrid User Source is not manageable from within Ignition. Users/passwords
must be administered through Active Directory, and roles, contact info, and so on, must be
administered directly through the database. The way AD/Database Hybrid works, is it has all the ...
same information requirements as the other authentication profiles, but it also has a number of
Database properties. You need to specify a database (i.e., MySQL) to store information, and set up AD/Database User
queries that you want to use. You must also specify the host that is acting as your primary domain Source
controller, and a secondary domain controller in case the primary is unavailable. You'll also need to Property Reference
specify the name of the domain and credentials for the Gateway itself to use for authentication Creating an
when it queries the list of roles. AD/Database Hybrid
User Source

Property Reference

This User Source shares many properties with both the AD User Source and Database User
Source.

See the Active Directory Authentication page for a list of Active Directory User Source
related properties.
See the Database Authentication page for a list of Database User Source related AD Database Hybrid
properties.
Watch the Video

Creating an AD/Database Hybrid User Source

1. On the Gateway Webpage, under the Config tab, go to Security > Users, Roles.
The User Sources page will be displayed. Click the blue arrow, Create new User Source.

2. Choose the AD/Database Hybrid authentication type, and click Next.

 May need to contact your internal IT Department for..
When using AD/Database Hybrid User Source, you may need to consult with your internal IT Department to get the
required information to complete your user source setup.

3. The New User Source window will open. Some properties are optional depending on how you set up your profile.
Related Topics ...

Internal Authentication
Database Authentication
Active Directory Authentication
AD Internal Hybrid Authentication
Identity Providers
Verifying a User Source
User Sources
Database Query Browser

Fallback Cache Authentication

Overview

This User Source was developed specifically for a system that is using Local Vision Client Fallback, On this page
and allows you to cache the login credentials from a remote user source. This means your users
can still log in with their normal username/password on a Local Vision Client Fallback project, even
when the network connection is unavailable. ...
Overview
Fallback Cache Authentication does not work with Perspective sessions, or with Identity Creating the
Providers in general. This User Source will only function with Vision clients and user Fallback Cache User
sources. Source
Populating the
Cache

Creating the Fallback Cache User Source

The Fallback Cache User Source is created in a similar fashion to any other User Source:

1. On the Gateway Webpage, go to the Config tab. Select Security > User, Roles.
2. Click on the Create new User Source... link.
3. Select the Fallback Cache option and click the Next button.

4. Type in a name for the new User Source and click Create New User Source.
5. Set the additional options for the User Source (Refer to the table below).

Main

Name Description

Name Name of the new User Source.

Description Optional description.

Schedule Restricted Users are only able to log in when their

assigned schedule is active. (Default:
false)
 Failover Source If this source is unreachable for
authentication, this failover source will be
used instead.

Failover Mode The failover mode to use if a failover

source is set.

Hard: Failover only if this source is

un-reachable.
Soft: Try the failover source when a
user fails to authenticate with this
source.

(Default: Hard)

Cache Validation The amount of time between cache

updates of the User Source. (Default:
60,000)

Fallback Cache Properties

Cache Retention Number of days that the cache will retain

recently used credentials. This property
determines the number of days
credentials will be stored in the cache.
Once exceeded, the credentials will be
removed from the cache. (Default: 15)

6. Click the Create New User Source button.

Populating the Cache

Users and Roles can not be manually added to the Fallback Cache. Instead, they are automatically
copied from remote Gateways. This type of User Source is normally configured on an Edge
Gateway, but can be utilized on an Ignition Gateway.

Before the Fallback Cache will populate, both the Central Ignition Gateway and Fallback
Gateway must be connected over the Gateway Network. The credentials are passed from
a User Source on the Central Ignition Gateway to the Fallback Cache over the Gateway
Network.
A Fallback Cache User Source must exist on the Fallback Gateway.
A client must be launched on the Fallback Gateway from the Central Ignition Gateway.
If the user successfully authenticates against the Central Ignition Gateway's User
Source, then the credentials are cached into the Fallback Cache.
 Related Topics ...

User Source

Verifying a User Source

You can verify that a user exists in a given User Source, if the password is correct, what roles a
user has, and any other information added about the user.
On this page
To Verify a User
...
1. On the Gateway Webpage, go to the Config tab. To Verify a User

2. Choose Security > Users, Roles from the menu on the left.
The User Sources page is displayed.

3. Select the Verify an Authentication Profile link.

Verifying an
Authentication
Profile
Watch the Video
4. The Verify Authentication Profile window will appear. Choose a Profile from the dropdown
list.
Enter a Username and Password. Click Test Login.
Ignition will test the credentials then display the results of the validity test.
 If the Login is incorrect, an error message will appear stating that the Login failed for a
specified user.
If the Login is correct, a successful message will appear for a specified user along with
their information.

Related Topics ...

Gateway Common Tasks

Identity Providers

An Identity Provider (IdP)

offers a way for users to log in to Ignition using
credentials stored outside of Ignition. An IdP creates, maintains, and On this page
manages identity (login) information while providing authentication services
to Ignition. This provides a secure login that allows Ignition to use SSL and
...
two-factor authentication (2FA).
Identity Provider
Authentication
In 8.0, Identity Providers are only utilized by Perspective. Authentication in other areas of Workflow
Ignition, such as the Vision module, is handled by User Sources. Types of Identity
Providers
Suggested
External Identity
Providers
Using Identity
Providers

Identity Provider Authentication Workflow

The following diagram illustrates how IdP authentication works.
 1. User starts a Perspective Session.
2. User attempts some action that requires authentication.
3. User is Redirected to Identity Provider: The Session sees that authentication is required and redirects the user to a webpage
hosted by the IdP.
4. IdP Authenticates the User: The IdP prompts the user with a security challenge, such as requesting a username and password.
The extent of the challenge depends entirely on the provider, but many providers may offer support for multi-factor authentication
(MFA).
5. User Responds: The user correctly responds to the security challenge.
6. Redirect back to the Session: If the IdP successfully validates the user, it will redirect the user back to the Perspective Session.
Some IdPs may have an additional workflow they will guide the user through, such as re-verifying an email address or replacing an
expired password. The IdP will also return information about that user to the Session. This provides some context about the user that
the Session can use to assign Security Levels.
7. Update the User's Security Level: Once back at the session, the user will be mapped to the specified Security Level, giving the
user access to the restricted action.

Types of Identity Providers

The following types of providers are available. More information on the types can be found on the Identity Provider configuration reference
page.

Ignition - The Gateway will act as an Identity Provider, accepting authentication requests from other Perspective Sessions. Users
and roles are stored internally to Ignition. Useful when an external identity provider is unavailable.
OpenID Connect 1.0 - Used to configure an external IdP via OpenId Connect.
Security Assertion Markup Language (SAML) - Used to configure an external IdP via SAML.

Suggested External Identity Providers

Your organization's IT may have some sort of existing integration with an Identity Provider. Some popular Identity Providers are listed below.

Ping Identity
Okta
Active Directory Federation Services
Duo

Using Identity Providers

 Once an Identity Provider has been configured, there are a few things that can be done to test and adjust how it works. You can map the
attributes that are returned in the IdP response document to more familiar user properties that are available to use within the project. You can
add rules to custom security levels that determine when a user falls into the level. Overrides can be given to users in the form of User Grants,
so that they are granted certain security levels regardless of the rules. Finally, you can test out the IdP by logging in with a user to confirm
what is returned in the response document.

In This Section ...

Configuring Identity Providers

Registering the Ignition Gateway

On this page
Before configuring an Identity Provider on the Ignition Gateway, it must first be registered as an
Identity Provider Client. Your Identity Provider will have a workflow to register, and it will most likely
request something called a return URL or redirect URI. The paths provided utilize your Gateway's ...
address/hostname, and they change depending on the type of provider.
Registering the
Ignition Gateway
Secure
The same redirect URI is used for login and logout Integration with
IdPs
Configuring an
Identity Provider
OpenID Connect Providers (OP): Common Properties
Ignition Identity
Provider
OpenID Connect Providers OpenID Connect
http://yourGatewayAddress:Port/data/federate/callback/oidc Providers
Importing
Metadata from
SAML Providers: the Provider
Configuring the
Provider
SAML Providers
JSON Web Key
http://yourGatewayAddress:Port/data/federate/callback/saml Configuration
Security Assertion
Markup Language
(SAML) Providers
Secure Integration with IdPs Importing
Metadata from
You should always use the secure SSL versions of those redirect URIs (https) in production the Provider
environment. To do this you must enable SSL in Ignition and install a valid certificate. This is the Configuring the
best practice for maintaining a secure integration with third party Identity Providers. Provider
SAML Signature
Verifying Key
Configuration
IdP Examples and
Troubleshooting

Configuring Identity
Providers
Watch the Video
Configuring an Identity Provider

Although there are several types, the general workflow for creating an Identity Provider is the same.

1. On the Gateway Webpage, click on the Config tab.

2. Under the Security section, click on Identity Providers. The Identity Providers screen is displayed. This screen will list all IdPs that
have been configured. You can change filter by name or adjust the number of IdPs displayed in the view.

3. Click on Create New Identity Provider...

4. Choose the type of provider. The current options are Ignition, OpenID Connect 1.0, or Security Assertion Markup Language 2.0
(SAML).
 5. Click the Next button.
6. Configure the adapter. This step varies based on the type of provider. Please see the reference tables below for a description of
properties.
7. Once you've filled in the properties, click Save.

Common Properties

All Identity Provider types share the following properties:

Property Name Description Required?

Provider Name The name of the adapter. Adapter names must be unique, so no two adapters on the same Gateway Yes
may have the same name.

Provider A description of the provider. No

Description

Provider Type The type of Identity Provider. The value for this field comes from the previous screen. It cannot be Yes
changed here.

Ignition Identity Provider

The Ignition Identity Provider also has the following property:

Property Name Description Required?

User Source The User Source for this IdP. Yes

OpenID Connect Providers

OpenID Connect Providers (OP) properties are listed in the following tables. The values on many of these properties may require you to refer
to information from your third-party IdP.

Importing Metadata from the Provider

This method is preferred because of its ease-of-use and accuracy. After importing, you will only need to add your client ID and secret
manually. (However you can revise the imported data if needed as well.)

Property Description
Name

Import URL to the OpenID Provider Configuration document. Typically, if the issuer is "https://example.org/foo" then the metadata
from URL URL would be "https://example.org/foo/.well-known/openid-configuration"

Import File must be a JSON document with the properties described in section 3 (OpenID Provider Metadata) of the OpenID
From File Connect Discovery 1.0 specification.

Configuring the Provider

Most OpenID Providers will require registering Ignition as a client. After the registration process is complete, the provider will generate a client
ID and secret for Ignition, which is required below. This gives Ignition the ability to communicate securely with the provider. Most providers will
also require a set of redirect URIs. The redirect URI for this Ignition Gateway is: http://docker.ia.local:51276/data/federate/callback/oidc
Property Description Required?
Name

Client ID The client identifier registered within the identity provider. This value is provided the Identity Provider. Yes

Client Secret The client secret registered within the identity provider. This value is provided by the Identity Provider. Yes

Authorization URL of the OP's OAuth 2.0 Authorization Endpoint. Yes

URL

Token URL URL of the OP's OAuth 2.0 Token Endpoint. Yes

Logout URL Optional URL at the OP to which an RP can perform a redirect to request that the end user be logged out No
at the OP.

JSON Web URL of the OP's JSON Web Key Set document. No
Keys URL

Use Json If checked, then identity provider public keys will be automatically downloaded from given JSON Web Keys No
Web Keys URL. New keys will be automatically fetched when the identity provider generates new keys. If unchecked,
URI then the static set of JSON Web Keys (configured below) are used, so when the identity provider rotates
keys, they must be manually added to this configuration.

Issuer Entity that issues a set of claims. Yes

Supported A list of the JSON Web Signature (JWS) signing algorithms supported by the OP for the ID Token to
ID Token encode the claims in a JWT.
Signing Click here to see options
Algorithm
Values

Scope A list of default scopes which will be sent for each auth request to the OP. No

JSON Web A list of signing key(s) the RP uses to validate signatures from the OP. No
Key Config

JSON Web Key Configuration

Property Description Required?

Name

Key Type The cryptographic algorithm family used with the key. Options are EC, RSA or oct. Yes

Public Key The intended use of the public key. Options are sig or eng. No
Use

Key The operation(s) for which the key is intended to be used. No

Operations

Algorithm The algorithm intended for use with the key. Yes

Key ID Used to match a specific key. No

X.509 URL A URI that refers to a resource for an X.509 public key certificate or certificate chain. The identified No
resource MUST provide a representation of the certificate or certificate chain that conforms to RFC 5280 in
PEM-encoded form, with each certificate delimited as specified in Section 6.1 of RFC 4945.

X.509 The "x5c" (X.509 certificate chain) parameter contains a chain of one or more PKIX certificates. Each entry No
Certificate must be a base64-encoded (Section 4 of RFC4648 -- not base64url-encoded) DER PKIX certificate value.
Chain

X.509 A base64url-encoded SHA-1 thumbprint (a.k.a. digest) of the DER encoding of an X.509 certificate. No
Certificate
SHA-1
Thumbprint
 X.509 A base64url-encoded SHA-256 thumbprint (a.k.a. digest) of the DER encoding of an X.509 certificate. No
Certificate
SHA-256
Thumbprint

There are some additional properties, that depend on which Key Type is selected.

Key Type: EC

Property Description Required?

Name

crv (Curve) The cryptographic curve used with the key. Yes

x (X The x coordinate for the Elliptic Curve point represented as the base64url encoding of the octet string Yes
Coordinate) representation of the coordinate.

y (Y The y coordinate for the Elliptic Curve point represented as the base64url encoding of the octet string No
Coordinate) representation of the coordinate.

d (ECC Private The Elliptic Curve private key value represented as the base64url encoding of the octet string No
Key) representation of the private key value.

Key Type: RSA

Property Name Description Required?

n (Modulus) The modulus value for the RSA public key represented as a Base64urlUInt-encoded value. Yes

e (Exponent) The exponent value for the RSA public key represented as a Base64urlUInt-encoded value. Yes

d (Private The private exponent value for the RSA public key represented as a Base64urlUInt-encoded value. No
Exponent)

p (First Prime The first prime factor represented as a Base64urlUInt-encoded value. No

Factor)

q (Second The second prime factor represented as a Base64urlUInt-encoded value. No

Prime Factor)

dp (First Factor The Chinese Remainder Theorem (CRT) exponent of the first factor represented as a No
CRT Exponent) Base64urlUInt-encoded value.

dq (Second The CRT exponent of the second factor represented as a Base64urlUInt-encoded value. No
Factor CRT
Exponent)

qi (First CRT The CRT coefficient of the second factor represented as a Base64urlUInt-encoded value. No
Coefficient)

oth (Other Information about any third and subsequent primes, should the exist. Each new Prime added will provide No
Primes Info) users with new Prime Factor, Factor CRT Exponent, and Factor CRT Coefficient properties, all of which
are required.

Key Type: oct

Property Description Required?

Name

k (Key The value of the symmetric (or other single-values) key represented as the base64url encoding of the octet Yes
Value) sequence containing the key value.

Security Assertion Markup Language (SAML) Providers

The properties for Security Assertion Markup Language (SAML) are listed in the following tables. The values on many of these properties
may require you to refer to information from your third-party IdP.
Importing Metadata from the Provider

This method is preferred because of its ease-of-use and accuracy. After importing, you will only need to add your client ID and secret
manually. (However you can revise the imported data if needed as well.)

Property Name Description

Import from URL to the SAML Identity Provider Metadata document.

URL

Import From File must be an XML document which conforms to the SAML 2.0 metadata schema described in
File saml-metadata-2.0-os.

The SAML Service Provider (SP) metadata for an Ignition Gateway may be accessed at the following URL: http://<ipaddress>:<port>/data/
saml/metadata/sp.

The Assertion Consumer Service (ACS) URL for this Ignition Gateway is: http://<ipaddress>:<port>/data/federate/callback/saml

Both of these addresses assume you know the IP Address and port of your Ignition install. For example, if you are on the computer Ignition is
installed on, you could use: http://localhost:8088/data/saml/metadata/sp for the SP metadata.

Configuring the Provider

Property Description Required?

Name

Entity ID The Identity Provider's Entity ID. Yes

Assertion The expected binding used by the Identity Provider when interacting with Ignition's Assertion Consumer Yes
Consumer Service.
Service
(ACS)
Binding

Name ID The expected name ID format for subjects of assertions resulting from Authn Requests. Options are Yes
Format UNSPECIFIED, EMAIL_ADDRESS, X509_SUBJECT_NAME, WINDOWS_DOMAIN_QUALIFIED_NAME,
KERBEROS_PRINCIPAL_NAME, ENTITY_IDENTIFIER, PERSISTENT_IDENTIFIER,
TRANSIENT_IDENTIFIER.

Single The Identity Provider's Single Sign-On (SSO) Service URL. Yes
Sign-On
(SSO)
Service URL

Single The binding Ignition will use for sending Authn Requests to the Identity Provider's Single Sign-On (SSO) Yes
Sign-On Service.
(SSO)
Service
Binding *

Force Authn Check this box to force complying Identity Providers to authenticate the user each time instead of relying Yes
on a previous security context. See section 3.4.1 of saml-core-2.0-os for more details.

Validate Check this box to validate the signature of the response from the Identity Provider. Yes
Response
Signatures

Validate Check this box if it is expected that assertions will be signed. Ignition will validate the signatures of each Yes
Assertion assertion.
Signature

Signature A list of signing key(s) that Ignition uses to validate signatures from the IdP. Yes
Verifying
Keys
 Signature A base64-encoded DER PKIX certificate value. No
Verifying
Certificates

SAML Signature Verifying Key Configuration

Property Name Description Required?

Key Algorithm The algorithm identifier for this signature verifying key. Options are DSA, RSA, or EC. Yes

Key Value A base64-encoded DER key value. Yes

IdP Examples and Troubleshooting

The OpenID Connect 1.0 Example page will show you how to configure an external IdP that used OpenID Connect 1.0 with your Ignition syst
em.
Go to Troubleshooting Identity Providers for helpful examples to help you diagnose and troubleshoot issues with configuring IdPs.
Refer to SAML Example page for how to connect an Identity Provider that is using the SAML protocol.

User Attribute Mapping

The User Attribute Mapping page allows you to map information in the Identity Providers (IdP)
response document to easily understandable properties. These properties are then made available
as Session Properties in the Perspective Session. To work, this requires that you are already On this page
connected to an IdP and are getting fields back when a user logs in.

...
Configuring User Attributes Configuring User
Attributes
There are two ways of mapping user attributes: Direct and Expression. Direct mappings require User Attribute
that you enter in the path to the attribute in the response document that you want to map to that Mapping Property
particular property. Expression mappings allow you to use the expression language to derive the Reference Table
attribute from contextual data such as the IdP response document or tags. The IdP Attributes and
Security Zones can be accessed in the same way as the expressions for the Security Level Rules.

1. From the Gateway Webpage Config tab, click on Security > Identity Providers.
2. Select the Identity Provider and click on User Attribute Mapping under the More button.

User Attribute
Mapping
Watch the Video
 3. The Name, Description, and Provider Type are not editable here, but are listed on the
page to make clear which IdP the User Attribute Mapping is being configured on.

4. Change the Type for each attribute to edit additional fields.

5. When you're finished mapping user attributes, click Save.

User Attribute Mapping Property Reference Table

Property Name Description

 ID The unique ID of the user.

Username The username of the user.

First Name The user's first name.

Last Name The user's last name.

Email The user's email.

Roles The user's roles.

Security Level Rules

When a user accesses a Perspective project, they can fall into one or more of many Security
Levels that you can set up. The Security Level Rules determine if the user has that Security Level
or not. The rules come in the form of expressions that can access any of the Expression On this page
Language's functions, Tag values, Security Zone information, or Identity Provider attributes.
Security Level Rules are accessible from the Gateway Webpage Config tab in Security > Identity
Providers. ...
Predefined Rulesets
Defining Security
Predefined Rulesets Level Rules
Special Object
One thing you may notice right away is that on the Security Level Rules page, many of the built in Reference
Security Levels are missing. Some Security Levels don't allow you to create an expression that Special Function
defines their rules. These particular Security Levels already have a set of rules that govern how a Reference
user gets them. The Security Levels corresponding to the different Security Zones are Special
automatically given to users depending on which zones they fall into. Similarly, the Security Levels Considerations
that correspond to the Roles a user gets while authenticated are automatically given to users for Rules
depending on what roles we receive from the Identity Provider. These Security Levels are removed Configuring Security
from the tree here because rules can't be defined on them. The "Public" and "Authenticated" Level Rules
Security Levels also can't have Security Level Rules defined on them, but are present in the tree
because they can potentially be a parent to custom nodes which can have Security Level Rules.
The Public level is granted to every user when they open the project, and the Authenticated level is
granted when the user authenticates against an Identity Provider, regardless of what roles they
may have.

The Security Level Rule in the following example checks to see if any of the "Manager" or
"Operator" roles are present.

Security Level
Rules
Watch the Video
Defining Security Level Rules

For the Security Levels that can have rules defined, the rules are defined in the form of an expression which should return either True or
False, the results of which determine whether a user falls into that level or not. The rules can take advantage of everything the expression
language has to offer, including the built in expression functions and any Tag values. The expressions here also have the unique ability to
access attributes from the Identity Providers response document for the authenticated user, as well as what Security Zone the user falls into.

Special Object Reference

These special objects can be used to reference information gathered from the IdP response document or the Security Zone that the user falls
under.

Object Name Description

{security-zones} This object gives the collection of security zones that the user currently has. The collection can be handled
using one of the unique functions: containsAll or containsAny.

{idp-attributes:X} This object gives you access to specific information within the Identity Provider's response document, where
"X" is the path to the attribute in the document. This path can vary depending on what IdP the user has
authenticated through. Can be used in the unique functions containsAll or containsAny if the
information returned is a collection object, such as a role list.
If using Ignition as the IdP, available paths will be:

Attribute Path Example

ID sub {idp-attributes:sub}

Username preferred_username {idp-attributes:preferred_username}

First Name given_name {idp-attributes:given_name}

Last Name family_name {idp-attributes:family_name}

Email email {idp-attributes:email}

Roles roles {idp-attributes:roles}

While these are available for use, what they return is dependent on what is set up in the User
Source for that number.

The {idp-attributes:X} object is only available to Security Levels that fall within the Authenticated Security Level. See below under
Special Considerations for Rules.

Special Function Reference

When writing an expression to determine Security Level Rules, there are functions available that are not a part of the normal set available to
Expression Bindings. These additional functions are:

Function Name Description Example

 containsAll(collection, Checks to see if all of the listed elements are containsAll({security-zones},
element 0, ..., element present in the collection object. The function 'PlantA', 'Floor1', 'Press Room')
N) requires at least two arguments, a collection
and an element.

containsAny(collection, Checks to see if any of the listed elements are containsAny({idp-attributes:roles},

element 0, ..., element present in the collection object. The function 'Manager', 'Operator')
N) requires at least two arguments, a collection
and an element.

Special Considerations for Rules

When defining rules for a Security Level, it is important to note where in the Security Level tree you are. If you want to access information out
of the Identity Provider such as the username, you will need to ensure that the Security Level is located in the Authenticated branch. User
information is only captured once a user logs in, so that information will only fall under Security Levels that come from the user being
Authenticated. If a Security Level lies outside of the Authenticated branch, then the level will only have access to information such as Tag
values and Security Zones.

Configuring Security Level Rules

1. From the Gateway Webpage under the Config tab, go to Security > Identity Providers.
2. A list of the Identity Providers will be displayed. Click the More button for the Identity Provider you wand to edit, and select Security
Level Rules.

3. Select the Security Level Name and, if a rule is defined, it will appear in the Rule field. If not, you can create one. We copied the
expression "containsAny ({security-zones}, 'PlantA', 'Floor1', 'Press Room')" from the example above for the following
example.
 4. After your enter your rule, click Save.

User Grants

A User Grant is a way to directly assign a user to a Security Level, even if they do not meet the
requirements of the Security Level Rules. User Grants essentially act as an override to the original
rules of the Security Level. On this page
User Grants are accessed from the Gateway Webpage Config section in Security > Identity
Providers. Users can be added and edited using the buttons in the Users table so that Security ...
Levels can then be granted to them.
Configuring a User
Grant
When adding, editing, and deleting users in User Grants, you are only modifying the User
Grant (whether the user is granted permission that overrides the Security Rules). The
user is not changed in the Identity Provider.

Users are identified by either their username or their ID from the provider response document.
Once you have identified a user, you can assign them any number of grants to Security Levels.
Selecting a level will automatically select all security levels above it. The User Grants can only be
applied to a user after they authenticate with the Identity Provider, though the grants do not have to
be for levels within the Authenticated branch.
User Grants
The system can't validate any user created here against actual users in the Identity
Provider (IdP). Instead, the username or ID needs to be entered exactly, and when a Watch the Video
user logs in, the system will check to see if they match any of the configured
usernames/IDs to give User Grants to.

Configuring a User Grant

There are two parts to configuring a User Grant: Adding a user then applying User Grants.

1. From the Gateway Webpage Config tab, click on Security > Identity Providers. The screen will refresh and you will see a list of all
your IdPs.
2. Choose the IdP and click the More button to see the actions in the dropdown list.
3. Select User Grants.

4. To add a new user, click the Add

icon.
5. Choose how you will identify the user; either with a username or an ID. Click Confirm to save the changes.
 6. With the user created and highlighted in the Users table, select Security Levels to grant them when they Authenticate with this
Identity Provider.

7. Click Save.

Now you can test this user through the Test Login and Logout screen to verify the new roles have been assigned.

Test Login and Logout

On the Identity Providers screen you can test a username and password combination against an
Identity Provider (IdP).
On this page
When you select the Test Login option for your IdP, it will confirm the IdP name and Type that you
are testing against. It gives you a way to test your attribute mapping configuration and your security
level rules / direct user grants configuration ...
Clicking the Test Login button will redirect you to the IdP where you can login. Upon successful Testing a Login
authentication with the IdP, the page navigates back to Ignition, and Ignition displays the response Testing Logout
document as the results. These results can vary between IdPs, so it can be useful to test out a
login to see what your IdP returns in its response document.

You can use Test Logout option to log out of the ID you were testing.

Testing a Login

1. From the Gateway Webpage Config tab, go to Security > Identity Providers. The window will refresh and your list of Identity
Providers will be displayed.
2. Choose the Identity Provider and click the More button to see the actions in the dropdown list, and select Test Login.
3. Confirm the IdP, and click the Test Login button at the bottom of the screen.

4. Login at your IdP's login screen.

5. If the login is successful, you will be returned to the Identity Provider Test Login screen. The returned results will be displayed under
the IdP Response Data tab.
6. Click on the Mapped User Attributes tab to view the user attributes for the currently logged in user.

7. Click on the Security Level Grants tab to view the Security Levels for the roles of the currently logged in user.
Testing Logout

After testing a User ID, you do not want to stay logged in as the user. You can use the Test Logout function to log out. For the Ignition IdP,
this function also logs you out of the IdP. For an OpenID Connect IdP, this function will also log you out of the IdP if you have a Logout URL.

1. To log out of the ID you were testing, click the Test Logout button on the Test Login page.

2. You will get a confirmation message of a successful logout.

Security Levels

With Security Levels, you define a hierarchy for access inside a Perspective Session. This
authorization system provides a way for you to map roles from an Identity Provider (IdP) to Ignition
roles. Any IdP can be used to provide roles, and security levels are independent of the type of IdP On this page
being used. Any role from the IdP is automatically granted to the user as a role, but only roles in
your Security Levels are available to the security screens in the Designer. You can also use the Us
er Grants option to grant additional access for each user. ...
Security Levels are defined at the Gateway and they are arranged in a tree structure. Each child Reserved Security
(nested) level of the tree inherits the security of its parent levels. Levels
Public
There are four reserved Security Levels in the platform: Authenticated
Authenticated/Rol
Public es
Authenticated SecurityZones
Authenticated/Roles Custom Security
Security Zones. Levels
Add a New Security
To access Security Levels, go to the Gateway Webpage under the Config tab, and choose Securit
Level
y > Security Levels. Editing Security
Levels
Delete a Security
Level
Import a Security
Levels Configuration
Export a Security
Levels Configuration

Security Levels
Watch the Video

Reserved Security Levels

The reserved security levels are mostly created for you, and have special rules that determine when a user is granted that level. They can't be
renamed or deleted.

Public

All users are always granted the Public security level, even if they are not authenticated (logged in). Public security level indicates open
access and the least amount of security. A session that only has the Public security level is not authenticated. This is similar to being a guest
or anonymous. Unless another security level is required, guest access will be allowed. The Public security level is the ancestor of all other
security levels in the hierarchy.

Authenticated

The Authenticated Security Level is a child of the Public Security Level. If a session has authenticated against the configured IdP
successfully, the Authenticated Security Level is granted. Users are required to be logged in in order to have access to this level.

Authenticated/Roles

The Roles level is a special level which itself has no special rules, but it acts as a parent placeholder for potential roles returned from the IdP.
This particular level is not configurable; however there can be levels added underneath the Roles level as children. These levels should
correspond to the names of roles that would be expected from the IdP. If the IdP provides role information, these roles are automatically
mapped to the child security levels underneath Authenticated/Roles. The names of the roles must match exactly for them to be correctly
mapped to. For example, if you authenticate against the Ignition IdP configured to delegate to the Internal user source, and your user was
granted the roles “A”, and “B”, you would have (at a minimum) the following security levels granted to you:

Public
Authenticated
Roles
A
B

You can only add one level of children to the Roles Security Level. Custom Roles can be nested as deeply as you want.

SecurityZones

The SecurityZones level is another special placeholder level that itself has no rules but is a parent for all of the Security Zones on the
Gateway. Security Zones are automatically pulled in from the Gateway. A Security Zone is a list of Gateways, Computers, or IP addresses
that are defined and grouped together. This group is a zone on the Gateway Network, which can have additional policies and restrictions
placed on it. Security Zones provide a way to bridge the IdP method of permissions with location-based permission modeling. You cannot
add, edit, or remove the SecurityZones node or any node in the SecurityZones sub-tree.

Custom Security Levels

Custom Security Levels can be added to almost anywhere within the tree. When these levels are granted to a user is determined by the Secu
rity Level Rules, which can pull information from the IdP, Security Zones, and even Tags. The placement of custom Security Levels can affect
when they may be potentially granted to a user. Any custom levels set under the Public level, but not within Authenticated, do not need to
have a user authenticate against the IdP to be granted to a user. However, custom levels within Authenticated do need to have the user
authenticate to be granted to the user, even if the rule for that level does not use any of the IdP attributes.

Add a New Security Level

1. From the Gateway Webpage Config tab, click on Security > Security Levels.
2. In the Security Level tree, select the level that will be a parent for the new level.
3. Click the Add Security Level button.

4. In the Security Level Details screen area, enter the Name for the level.

Security Level names within the same parent must be unique.

 4.

5. The path for the parent is filled in automatically. Use the Parent dropdown list if you want to change the parent for this new level.

6. Add a Description for the new level (optional).

7. If you make changes to Security Levels, but decide not to save them, you can use the Reset button

to return the tree view to its currently saved configuration.

8. To save the changes, press Save.

Editing Security Levels

1. From the Gateway Webpage Config section, click on choose Security > Security Levels.
2. In the Security Level Tree, select the level that you want to edit.
 3. Make the desired changes in the Security Levels Details screen area.
4. If you make changes to Security Levels, but decide not to save them, you can use the Reset button

to return the tree view to its currently saved configuration.

5. To save the changes, click the Save button.

Delete a Security Level

When you delete a Security Level, all children under that level will also be deleted.

1. From the Gateway Webpage Config tab, click on Security > Security Levels.
2. In the Security Level tree, select the level that you want to delete.
3. Click the Delete button on the Security Level Details screen.
 4. In the confirmation box, click Delete to confirm the delete.

Import a Security Levels Configuration

1. From the Gateway webpage Config tab, click on Security > Security Levels.
2. Click the Import icon

.
3. Choose Import on the confirmation screen.

4. Choose a security levels configuration file to import.

5. Click Open.

Export a Security Levels Configuration

1.
 1. From the Gateway Webpage Config tab, choose Security > Security Levels.
2. Click the Export icon

.
3. The security levels configuration will be saved as a .json file with a unique number, for example:

Security Zones

What are Security Zones?

A Security Zone is a list of Gateways, Computers, or IP addresses that are defined and grouped
On this page
together. This group now becomes a zone on the Gateway Network, which can have additional
policies and restrictions placed on it. While Users and Roles restrict access to specific functions ...
within the Gateway like making certain controls read-only for certain users and read/write for
others, Security Zones provide this functionality to the Gateway Network, limiting locations instead What are Security
of people to be read-only for specific actions. This allows for greater control over the type of Zones?
information that is passing over the network, improving security and helping to keep different areas Using Security
of the business separate, while still allowing them to interconnect. Zones
Defining a Security
Zone
Identifiers
Qualifiers
Service Security

Security Zones and

Service Security
Watch the Video
Using Security Zones

Sometimes, in addition to knowing who the user is, it is important to know their location. An
operator may have permissions to turn on a machine from an HMI, but if the operator is logged into
a project on a different Gateway in the network that has remote access to those Tags, it might not
be a good idea to let the operator write to those Tags from a remote location. The operator can't
see if the physical machine is clear to run.

This is where Security Zones come in. While Security Zones themselves don't define the security,
they instead define an area of the Gateway Network, breaking up Gateways and network locations
into manageable zones that can then have a Security Policy set on them. Once there are zones
defined, a Security Policy can be assigned to each zone, and a priority of zones can be set in the
event that more than one zone applies in a given situation.

When using zone-based security in a project, the project stores the name of the security
zone as a string. This means that if you were to modify the name of the zone in the
Gateway, the zone-based security in your project will not update to reflect the new name,
and instead will try searching for a zone with the original name. Be very careful when
modifying the names of security zones.
Defining a Security Zone
When setting up a new Security Zone, it is a good idea to setup a Gateway Network first if you haven't already. While Security Zones can be
defined and used without a connected Gateway, they work best when used in conjunction with other Gateways on a Gateway Network.

Security Zones are defined under the Config tab of the Gateway Webpage by going to Security > Security Zones.

There is a special zone called Default. It is always present and can't be modified, and will be used if an incoming connection does
not match any of the other defined zones.

Selecting the Create new Security Zone link brings up a new page where the Security Zone can be defined.

Besides the name and description, there are two major sections here: Identifiers and Qualifiers. These are two forms of checks that need to
happen before an incoming connection gets placed in a Security Zone.

Identifiers

The identifiers are how incoming connections are distinguished between different zones. While there are a few different ways to define the
incoming connection, it only needs to match one of them to match this zone.

IP Addresses - This defines an IP address that the connection is coming from. This can be a list of IP addresses by using commas
to separate them. It can also make use of the (*) wildcard like '192.168.100.*', or use a range such as '100.100.1-100.0-255'. With IP
addresses, virtually all connections can be listed. Use 127.0.0.1 for the local connection.
Host Names - The host name refers to the system name of the machine generating the request such as Joe_Workstation. This can
be a list of names separated by commas, and it can also use the (*) wildcard like '*_Workstation'.
Gateway Names - The Gateway name is the name of the Ignition instance. This is set in the Config section by going to System >
Gateway Settings, and changing the System Name. This can be a comma separated list and can use the wildcard such as '* Ignition
Gateway'.

Many incoming connections can be defined using any of the three identifiers, or even multiple at once. As mentioned before, an incoming
connection only needs to match one of the identifiers for it to be accepted.

When identifying a Gateway through a proxy Gateway, the IP Address should be using the IP of the proxy, but the Gateway name
should use the name of the Gateway we are trying to identify.
Qualifiers

After first being identified as part of a particular Security Zone, the connection then must check the Qualifiers. With the Qualifiers, the
incoming connection needs to fit in with all of the properties before it is fully placed into the Security Zone.

Require Secure Connection - If this is true, only connections that are made over a secure channel will be accepted.

A Security Zone is only able to check connections made to the Gateway the zone is defined on. This means that
connections through a proxy Gateway may not be secure.

Direct Connection Required - If this is true, only connections that come from a direct connection will be accepted. The Gateway
Network allows you to connect three Gateways in a 1-2-3 configuration, where Gateway 1 can see Gateway 3 through the proxy
Gateway 2.
Allow Client Scope - If this is false, any client scoped requests will not be accepted.
Allow Designer Scope - If this is false, any Designer scoped requests will not be accepted.
Allow Gateway Scope - If this is false, any Gateway scoped requests will not be accepted.

As mentioned above, a connection must pass all of the qualifier checks before being accepted into a Security Zone. So if Require Secure
Connection was checked, and Allow Client Scope was not, any requests coming from Clients would be rejected even if they are secure, and
the same goes for any non-secure connections coming from sources other than a Client.

Requests can be a part of more than one zone, depending on how the zones are setup. This can be useful for making a whole section of IP
addresses read only, but a specific Gateway in that IP address range may be listed specifically in another zone, which can be given
read/write access. Any connection which does not fall into one of the zones will be placed in the Default zone.

After entering all the information on the Security Zone page, click Create New Security Zone. The page will refresh and you will see a green
banner stating that your new Security Zone was successfully created.

Service Security
After creating some Security Zones, a Security Policy can then be defined for each zone. This can be found by going to the Config section of
the Gateway Webpage and navigating to Security > Service Security. At first, none of the zones will have a policy defined, and the Default
zone will be at the top. Editing any of them will bring up the Security Policy definition page for that zone. The Security Policy has four
sections: Alarm Notification, Alarm Status, History Provider Access, and Tag Access. They work together to define how the local Gateway
gives access to incoming Gateway connections. All four sections also have the ability to completely block access to specific services with the
Service Access setting in each section. Setting that to deny will deny the zone access to that particular information, regardless of what the
rest of the options are set to.

It is important to realize that if you have a single Gateway, limiting access of certain clients to certain Tags is still done in the individ
ual Tags.

Alarm Notification - The Accessible Pipeline Filter setting is a list of Pipelines in the current Gateway that other connections can use
for alarm notification. Pipelines must be entered in the format "project_name/pipeline_name". The list is a comma separated list, and
it can make use of the (*) wildcard. This setting is an inclusionary list not an exclusionary list, meaning that if there are no pipelines
listed here, then all of them will be available.

Alarm Status - The Allow Acknowledge setting will allow the Gateways that fall within the zone to acknowledge alarms on the local
Gateway. The Allow Shelving setting will allow the Gateways that fall within the zone to Shelve alarms on the local Gateway. IE:
Other Gateways can shelve alarms on this Gateway. For this Gateway to shelve alarms on others, this must be set on the remote
Gateway.

History Provider Access - The History Provider Access has two different settings. First, it has a Default Access Profile. This is the
default access rights for Tag History. Second, there will be a setting for each History Provider setup on the local Gateway. In the
image below, there is an "Access Level: 'New Connection" that can be set that corresponds to the History Provider that was created
when a database was connected. It can be set to Query and Storage, which will allow connections in the current zone to both run
queries and store Tag History against the Tag History provider, Query Only, which will only allow the zone to query out history data,
but not store it, and No Access, which will completely block access to that History Provider. The final setting is Inherited, which will
inherit the Default Profile Access rights. Any new history providers will automatically get added to the Security Policy set at inherited
so it may be beneficial to set the Default Profile Access to be either Read Only or No Access so that a recently added history provider
does not accidentally get storage rights when it should not.

The Default Access Profile should not be set to Inherited. This also goes for the Default Provider Access Level in the Tag
Access section.

Tag Access - The Tag Access section also has a few different settings. The Default Provider Access Level, which works the same
as the History Provider Default Access Profile. It sets the default access rights for realtime providers. It will then have a setting for
each provider configured in the local Gateway, as well as an additional one for system Tags. These can be set to ReadWriteEdit,
which will allow connections in the current zone to read, write to, and edit the Tags in that provider, ReadWrite, which allows the
zone to read and write to Tags, and ReadOnly, which only allows the zone to read the Tags. It also can be set to None, which will
prevent the zone from interacting with the Tag Provider altogether, and Inherited, which will again inherit the access rights set in the
Default Provider Access Level. Any new Tag Providers will automatically get added to the Security Policy with Inherited access
rights. The Trust Remote Roles setting will allow similarly named roles on other Gateways to access Tags with role specific security
on them.

This feature is new in Ignition version 8.0.3

Click here to check out the other new features
The Impersonation Role Name field allows you to specify a role name to use when writing to a Tag from an incoming Gateway
Network connection (from the selected Zone). Note that you must use this role if you are configuring Tag Security.
Default Security Zone

While the Default zone may not have a custom Security Policy defined, it does default to not include any notification pipelines, allow alarm
acknowledgment, query only history access, and read only Tag access. This means that if a remote Tag Provider is setup on a remote
Gateway, and the local Gateway has not changed the default security settings, the remote Gateway will have read only access to the
Tag History Provider. This can be changed by editing the Default zone's Security Policy to fit a different preference, or creating new Security
Zones with custom security policies. Once a Security Policy has been defined on a zone, it will automatically jump to the top of the list. A new
option will also become available that will clear the policy from the zone.
Setting Zone Priority

Once a Security Policy has been defined for two or more zones, a new option appears on the Service Security page to move the zones up
and down the list. This allows a priority to be set on the Security Zones, since a connection can apply to multiple zones. For example, say
Zone 2 dictates that all requests coming from a range of IP addresses have query only history access, and read write access to Tags. Zone 1
includes specific Gateways, one of which is also contained in Zone 2, that will have query and storage history access and read write edit
access to Tags. When a request comes in from a connection, it first determines which Security Zones it belongs to. The request then starts at
the top of the Service Security list and goes down until it finds the first zone that it is in, and uses the access rights of that zone. In our
example, we want to make sure Zone 1 is above Zone 2, so that the Gateway that is in both Zone 1 and Zone 2 gets the full access rights
afforded to it by the Security Policy of Zone 1 instead of getting the limited access rights from Zone 2.

Related Topics ...

Security in Vision
Gateway Common Tasks

User Schedules

Schedules
Schedules define the times of users on-call availability and unavailability. For example, the Always
schedule is a schedule that is active 24/7. You can set a schedule for each user in the alarm
On this page
notification system. The notification messages are then sent only to those users with an active
schedule. When a message reaches a notification block in a pipeline, that block's on-call roster is ...
used to find the users with active schedules so they can be notified.
Schedules
There are also a number of system functions that allow you to create, read, edit, and delete To Define a New
schedules or holidays from a user source using scripting. (i.e., system.user.addSchedule, system.u Schedule
ser.getHoliday, etc.,). To learn what system functions are available for user scheduling and holiday Managing User
scripting, refer to the Scripting Functions in the Appendix. Schedules from
the Vision Client
Using Schedules
To Define a New Schedule for Alarm
Notification
1. Go to the Config section of the Gateway. Using Schedules
for Restricting
2. Choose Alarming > Schedules from the menu on the left. Login
The Schedule Management page is displayed. Here you can see an Always and an
Example schedule.
The Always Schedule is a built-in schedule that is always available: 24x7x365.
 2.

The Example Schedule is an example of a M-F 8am-5pm schedule with a lunch break.
Click on the edit to see the detailed settings.

3. Click on Create new Schedule.

4. Choose a Standard or Composite schedule and click Next.

The Standard schedule is defined by hours of operation on each day, with repeating
options.
User Schedules
The Composite schedule is defined by the combining of two other schedules.
Watch the Video
5. On the New Schedule page, enter a Name, the Schedule to be notified, and any Repeati
ng options, then click Add Schedule.
Each schedule is defined by which days of the week it is active for, and during what times.
Additionally, you can define repeating patterns that repeat either weekly or daily, and even
plug in holidays. When defining time ranges, use 24-hour format and commas to break up
different spans. For example, to if you want the schedule to be active from 8am-5pm with a
45 minute break starting at noon, you'd use: 8:00-12:00, 12:45-17:00.

Schedule and
Holiday Scripting
Watch the Video

Managing User Schedules from the Vision Client

There are a few ways to manage user schedules from the Vision client. The first is to use the Schedule Management component on a
window. This component allows you to quickly and easily manage the schedules from the Vision client.

For more granular control, you may instead want to use scripting to manage the schedules. This may offer a more granular control at the click
of a button.
 # This code creates a new schedule by using an old schedule but setting observe holidays to true.
mySchedule = system.user.getSchedule("WeeklySchedule")
if mySchedule != None and mySchedule.getType() == "basic schedule":
mySchedule.setObserveHolidays(True)
mySchedule.setName("NewWeeklySchedule")
system.user.addSchedule(mySchedule)

Using Schedules for Alarm Notification

The alarm notification system always uses the Schedules. When an alarm notification pipeline reaches a notification block, it looks at all of the
users defined in that block's configured on-call roster. Only those users whose schedules are currently active will be notified. This way, you
can group people in call rosters by role, not by shift. For example, suppose you have alarms that should be sent to all supervisors. You can
put all of the supervisors in one call roster, and the scheduling system will automatically only notify those supervisors who are on-shift when
the alarm goes active.

Using Schedules for Restricting Login

You can use Schedules to restrict users' ability to log in. To enable this, select the Schedule Restricted option on the user source in
question. That user source will then reject logins for users whose schedule is inactive, even if their credentials were accurate.

Related Topics ...

On-Call Rosters
User Notifications

Project Security in Designer and Gateway

When several users are all working on the same project, managing changes to the project can become cumbersome. By default, all users
with Designer access can modify, delete, save, and publish all resources available in the Designer. In some situations, it is desirable to limit
what each user can do in the Designer. Ignition has several built-in Designer restriction methods to help in these scenarios.

Designer Project Permissions

Actions such as publishing, viewing, saving, deleting, and editing of project resources are restricted
to users who have sufficient roles to do so. Editing of the these required roles is done in the
On this page
permissions section of the Project Properties dialog in the Designer. If required roles are not set for
an action, then all users with Designer access can perform the action. ...
Designer Project
Role Changes.. Permissions
The Designer does not poll for role changes, so if a user who is currently logged into the Controlling
Designer has their roles changed, they will need to re-launch the Designer for the new Project Edits by
role(s) to take effect. Role
Protecting Project
Resources
Protecting Global
Controlling Project Edits by Role Resources
Gateway
You can control who gets to login to a project by assigning roles and giving permissions to those Permissions
roles in the Required Designer Roles property which you set up in the Designer. To Lock Global
Resources on the
1. In the Designer, from the menubar, choose Project > Properties. Gateway
Restrict Project
2. Go to the Project > Permissions area, and under the Required Designer Roles, enter the Creation
appropriate roles next to each project level restriction, as required.
In the text boxes on this page, enter a comma-separated list of role names that
are required to access the project. As you start typing, matching role names will pop up.
 2.

Project Permissions
Watch the Video

The following table describes each of these five options:

Option Affect

Publish User must have at least one of these

roles to publish the project.

View User must have at least one of these

roles to view the project in the Designer.

Save User must have at least one of these

roles to save the project.

Delete User must have at least one of these

roles to delete the project.

Protect Resources User must have at least one of these

roles to access protected resources.

Protecting Project Resources

You can lock individual project resources from inside Designer by opening the Project Browser,
and right clicking on any of the objects that you want to lock in. Select the Protect option to protect
it. Once it's protected, it cannot be changed except by someone that has the permission to
unprotect it, and modify it.

Locking Project
Resources
Watch the Video

Protected resources are global or project resources that can only be edited by select users with the
required roles. These roles are required to protect resources from being edited in the Designer, and
do not apply to the clients. This means you can prevent a resource from being edited by other
users who have Designer access. It is often used in scenarios where development work is finished
on a window or object, and no further changes should be made to it. Other objects like Vision
Templates or Alarm Pipelines are often protected so they may be used, but not modified.

Users without a required role will see the following message in the Designer when attempting to
open a protected resource:

Users with a required role are allowed to modify the resource, but a message will appear informing
them that the resource is protected, and will be asked how to proceed:

Additionally, a lock

icon will appear on the resource informing users that it is protected. An example can be seen on
the 'Audit Events' window below:

To remove the protection, simply right click the object and select the Protect option to unprotect it.

Protecting Global Resources

Just like protecting project resources, you can protect individual global resources using the Protect
option. Global Resources can be locked in two different locations: in the Designer and on the
Gateway Webpage using the Global Resource Protection property as described earlier on this
page.

Locking Global
To Lock Global Resources in Designer
Resources
1. Go to the Alarm Notification Pipeline section of your Project Browser.
Watch the Video
2. Right click on one of your Alarm Notification Pipelines, and select Protect. This example
uses the Email pipeline object, but any object can be protected. To remove the protection,
simply right click the object and select the Protect option again to unprotect it. Once an
object is protected, you will see that you can still modify it.
 2.

Gateway Permissions

To Lock Global Resources on the Gateway

Before assigning any roles in the Global Resource Protection property, you need to keep in mind all
the different roles in your project, what level of access they need in each area of the project, and
that it agrees with your security policy. Typically, the Administrator, identifies what role is required,
and the user(s) who have that role so the proper protection is placed on global resource objects.

1. To block certain users, a role requirement must be added on the Gateway Webpage under
the Config section System > Gateway Settings, otherwise, other users who have
Designer access, can edit a protected resource.
Scroll down to the Global Resource Protection option.

Add or modify the roles in the Global Resource Protection field to protect the global
resources. In this example, you can enter multiple role names separated by commas.
Once you enter the required roles, anyone without one of these roles will not be able to
modify protected objects. Click Save Changes.

Global Resource Protection supersedes the individual locks applied in the

Designer
The roles you identify in the Global Resource Protection property to protect or
modify any of the protected global resources (i.e., alarm pipeline, scripts, etc.),
will supersede all of the individual locks that were applied in the Designer.

Restrict Project Creation

The ability to create new projects can also be restricted by role. In cases where multiple users have
Designer access, this property can prevent each user from creating a large amount of 'test' or
'sandbox' projects. This is ideal for production systems where you don’t want other users creating
new projects.

The Create Project Role(s) property can allow users with one of the specified roles to create new
projects on the Gateway. To grant permission to create new projects in Designer, you must assign
a role in the Create Project Roles(s) property of Gateway Settings. On the Config section of the Ga
teway, go to System > Gateway Settings, and scroll down to Create Project Role(s) property. E
nter a role that users should have to create a new project, and click Save Changes.

Using SSL

What is SSL?
Secure Socket Layer (SSL) is a widely used security protocol for data as it goes across a network
On this page
or the internet. SSL and TLS are protocols that secure the network traffic of the Gateway. This
means using HTTPS for all traffic between the Designer, Vision Clients, and Perspective Sessions ...
when connecting to the Gateway. It is highly recommended that SSL / TLS is always used as it will
help protect against your data being vulnerable. What is SSL?
Enabling SSL
Turn on SSL
Enabling SSL Adding an SSL
Certificate
To enhance security in Ignition, you may opt to enable SSL encryption. This will affect Get a Certificate
all communication to and from the Gateway that is done over the HTTP protocol. This includes not Signing Request
only browsers interacting with the Gateway's web interface, but all Vision Client communication as Install an SSL
well. Turning on SSL will encrypt all data sent over HTTP. This protects your installation from Certificate
anyone "snooping" the data as it passes over the network. This may be important if data
transferred between the Gateway and Clients is sensitive in nature. This also helps to thwart a sec
urity vulnerability known as "session hijacking".

Turn on SSL

1. Go to the Config section of the Gateway.

2. Choose Networking> Web Server from the menus on the left.

3. Select the checkbox for Force Secure Redirect, and click the Save button at the bottom of the page.
After SSL is enabled, all Clients, Designers, and web browsers are redirected to the SSL port if they try to use the standard HTTP port. By
default, the SSL port is 8043. You can change it here to another port like the standard SSL port of 443. If you are using a firewall, make sure
to open the appropriate ports.

Adding an SSL Certificate

Ignition supports using SSL communications to the Gateway Webpage as well as Client/Designer communication with the Gateway. It is
highly recommended that you purchase an SSL certificate from a certificate authority if you turn this feature on. The procedures for how to
install a genuine SSL Certificate are below.

When you turn on SSL in Ignition, the web browser uses what is called a "self-signed" certificate. This gives you the encryption benefits of
SSL, but not the identity validation, and it isn't a "real" certificate. This is why a web browser will display nasty warnings to users that they
shouldn't trust the website.

We are not able to ship a real certificate with Ignition because SSL certificates have to be purchased individually from a certificate authority,
such as Verisign, GoDaddy, Comodo, or any others.

After you have added an SSL certificate, the keystore will automatically refresh every 15 minutes. You can disable this in the
ignition.conf file by altering the ignition.ssl.refresh entry (Set to 0 to not refresh).

Get a Certificate Signing Request

Since SSL/TLS requires the installation of an SSL certificate, filling out the form below will generate a certificate signing request (CSR) to
provide to a certificate authority. It is the first step required in getting an SSL certificate from a trusted Certificate Authority (CA), which is why
details such as Organization and Location are being collected.

1. Go to the Config tab of the Gateway Webpage and choose Networking > Web Server.

2. You'll see a warning message indicating that SSL/TLS is not enabled. Click on the Click here link.
 3. Click on the I don't have all the items above button. The Create Certificate screen is displayed.
4. Fill in the required fields on the screen, then click the Generate Certificate Signing Request button. This can be brought to a
Certificate Authority.

Basic Details

Field Definition

Common Name Full DNS name (required). This is typically what you type in your browser URL bar in order to navigate to
this gateway, for example: yourdomain.com

Organization Name of company (required). For example: Inductive Automation.

Name

Organization Department or section (required). For example: Engineering.

Department

Email Email address. For example: [email protected].

Country Typically an ISO 3166 2 character code (required). For example: US.

State / Province State, province or region, for example: California.

Locality (City) Name of city. For example: Folsom

Street Street number and street name. For example: 90 Parkshore Dr

Postal Code Postal Code Example: 95630

Key Type The algorithm of the key pair which will be generated for the self signed certificate. Options are RSA or EC.
Recommended: RSA

Key Size The strength of the generated Key. Recommended: 2048 bits

Expires in The number of days the generated Certificate will be valid. Only applies to the self-signed certificate.

Subject Alternative Names

Field Definition

IP Addresses The IP addresses of all the servers you plan on installing the certificate. Click the Add button for each
additional IP address.

DNS Names DNS names which map to the list of IP addresses above.Click the Add button for each additional IP
address.

Install an SSL Certificate

Once you have an SSL certificate, it needs to be added to Ignition.

1. Go to the Config tab of the Gateway Webpage and choose Networking > Web Server.
2. You'll see a warning message indicating that SSL/TLS is not enabled. Click on the Click here link.
3. The Setup SSL/TLS screen is displayed. Review the following list:
Private Key
Certificate Signed By A Certificate Authority (CA)
Any Intermediate CA Certificates (Provided by your CA)
Root CA Certificate (Provided by your CA)

4. If you have the items, click on the I have all the items above button. If you don't have all the items, click on the I don't have all the
4.

items above button, and follow the previous procedure, To Get an SSL Certificate from a CA.

5. The Certificate Wizard is displayed. The first step is to import your private key in one of the following three ways.
Drag and Drop your certificate from your computer onto the screen.
Click anywhere on the grey box to browse for the private key.
Click Manually enter data button to type in the private key information
6. If the private key is encrypted, click the checkbox to enable a password for this certificate and enter the password in the field. Click
Continue.
7. The next step is to import the server certificate. This is the The DER or PEM encoded X.509 SSL Certificate that Ignition will use for
SSL / TLS. Drag and drop the certificate file, browse for it, or manually enter the data.
8. The next step is to import the certificate chain. This gives you the Intermediate CA Certificate. Drag and drop the certificate file or
bundle, browse for it, or manually enter the data.
You'll see a message that the Intermediate CA Certificate was successfully uploaded.
9. Finally, import the root CA certificate: Drag and drop the certificate file, browse for it, or manually enter the data. You'll see a
message that the Root CA Certificate was successfully uploaded.

Editor notes are only visible to logged in users

Why does the description for the previous certificate, the intermediate one, change to
say Root certificate now? - This is a question for Dev., probably a bug. The text is a
duplicate of the step 4 too.This is a bug. Alex Lu submitted FB14677 for it.
10. Click the Continue button.

11. You'll see a confirmation message that the certificate is installed and SSL/TLS is enabled.
 12. If you have a redundant installation, you'll need to repeat this procedure on your backup server and buy a second certificate for it.

Related Topics ...

Security
Security in Perspective
Security in Vision

Audit Profiles

Using Auditing
Audit Profiles cause Ignition to record details about specific events that occurred. Audit Profiles are
simple to set-up, and immediately start to record events. By default, only Tag writes, SQL
On this page
UPDATE, SQL INSERT, and SQL DELETE statements are recorded. This allows you to keep track
of which user wrote to which Tag, or modified which table. Furthermore, a time-stamp is recorded, ...
so you can easily track the changes and outline an order of events.
Using Auditing
To Create an
To Create an Audit Profile Audit Profile
Auditing Project
Events
1. Go to the Config section of the Gateway. To Assign an
2. Choose Security > Auditing from the menu on the left. Audit Profile to a
3. The Audit Profiles page is displayed. Project
4. Click the Create a new Audit Profile link. To View
5. Select Database and click Next. Information in an
6. Enter the Name of the audit log and the Retention time. Audit Log
7. Under the Database Settings, select the Database where the table will be stored, select Audit Table
the Auto Create check box, and enter the desired Table Name. Definition
8. Click Create New Audit Profile. Custom Auditing
 8.

Once some changes have been made to a Tag or a Database table, Ignition will begin recording.

Auditing Project Events

A project can be assigned to an Audit Profile. Once configured, Ignition will track changes made to
the Designer, as well as keep track of when users logged in or logged out of a client. Additionally,
the hostname of the computer used will be recorded.

To Assign an Audit Profile to a Project Project Auditing

1. Go to the Designer, open the project that you want to enable auditing on, and go to Proje Watch the Video
ct > Properties.
2. Go to the General section, select the Enable Auditing check box, and select your Audit
Profile from the drop-down menu. The audit profile is used to record audit actions for your
project. If the new audit profile does not show up, click Refresh.
3. Click OK.
4. Save your Project.
To View Information in an Audit Log

There are a few ways to view audit information: using a Table component, interface on the
Gateway, or the Database Query Browser. Here is one example of viewing an Audit Log using the
Database Query Browser.

1. Go to Tools > Database Query Browser.

2. Under the Schema area, double click on a table, and it will expand the query in the
Database Query Browser area.
3. Click Execute, and all the audit log data will be displayed in the Resultset1 area.

Refer to the Database Query Browser to learn more about how it works.

Audit Table Definition

The following table describes the audit table as it exist in the database:

Column Name Description

 AUDIT_EVENTS_ID The id of the row.

ACTION Brief description of the action.

ACTION_TARGET The target of the action.

ACTION_VALUE The value acted upon the action target.

ACTOR The logged in user when the action occurred or a description of the system that generated the action.

ACTOR_HOST The host computer where the action occurred.

EVENT_TIMESTAMP The time when the action occurred.

ORIGINATING_CONTEXT A numerical description of the origin of the originating system. gateway = 1, designer = 2, client = 4

ORIGINATING_SYSTEM The name of the project or system where this action occurred.

STATUS_CODE The OPC quality code where 192 signifies success. 0 signifies bad or failure.

Custom Auditing

The Audit Table is simply a database table, so custom events can be logged to the table. This is commonly done through scripting events. In
most cases, users will log certain button presses and event values by adding just several lines of code.

Related Topics ...

Database Query Browser

Audit Log Display

In This Section ...

Alarm Notification Auditing

Alarm Notification profiles can be set to store information in an Audit Profile.

On this page
How to Store Alarm Notifications in an Audit Profile

Once you have an audit profile created in Ignition, you can configure your Alarm Notification Profile
...
to start using it. How to Store Alarm
Notifications in an
1. Go to the Config section of the Gateway. Audit Profile

2. Choose Alarming > Notification from the menu on the left.

The Alarm Notification Profiles page is displayed.

3. Edit the appropriate notification profile by clicking the edit link.

Alarm Notification
Auditing
Watch the Video

4. The Edit Alarm Notification Profile page is displayed.

Scroll down to the Auditing section, and select an Audit Profile from the drop-down
 4.

menu.
Click Save Changes, and Ignition will automatically begin storing information.

Now that the Alarm Notification Profile is storing data into the Audit system, you have a complete log of all alarm emails and
acknowledgements that you can review.
See Audit Log Display for more info on how to retrieve information from the Audit Log.

Related Topics ...

Alarm Notification
Database Connections
Audit Log Display

Audit Log Display

Audit profiles store information into a database, you can then display that information and see what
information is stored.

Database table mutations (update, delete, insert) On this page

Stored Procedure calls from scripting
Vision login/logout/failed login
Designer login/logout ...
Saving a project in the Designer
Tag writes To Access the Audit
Tag Edit Log with Table
Tag Move Functions
Tag Rename To Access the Audit
Report Executions Log using the
Notification Send Attempts (seems to be all of the notification types) Database Query
Publishing a project Browser
To Access the Audit
There are a few ways to view audit log information: using a Table component, Database Query Log on the Gateway
Browser, or the interface on the Gateway.

View Audit
Information
Watch the Video
To Access the Audit Log with Table Functions

Since Ignition makes accessing data from databases seamless, it is possible to bind a data property of a table directly to database table.
Alternatively, it is possible to access the contents of the audit log with table functions.

Once you have an Audit Log setup and attached to a project, you can go back to that project and see what information is in that audit log.
This example uses the Table Functions to extract data from the Audit Log.

1. In Designer, drag a Table component on to a window.

2. In the Property Editor, click on the binding icon from the table's Data property.
The Property Binding window is displayed.

3. Select the Functions Binding Type.

4. Select Functions from the various binding options.

a. Binding Function, select the Audit Log from the drop-down menu.
b. Audit Profile Name, select Audit or the name of your Audit Profile.
c. Start Date, enter the appropriate start date.
d. End Date, enter the appropriate end date.
e. Polling Mode, select Relative.
f. Select any other appropriate function options from the menu, and click OK.

5. The table will populate with all the information stored in the audit log based on the Table Functions you selected. You can use the Ta
ble Customizer to configure how you want the table to look by reorganizing and hiding columns, making columns sortable, assigning
meaningful headers, and much more.
To Access the Audit Log using the Database Query Browser

The Database Query Browser makes it easy to search your database tables to view audit information.

1. In the Designer under the Tools menubar, select Database Query Browser.
The Database Query Browser will open.

2. On the right side of Browser window under Schema, will be a list of tables from the currently selected database. Double click on the
audit_events table, and click Execute.
The data from the audit_events table will appear in the Resultset 1 tab.

Refer to the Database Query Browser to learn more about how it works.

To Access the Audit Log on the Gateway

Ignition provides a simple interface to view Audit Logs on the Gateway.

1. On the Gateway webpage in the Config section, scroll down to Security > Auditing.
2. The Audit Profile page will be displayed. Select the Audit Profile where your information is stored, and click More > view log.
 3. Choose the parameter settings if you're looking for something specific, otherwise, enter a Start Date and End Date, and click Searc
h.

Related Topics ...

Scripting
Database Query Browser
Table Customizer
Security

Common Security Tasks

This section contains examples for items we identified as "common" tasks. It includes methods and
examples of Security features that many users are looking to utilize when first starting out with
Ignition. Additionally, this section attempts to clarify some of the Security options available that can On this page
be used to protect your applications and data.

The examples in this section are self-contained explanations that may touch upon many other ...
areas of Ignition. While they are typically focused on a single goal or end result, they can easily be
expanded or modified after the fact. In essence, they serve as a great starting point for users new Configuring IdPs
to Ignition, as well as experienced users that need to get acquainted with a new or unfamiliar Troubleshooting
feature. IdPs

Below is a list of common tasks related to the security features and setting up security for your
Ignition system.
 Configuring IdPs
With the introduction of Ignition 8 and Perspective 8.0, we implemented several new features called Security Levels and Identity Providers
(IdPs) that improve authentication and authorization to the Ignition system. There are several types of Identity Providers (IdPs) such as
Ignition, OpenID Connect 1.0, and Security Assertion Markup Language (SAML). An IdP offers a way for users to log into Ignition using
credentials stored outside of Ignition as well as providing authentication services such as two-factor authentication (2FA). Security Levels,
similar to roles that are assigned to users, are defined in the Gateway and enable you to define a hierarchy for access inside a Perspective
Session. They provide a way for you to map roles from an IdP to Ignition roles.

The OpenID Connect 1.0 Example page will show you how to configure an external IdP that used OpenID Connect 1.0 with your Ignition
system.

Troubleshooting IdPs
On the Troubleshooting Identity Providers page, you will find a few helpful examples to help you diagnose and troubleshoot issues with
configuring IdPs. They typically include various scenarios that you may find yourself in, and what to do in those situations, as well as some
error messages that will be helpful in figuring out what is going wrong.

In This Section ...

OpenID Connect 1.0 Example

This section provides an example of how to connect an Identity Provider that is using the OpenID
Connect 1.0 protocol. This example uses the Okta IdP service. Your IdP vendor may differ and the
specific links will differ. On this page

Prerequisites ...
Prerequisites
Before you begin configuring Ignition there are some preliminary requirements that need to be done Configured IdP
outside of Ignition: Metadata File
Scope Data
A configured remote IdP (Okta in this example) Test Login
The metadata file specific to your IdP Credentials
The scope data specific to your IdP Configure Ignition
Login credentials to use as a test Gateway

Configured IdP

An IT department is usually the one to setup and configure a remote IdP. You need a configured remote IdP that is compatible with OpenID
Connect 1.0. protocol.

At minimum there needs to be an account set up with the IdP, users added to the IdP account, and applications added to the IdP.

Metadata File

You will need the metadata file specific to your IdP. This document defines how to communicate with the IdP. It is usually a web page that
allows the metadata file to be exported to a JSON file. Often it is a URL that ends with “.well-known/openid-configuration”.

You will need the URL link to this page or a JSON export of this page. For example, if your IdP user login URL is something like this:

https://dev-123456.oktapreview.com/login/login.htm

Then the metadata import URL may look like something like this:

https://dev-123456.oktapreview.com/.well-known/openid-configuration
Here is an example of part of a metadata file for Okta. Notice that the URL link has "/.well-known/openid-configuration" at the end and is very
similar to the login URL. It is recommended to use the URL specific to your IdP. Your IT department may choose to export this JSON file of
this page and provide it to you. Either option will work.

It is recommended to use the URL specific to your IdP. Your IT dept. may choose to export this JSON file of this page and provide
it to you. Either option will work.

Scope Data

When a user is verified by the IdP a lot of the user specific data is not returned in the response file by default (i.e., username, email,
firstname, lastname, etc). This user specific data is called the scope, and it can be returned if the Scope section of the Ignition Gateway is
configured. The list of available scope definitions may be available from your IT deptartmeny or available from the developer documentation
of the IdP you are using.

For this Okta example, the scope data is in the developer notes at https://developer.okta.com/docs/api/resources/oidc#scope-dependent-clai
ms-not-always-returned

Test Login Credentials

You need an account specific to the IdP for testing purposes (Okta in this example). To test and verify the IdP account, login to your IdP. For
our example, the Okta login page is shown here:
You should now have a IdP credentials to test with, a metaData URL or metaData JSON file, and a list of scope parameters to reference for
your project. The next step is to configure Ignition to communicate with your IdP.

Configure Ignition Gateway

1. On the Gateway Webpage, click on the Config tab. You will need to log in if you aren't already.

2.
2. Under the Security section, click on Identity Providers. The Identity Providers screen is displayed. This screen will list all IdPs that
have been configured. You can filter by name or adjust the number of IdPs displayed per page in the view.

3. Click on the Create a New Identity Provider... link.

4. Select the OpenID Connect 1.0 option and press Next.

5. On the Basic Details screen, provide an Adapter Name. You can also add an Adapter Description if desired. The Provider Type
field will fill in automatically from the previous screen.
6. The next section is Import Provider Metadata. In the Import from URL section, enter in the URL from earlier that shows the
“.well-known/openid-configuration” link specific to your IdP. You can also import a file below if it was provided by your IT department.
7. Click on the Import button.

8. Ignition will now generate a URI redirect address for your Ignition server. It is listed just below the “Import Provider Metadata” area of
the configuration page.
In our example it is http://10.10.115.3:8088/data/federate/callback/oidc. You need to provide this URI to your IdP (usually this means
giving it to your IT department).

The URI should be a web address that is accessible from the IdP server.

9. Once you've giving your IT department the redirect address, they can add your Ignition server as an application to the IdP.
Once they have done this, they can provide you with a “Client ID” and “Client Secret”. This is needed for the Ignition Gateway to
properly communicate with the IdP.
 9.

The IdP can use the same redirect address for the Login, Logout, and Initiate Login.

10. The next section is Provider Configuration. Most of the fields below should now be filled in when you imported the IdP Metadata. Fill
in the Client ID and Client Secret fields with the information obtained from your IdP (or IT department). If you don't know them yet,
you can put in bogus values for now and edit them later once the correct values are provided to you.

11. Providing scope is optional. These fields are specific to your IdP, and you may need to find the developer documentation specific to
your IdP.

Enter "email" in the Scope field and press the Add button. Repeat for each scope you want returned.
For our example, the list of available scopes is in the Okta developer documentation: https://developer.okta.com/docs/api/resources/
oidc#scope-dependent-claims-not-always-returned.

12. Press the Save button at the bottom right of the page. You'll see a confirmation message.
13. The next step is to perform a test login. From the Identity Providers screen, select More and then Test Login.

14. You will be re-directed to the Okta login. Enter in your test login credentials and click the Sign In button.
14.

15. If the login is successful, you will be returned to the Identity Provider Test Login screen. The returned results will be displayed in the
Results section.

In this example, we did not add the username or email to our scope. Thus they have not been returned.
 Editor notes are only visible to logged in users
Admin Username/password for Training's
OKTA instance are available through
LastPass. See Bobby.
OKTA USER LOGIN INFO:
Okta Login Page: https://dev-997763.oktap
review.com/login/login.htm
Okta ia User: [email protected]
Okta ia Pass: P4ssw0rd

Okta Metadata Definition: https://dev-997

763.oktapreview.com/.well-known/openid-co
nfiguration
Okta Scope Definition: https://developer.
okta.com/docs/api/resources/oidc#scope-de
pendent-claims-not-always-returned

Okta Client ID: 0oaifp0dlntvhYxaX0h7

Okta Client Secret:
ZvMy_gt-XqiILB4qQH6AacpsEqA_M2Y8gwkvoj3Q

SAML Example

This section provides an example of how to connect an Identity Provider that is using the SAML
protocol. This example uses the Okta IdP service. Your IdP vendor may differ and the specific links
will differ. On this page

Prerequisites ...
Prerequisites
Before you begin configuring Ignition there are some preliminary requirements that need to be done Configured IdP
outside of Ignition: Metadata File
Test Login
A configured remote IdP (Okta in this example) Credentials
The metadata file specific to your IdP Configure Ignition
The scope data specific to your IdP Gateway
Login credentials to use as a test

Configured IdP

An IT department is usually the one to setup and configure a remote IdP. You need a configured remote IdP that is compatible with SAML
protocol.

At minimum there needs to be an account set up with the IdP, users added to the IdP account, and applications added to the IdP.

Metadata File
You will need the metadata file specific to your IdP. This document defines how to communicate with the IdP. It is usually a web page that
allows the metadata file to be exported to an XML file.

You will need the URL link to this page or an XML export of this page. For example, the metadata import URL may look like something like
this:

https://dev-123456.okta.com/app/esdfsdf7886sd6723hjkdf/sso/saml/metadata

Here is an example of part of a metadata file for Okta. Notice that file is XML format. You can use the file or the URL to automatically import
the configuration into Ignition. Otherwise it will need to be manually typed in.

Test Login Credentials

You need an account specific to the IdP for testing purposes (Okta in this example). To test and verify the IdP account, login to your IdP. For
our example, the Okta login page is shown here:
You should now have a IdP credentials to test with, a metadata URL or metadata XML file. The next step is to configure Ignition to
communicate with your IdP.

Configure Ignition Gateway

1. On the Gateway Webpage, click on the Config tab. You will need to log in if you aren't already.
2. Under the Security section, click on Identity Providers. The Identity Providers screen is displayed. This screen will list all IdPs that
have been configured. You can filter by name or adjust the number of IdPs displayed per page in the view.

3. Click on the Create a New Identity Provider... link.

4. Select the Security Assertion Markup Language 2.0 option and press Next.

5. On the Basic Details screen, provide an Adapter Name. You can also add an Adapter Description if desired. The Provider Type
field will fill in automatically from the previous screen.
 5.

6. The next section is Import Provider Metadata. In the Import from URL section, enter in the URL from earlier specific to your
IdP. You can also import a file below if it was provided by your IT department.
7. Click on the Import button.

8. Ignition will now generate a URI redirect address for your Ignition server. It is listed just below the “Import Provider Metadata” area of
the configuration page.
In our example it is http://10.10.110.86:8088/data/federate/callback/saml. You need to provide this URI to your IdP (usually this
means giving it to your IT department).

The URI should be a web address that is accessible from the IdP server.

9. Once you have given your IT department the redirect address, they can add your Ignition server as an application to the IdP.

The IdP can use the same redirect address for the Login, Logout, and Initiate Login.

10. The next section is Provider Configuration. Most of the fields below should now be filled in when you imported the IdP Metadata.
10.

11. Press the Save button at the bottom right of the page. You'll see a confirmation message.
12. The next step is to perform a test login. From the Identity Providers screen, select More and then Test Login.

13. You will be re-directed to the Okta login. Enter in your test login credentials and click the Sign In button.
 14. If the login is successful, you will be returned to the Identity Provider Test Login screen. The returned results will be displayed in the
Results section.

Troubleshooting Identity Providers

Editor notes are only visible to logged in users

QA items:

Logout URL seems to have no effect

JSON Web Key seems to have no effect

This Troubleshooting section has a compilation of examples to help you diagnose and troubleshoot
issues with configuring IdPs.

The Save Button Is not Selectable

All required fields must be entered on the Identity Providers screen before Save can be selected.
Required fields have an asterisk (*) next to their name.

If you are waiting for values for the ClientID and Client Secret fields, you can enter fake
values and return when you have the correct value.
After Importing Metadata from a File, Values Did not Auto Populate

1. Verify that import file is JSON format.

On this page
2. Verify that the import URL is valid.
3. Re-import the file. ...
The Save Button Is
Login Testing: IdP Login Page Does not Appear not Selectable
After Importing
1. Confirm that the values in Client ID and Client Secret fields are correct. These come Metadata from a
from the IdP when your Ignition Gateway is added as an application. File, Values Did not
2. Check all other configuration settings. Auto Populate
Login Testing: IdP
Login Page Does
not Appear
Login Testing: The
IdP login Is
Displayed but the
Login Attempt Fails
Login Testing: The
IdP Login Accepts
the User but the IDP
Redirect Fails (HTTP
ERROR 500)
Login Testing: The
Test Is Successful,
but Results Do not
Show Useful data
(i.e., user name,
eMail)
Login Testing:
Revised User
Attributes Are not
Shown in the
Results of a
Successful Test
You Are not
Re-directed Back to
Ignition after a
Successful IdP Login

Login Testing: The IdP login Is Displayed but the Login Attempt Fails

This issue is outside of Ignition. Check with your IT department and verify the login credentials (username and password) for your IdP.
Login Testing: The IdP Login Accepts the User but the IDP Redirect Fails (HTTP ERROR 500)

1. Go to Settings for you IdP.

2. Verify the setting for Supported ID Token Signing Algorithm Values.

3. If the URL for the IdP's metadata is available, try re-importing it.
4. Verify and re-enter the Client Id and Client Secret.
5. Verify the Token URL. Then re-import the IdP's metadata.
6. Verify the JSON web keys URL. (Default is to leave the check box checked.) Then re-import the IdP's metadata.
7. Verify the Issuer URL, then re-import the IdP's metadata.
Login Testing: The Test Is Successful, but Results Do not Show Useful data (i.e., user name, eMail)

1. Go to settings for you IdP.

2. Add the desired fields to the Scope section. You may have to reference the developers documentation Scope document

3. Click Save.
4. Repeat the Login test.

Login Testing: Revised User Attributes Are not Shown in the Results of a Successful Test

1. Go to settings for you IdP.

2. Add the desired fields to the Scope section.
3. Click Save.
4. Repeat the Login test.

You Are not Re-directed Back to Ignition after a Successful IdP Login

1. Verify the Adapter Configuration: Authorization URL.

2. Re-import the IdP's metadata.