Skip to main content
Version: 8.1

Configuring Identity Providers

Registering the Ignition Gateway​

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.

note

The same redirect URI is used for login and logout.

OpenID Connect Providers (OP)​

OpenID Connect Providers
http://yourGatewayAddress:Port/data/federate/callback/oidc

SAML Providers​

SAML Providers
http://yourGatewayAddress:Port/data/federate/callback/saml

Secure Integration with IdPs​

You should always use the secure versions of those redirect URIs (https) in production environments. To do this you must enable SSL/TLS in Ignition and install a valid certificate. This is the best practice for maintaining a secure integration with third party Identity Providers.

Configure an Identity Provider​

Inductive University

Configuring Identity Providers

Watch the video

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 NameDescription
Provider NameThe name of the adapter. Adapter names must be unique, so no two adapters on the same Gateway may have the same name.

The naming conventions for IdPs are as follows:
  • IdP names must begin with an underscore or alpha character.
  • The remaining characters in the name must be either underscores or alphanumeric.
  • IdP names are not case sensitive.
Provider DescriptionA description of the provider.
Provider TypeThe type of Identity Provider. The value for this field comes from the previous screen. It cannot be changed here.

Ignition Identity Provider​

The Ignition Identity Provider has the following properties:

Property NameDescription
User SourceThe User Source for this IdP. In order to properly authenticate users, the Ignition Identity Provider must be able to query the list of users from the underlying user source profile.
Session Inactivity Timeout
New in 8.1.0
The number of minutes which must elapse before expiring a session due to user inactivity. Sessions will not timeout if set to any number less than or equal to zero.
Session Expiration
New in 8.1.0
The maximum number of minutes a session may exist before it is expired. Sessions will not have a max lifetime if set to any number less than or equal to zero.
Remember Me Expiration
New in 8.1.0
The maximum number of hours a user will be remembered if they elect to be remembered. Remember Me is disabled when this value is set to any number less than or equal to zero. For more information on this option, see the Remember Me section below.
Authentication MethodsYou can opt into Badge based authentication for the IdP by enabling the β€œBadge” Authentication Method. The β€œDefault” radio button determines which option users first see when attempting to authenticate against the IdP.
Badge SecretChoose whether or not the user is required to enter a secret (password) along with their badge scan. Additional option can be checked to require the user to enter their password in addition to scanning their badge.

Badge (RFID) Settings​

Property NameDescriptionRequired?
Badge SecretChoose whether or not the user is required to enter a secret (password) along with their badge scan. Check to require the user to enter their password in addition to scanning their badge. Default is false (not checked).Yes

Built-In Attributes​

The following attributes are available in the Ignition IdP.

AttributeTypeDescriptionExample
auth_timeDateRepresents the time the user last authenticated.
// Check if it has been within
// 15 minutes since the last
// authentication attempt
dateDiff({idp-attributes:auth_time},
now(), "minutes") <= 15
challengedBooleanSignifies if the user provided credentials at the last login.

If true, then the user was asked to re-validate their credentials the last time they attempted to login.

If false, then they were not challenged to re-validate their credentials during the last login attempt. This can happen when a login request was made after a user was already authenticated. For example, if a user was already authenticated in a Perspective Session, and a separate call to system.perspective.login function was made with the forceAuth parameter set to false, meaning the user did not provide credentials during the last authentication challenge.
// Returns True or False,
// depending on whether or not the user
// provided credentials at the last login.
{idp-attributes:challenged}

Remember Me Example​

New in 8.1.0

The Remember Me option allows your login to be remembered for a set amount of time, even if you close your browser or restart your Gateway. When set, you will be remembered on this device for the specified number of hours without needed to log in again.

note

The following items will prevent this feature from working successfully:

  • Updating the Ignition Gateway to a new version will cause the device to "forget" the remembered user for some update versions, namely 8.1.2.

  • Checking the Always ask the IdP to re-authenticate users by default option for the General Gateway Security Settings > System Identity Provider setting will still require re-authentication regardless of Remember Me time allotments.

caution

This option is not recommended if you are using a public or shared device.

To set up Remember me, do the steps that follow:

  1. On the Gateway Webpage, click on the Config tab. Scroll down to Security > Identity Providers.

  2. For the Ignition Identity Provider you'd like to configure, click on the More option and choose Settings.

  3. On the Settings page, scroll down to the Provider Configuration section.

  4. For the Remember Me Expiration option, enter a value greater than zero. For this example, we set the option to two hours.

  5. Click Save to save your changes.

To enable Remember Me for your login, do a test login:

  1. On the Gateway Webpage, click on the Config tab. Scroll down to Security > Identity Providers.

  2. For the Ignition Identity Provider you'd like to configure, click on the More option and choose Test Login.

  3. Enter your password and select the Remember Me option.

  4. Click the Continue button.

  5. Your login will now be remembered for the amount of hours that were specified in the Gateway setting (in this example, it is 2 hours).

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 NameDescription
Import from URLURL to the OpenID Provider Configuration document. Typically, if the issuer is "https://example.org/foo" then the metadata URL would be "https://example.org/foo/.well-known/openid-configuration"
Import From FileFile must be a JSON document with the properties described in section 3 (OpenID Provider Metadata) of the OpenID 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. An example redirect URI would look like: http://hostname:port/data/federate/callback/oidc

Property NameDescription
Client IDThe client identifier registered within the identity provider. This value is provided the Identity Provider.
Client SecretThe client secret registered within the identity provider. This value is provided by the Identity Provider.
Authorization URLURL of the OP's OAuth 2.0 Authorization Endpoint.
Token URLURL of the OP's OAuth 2.0 Token Endpoint.
Logout URLOptional URL at the OP to which an RP can perform a redirect to request that the end user be logged out at the OP.
JSON Web Keys URLURL of the OP's JSON Web Key Set document.
Use Json Web Keys URIIf checked, then identity provider public keys will be automatically downloaded from given JSON Web Keys URL. New keys will be automatically fetched when the identity provider generates new keys. If unchecked, 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.
User Info URLOptional URL to retrieve UserInfo claims from the provider. Resulting claims are typically determined by the scopes listed under the Scope setting.
User Info HTTP Request Method
New in 8.1.27
The HTTP method used for sending User Info API requests to the User Info URL. Available options are POST and GET.
Authorization Response Mode
New in 8.1.43
Requests the authorization server to use the form_post mechanism for returning authorization response parameters from the authorization endpoint.
IssuerEntity that issues a set of claims.
Supported ID Token Signing Algorithm ValuesA list of the JSON Web Signature (JWS) signing algorithms supported by the OP for the ID Token to encode the claims in a JWT.
ScopeA list of scopes which will be sent for each auth request to the OP. Commonly used scopes would be email and profile but check your Identity Provider's documentation for more information.
JSON Web Key ConfigA list of signing key(s) the RP uses to validate signatures from the OP.

JSON Web Key Configuration​

Property NameDescription
Key TypeThe cryptographic algorithm family used with the key. Options are EC, RSA or oct.
Public Key UseThe intended use of the public key. Options are sig or eng.
Key OperationsThe operation(s) for which the key is intended to be used.
AlgorithmThe algorithm intended for use with the key.
Key IDUsed to match a specific key.
X.509 URLA URI that refers to a resource for an X.509 public key certificate or certificate chain. The identified 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 Certificate ChainThe "x5c" (X.509 certificate chain) parameter contains a chain of one or more PKIX certificates. Each entry must be a base64-encoded (Section 4 of RFC4648 -- not base64url-encoded) DER PKIX certificate value.
X.509 Certificate SHA-1 ThumbprintA base64url-encoded SHA-1 thumbprint (a.k.a. digest) of the DER encoding of an X.509 certificate.
X.509 Certificate SHA-256 ThumbprintA base64url-encoded SHA-256 thumbprint (a.k.a. digest) of the DER encoding of an X.509 certificate.

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

Key Type: EC​

Property NameDescription
crv (Curve)The cryptographic curve used with the key.
x (X Coordinate)The x coordinate for the Elliptic Curve point represented as the base64url encoding of the octet string representation of the coordinate.
y (Y Coordinate)The y coordinate for the Elliptic Curve point represented as the base64url encoding of the octet string representation of the coordinate.
d (ECC Private Key)The Elliptic Curve private key value represented as the base64url encoding of the octet string representation of the private key value.

Key Type: RSA​

Property NameDescription
n (Modulus)The modulus value for the RSA public key represented as a Base64urlUInt-encoded value.
e (Exponent)The exponent value for the RSA public key represented as a Base64urlUInt-encoded value.
d (Private Exponent)The private exponent value for the RSA public key represented as a Base64urlUInt-encoded value.
p (First Prime Factor)The first prime factor represented as a Base64urlUInt-encoded value.
q (Second Prime Factor)The second prime factor represented as a Base64urlUInt-encoded value.
dp (First Factor CRT Exponent)The Chinese Remainder Theorem (CRT) exponent of the first factor represented as a Base64urlUInt-encoded value.
dq (Second Factor CRT Exponent)The CRT exponent of the second factor represented as a Base64urlUInt-encoded value.
qi (First CRT Coefficient)The CRT coefficient of the second factor represented as a Base64urlUInt-encoded value.
oth (Other Primes Info)Information about any third and subsequent primes, should the exist. Each new Prime added will provide users with new Prime Factor, Factor CRT Exponent, and Factor CRT Coefficient properties, all of which are required.

Key Type: oct​

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

Import Provider Metadata for Redundant Backup​

New in 8.1.11

See the Import Provider MetaData for Redundant Backup section below.

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 have the opportunity to revise the imported data if needed before saving.

Property NameDescription
Import from URLURL to the SAML Identity Provider Metadata document.
Import From FileFile must be an XML document which conforms to the SAML 2.0 metadata schema described in 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.

New in 8.1.1

SAML IdPs may send the Base64-encoded SAML Response in a line-wrapped form (with new line characters such as \r and \n separating each line). As of release 8.1.1, Ignition's 2.0 SP implementation can handle both line-wrapped and non-line-wrappedBase64-encoded SAML responses.

Configuring the Provider​

Property NameDescription
IdP Entity IDThe Identity Provider's Entity ID.
SP Entity IDThe Service Provider's Entity ID. In this case, the Service Provider is the current Ignition Gateway.

By default, the Identity Provider will automatically generate the SP Entity ID based on the hostname that the client uses to connect to this Gateway. You may opt out of this setting and input a different SP Entity ID for the Gateway.
Assertion Consumer Service (ACS) BindingThe expected binding used by the Identity Provider when interacting with Ignition's Assertion Consumer Service.
Name ID FormatThe expected name ID format for subjects of assertions resulting from Authn Requests. Options are UNSPECIFIED, EMAIL_ADDRESS, X509_SUBJECT_NAME, WINDOWS_DOMAIN_QUALIFIED_NAME, KERBEROS_PRINCIPAL_NAME, ENTITY_IDENTIFIER, PERSISTENT_IDENTIFIER, TRANSIENT_IDENTIFIER.
Single Sign-On (SSO) Service URLThe Identity Provider's Single Sign-On (SSO) Service URL.
Single Sign-On (SSO) Service BindingThe binding Ignition will use for sending Authn Requests to the Identity Provider's Single Sign-On (SSO) Service.
Force AuthnCheck this box to force complying Identity Providers to authenticate the user each time instead of relying on a previous security context. See section 3.4.1 of saml-core-2.0-os for more details.
Validate Response SignaturesCheck this box to validate the signature of the response from the Identity Provider.
Validate Assertion SignaturesCheck this box if it is expected that assertions will be signed. Ignition will validate the signatures of each assertion.
IdP Metadata URL
New in 8.1.16
URL to the SAML Identity Provider Metadata document.

If Use IdP Metadata URL is checked, the identity provider's signature verifying keys and certificates will be automatically downloaded from the given metadata URL. New keys and certificates will be automatically fetched when the identity provider generates them. If unchecked, then the static set of keys and certificates (configured below) are used, so when the identity provider rotates them, they must be manually added to this configuration.
Signature Verifying KeysA list of signing key(s) that Ignition uses to validate signatures from the IdP.
Signature Verifying CertificatesA base64-encoded DER PKIX certificate value.

SAML Signature Verifying Key Configuration​

Property NameDescription
Key AlgorithmThe algorithm identifier for this signature verifying key. Options are DSA, RSA, or EC.
Key ValueA base64-encoded DER key value.

Import Provider Metadata for Redundant Backup​

New in 8.1.11

See the Import Provider Metadata for Redundant Backup section below.

Import Provider Metadata for Redundant Backup​

New in 8.1.11

Both OIDC and SAML provider configurations contain a section that allows you to define metadata which will be used by the backup gateway in a redundant Ignition configuration. When a backup gateway becomes the active node, it will interact with the identity provider via the backup settings. By default, the backup meta data will use the same configuration settings that the master node uses, unless "Provider Metadata for Redundant Backup" is set to false, in which case the IdP configuration will allow you to define settings for the backup gateway.

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 system. 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 configure an Identity Provider that is using the SAML protocol.