External Identity Providers¶
This section describes how to configure an external identity provider (IdP) in Neteye.
Identity Providers are services that create, maintain, and manage identity information for users while providing authentication services to relying applications within a federation or distributed network. If you have an existing IdP, you can configure it in NetEye to authenticate users with it (via SAML), defined in RFC 7522 or OIDC defined in the OpenID Connect Core 1.0 specification. Some popular options for that are: Ping Identity, Fortinet or MS ADFS. This page also shows examples of how to configure some of the most common IdPs.
When an IdP is enabled, Keycloak redirects the user to the IdP login page based on the email address’ domain.
Note
If LDAP is enabled and provides the user’s email address, the user can insert only the username at the login.
Add an IdP in NetEye¶
To add an IdP in NetEye, access the Authentication Admin Console and click on the menu item. Many already configured IdPs can be easily set up by clicking a button under the Social section, or a custom IdP can be configured by selecting a protocol under the User defined tab.
Note
Keycloak supports SAML v2.0, OIDC v1.0, and OAuth 2.0.
After clicking a button, a wizard will guide you through the configuration of the IdP. You will also need access to the IdP admin console to obtain the necessary information to configure the IdP in NetEye, and accept NetEye as a client.
Specific IdP how-to guides¶
How to configure MSADFS
How to configure FortiAuthenticator
OpenID Connect (OIDC)¶
Keycloak supports the auto discovery of OIDC configuration from the IdP. The URL:
https://{YOUR-IDP-HOST}/.well-known/openid-configuration can be used to configure the IdPs
discovery endpoint inside the Keycloak configuration form. If you want to configure the IdP
manually, you can follow the official
OIDC Configuration documentation.
We generally recommend using OIDC over SAML when possible, as it is easier to integrate with Keycloak and has a
Security Assertion Markup Language (SAML)¶
Keycloak supports the SAML identity descriptor file (metadata) from the IdP. If you want to configure the IdP manually, you can follow the official SAML Configuration documentation.
Common IdP configuration¶
Alias |
The alias is a unique identifier for an identity provider and references an internal identity provider. Keycloak uses the alias to build redirect URIs for OpenID Connect protocols that require a redirect URI or callback URL to communicate with an identity provider. All identity providers must have an alias. Examples of aliases include Facebook, Google, and idp.acme.com. |
Hide on Login Page |
When ON, Keycloak does not display this provider as a login option on the login page. In NetEye MUST be set to true because we have the idp auto selection based on email address |
Account Linking Only |
When ON, Keycloak links existing accounts with this provider. This provider cannot log users in, and Keycloak does not display this provider as an option on the login page. In NetEye MUST be set to false |
Store tokens |
When ON, Keycloak stores tokens from the identity provider. In NetEye MUST be set to false |
Store Token Readable |
When ON, users can retrieve the stored identity provider token. This action also applies to the broker client-level role read token. In NetEye MUST be set to false |
Trust Email |
When ON, Keycloak trusts email addresses from the identity provider. In NetEye MUST be set to true |
Verify essential claim |
ONLY FOR OIDC. When ON, ID tokens issued by the identity provider must have a specific claim; otherwise, the user cannot authenticate through this broker. |
Essential claim |
ONLY FOR OIDC. When Verify essential claim is ON, the name of the JWT token claim to filter (match is case sensitive). |
Essential claim value |
ONLY FOR OIDC. When Verify essential claim is ON, the value of the JWT token claim to be matched (supports regular expression format). |
First Login Flow |
The flow to use when the user logs in for the first time. The default is to use the browser flow. In NetEye MUST be set to the default value First login flow override |
Post Login Flow |
The flow to use after the user logs in. The default is to use the browser flow. In NetEye MUST be set to NONE |
Sync Mode |
Strategy to update user information from the identity provider through mappers. When choosing legacy, Keycloak used the current behavior. Import does not update user data, and force updates user data when possible. In NetEye, MUST be set to force because you have to trust the IdP. |
Case-sensitive username |
If enabled, the original username from the identity provider is kept as is when federating users. Otherwise, the username from the identity provider is lower-cased and might not match the original value if it is case-sensitive. This setting only affects the username associated with the federated identity, as usernames in the server are always lower-case. In NetEye MUST be set to true |
Configuring idp domains¶
The Home IdP Discovery plugin allows you to select an IdP for the user that is logging in, based on their email domain. Since that configuration option is currently only available over a REST-API, we provide a neteye subcommand to make these configuration as easy as possible. With the neteye config auth idp command, you can view and edit the domain configuration with the subcommands list and set respectively.
To active the flow, you then also need to follow the configuration steps below. One the first time the user logs in, they need to confirm the password in Keycloak before being automatically linked to the IdP. Once set up, each user can log in over their selected IdP.
Enabling the Home IdP Discovery Flow¶
After setting up the IdP, you must change the default Authentication Flow on Keycloak.
To do this, you need to access the Authentication section in the Authentication Admin Console and:
- Click on the neteye-idp-discovery-flow flow
Click on the Dots menu button and select Bind flow
Select Browser and click on Save
- Click on the neteye-first-broker-login-flow flow
Click on the Dots menu button and select Bind flow
Select First Login Flow and click on Save
