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

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 Name	Description
Provider Name	The 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 Description	A description of the provider.
Provider Type	The 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 Name	Description
User Source	The 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 Methods	You 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 Secret	Choose 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 Name	Description	Required?
Badge Secret	Choose 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.

Attribute	Type	Description	Example
auth_time	Date	Represents 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
challenged	Boolean	Signifies 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 Name	Description
Import from URL	URL 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 File	File 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 Name	Description
Client ID	The client identifier registered within the identity provider. This value is provided the Identity Provider.
Client Secret	The client secret registered within the identity provider. This value is provided by the Identity Provider.
Authorization URL	URL of the OP's OAuth 2.0 Authorization Endpoint.
Token URL	URL of the OP's OAuth 2.0 Token Endpoint.
Logout URL	Optional 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 URL	URL of the OP's JSON Web Key Set document.
Use Json Web Keys URI	If 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 URL	Optional 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.
Issuer	Entity that issues a set of claims.
Supported ID Token Signing Algorithm Values	A list of the JSON Web Signature (JWS) signing algorithms supported by the OP for the ID Token to encode the claims in a JWT.
Scope	A 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 Config	A list of signing key(s) the RP uses to validate signatures from the OP.

JSON Web Key Configuration

Property Name	Description
Key Type	The cryptographic algorithm family used with the key. Options are EC, RSA or oct.
Public Key Use	The intended use of the public key. Options are sig or eng.
Key Operations	The operation(s) for which the key is intended to be used.
Algorithm	The algorithm intended for use with the key.
Key ID	Used to match a specific key.
X.509 URL	A 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 Chain	The "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 Thumbprint	A base64url-encoded SHA-1 thumbprint (a.k.a. digest) of the DER encoding of an X.509 certificate.
X.509 Certificate SHA-256 Thumbprint	A 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 Name	Description
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 Name	Description
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 Name	Description
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 Name	Description
Import from URL	URL to the SAML Identity Provider Metadata document.
Import From File	File 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 Name	Description
IdP Entity ID	The Identity Provider's Entity ID.
SP Entity ID	The 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) Binding	The expected binding used by the Identity Provider when interacting with Ignition's Assertion Consumer Service.
Name ID Format	The 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 URL	The Identity Provider's Single Sign-On (SSO) Service URL.
Single Sign-On (SSO) Service Binding	The binding Ignition will use for sending Authn Requests to the Identity Provider's Single Sign-On (SSO) Service.
Force Authn	Check 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 Signatures	Check this box to validate the signature of the response from the Identity Provider.
Validate Assertion Signatures	Check 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 Keys	A list of signing key(s) that Ignition uses to validate signatures from the IdP.
Signature Verifying Certificates	A base64-encoded DER PKIX certificate value.

SAML Signature Verifying Key Configuration

Property Name	Description
Key Algorithm	The algorithm identifier for this signature verifying key. Options are DSA, RSA, or EC.
Key Value	A 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.