SSO SAML Authentication

Identity Provider Authentication

Beginning with the 2023.2 release, IAP has expanded its user management capabilities to include Single Sign-On (SSO) via SAML. As of the 2023.2 release, the following providers are supported in IAP: Okta, Azure, AD FS, and PingId. To enable SSO, an Identity Provider (IDP) Config must be created under Admin Essentials → Authorization → Identity Providers.

Along with enabling an Identity Provider, a successful authentication test is required. Upon successful test, a single provider can be enabled at a time. Once an Identity Provider is enabled, all IAP authentication is done via SSO SAML using that config immediately without restart of IAP. Authentication via AAA broker is still supported, but it is disabled when an Identity Provider is enabled. All IDP Configs must be disabled to continue AAA broker authentication usage.

Creating an Identity Provider

To create an Identity Provider, first navigate to Admin Essentials → Authorization → Identity Providers. Then, click the New Provider button. This will prompt you for the name and optional description of the Identity Provider. All providers must use SAML in 2023.2, so that cannot be changed.

Any number of IDP Configs can be created for a single IDP (Identity Provider). For instance, if two (2) IDP Configs are created for an Okta provider with Login URL https://exampleapp.oktapreview.com/app/examplesaml/7Y374u1d7/sso/saml, separate IAP users will be created for each IDP upon successful authentication, and each will have provenance corresponding to the name of the IDP. Accordingly, a user authenticated from Okta using two (2) separate IDP Configs with username example@email creates two separate IAP users with the same username, but a different provenance.

Figure 1: Identity Providers Home Page

Figure 2: Identity Providers Create Dialog

Newly created Identity Providers are disabled by default and include empty text fields for the required Issuer, Login URL, Username Attribute, and Groups Attribute fields. The Login URL is the entry point by which SSO authentication is initiated. The Issuer maps to the Entity Identifier from the provider. Identity Providers also require a public signing certificate, which can be retrieved from the IDP and uploaded to IAP. This certificate is used to validate signatures of incoming SAML responses. Below shows the newly created IDP from the above example. These fields are provider specific. Refer to the table at the end of this article for locating configuration values in each provider, as this can change depending on the provider.

Figure 3: New Identity Provider Created

The IDP Config can be saved whenever it is changed. Below is an example of a config with all required fields filled in, as well as an uploaded certificate. Note that every time an Identity Provider is updated, a successful authentication test (via Test Connection) is required to enable the config in IAP.

Figure 4: Identity Provider SSO Config

Identity Provider Group Mappings

The Group Mappings table of an IDP Config maps internal IAP groups to external Identity Provider groups. Upon successful login of a user via SSO, IAP will assign roles from the internal IAP groups mapped to the groups returned by the SAML response from the IDP. In the below example, when Okta Example is enabled, and a user authenticates via SSO SAML in IAP, if that user is a member of the Developers group in Okta Example, then the user will be assigned all roles in the pronghornall IAP group.

Figure 5: Identity Provider Group Mappings

Figure 6: New Group Mapping

Testing Identity Provider

To enable an Identity Provider in IAP, you will need to successfully test the config. You can initiate a test by clicking the Test Connection button at the top of the Identity Providers page. This will initiate SSO SAML authentication with the provider in a new tab. Successful tests require the Profiles.updateProfile permission from the group mappings (at a minimum) to provide a mechanism for disabling the config. Upon successful authentication, the below response is displayed to the user and the tab can be closed. Each new save of an IDP Config will require a new successful test.

Figure 7: Identity Provider Successful Test

SSO Login Page

Once an Identity Provider is enabled, the IAP authentication method immediately switches to SSO SAML with the enabled config. The active IAP session does not end, but upon logout or IAP session expiration, the enabled config will require login via SSO. Below shows the login page displayed when an Identity Provider is enabled. When the SSO Sign In button is clicked, SSO SAML authentication is initiated. If no Identity Provider is enabled, the normal default login page is used for AAA authentication. Note that the login API can no longer be used if SSO is enabled, but works as normal if it is not enabled.

Figure 8: Identity Provider Login Screen

Retrieving Configuration Values for Identity Providers

The following table is an attribute mapping of Identity Providers to IAP. Each row corresponds to an identity provider (such as Okta and Azure), and each column is a provider attribute for the mapping, such as Issuer or Login Url. Each table cell contains the location of the property in the IDP, which may or may not be configurable.