Outdated SSO user records in IP Fabric might cause login issues
With SSO configured, each sign-in of a new user into IP Fabric via SSO will
create a new (non-local) user record in Settings → Administration →
Local Users – with the user’s current username and email from the
Identity Provider (IdP).
If the user’s username or email change on the IdP side, the user will
encounter Authentication Failure while logging in to IP Fabric via SSO –
due to username/email mismatch between the IdP and IP Fabric.
In that case, please remove the outdated user record of that user in
Settings → Administration → Local Users.
IP Fabric includes support for single sign-on. We have opted for
Dex (A Federated OpenID Connect Provider) as a key
building block to allow a broader set of Identity Providers (IdP).
Complex Configuration
Implementation of SSO configuration can be complex, and because of that, it
is recommended to be configured for you by our Solution Architects. If you
are unsure who your Solution Architect is, please contact our Support Team.
Requirements
Certificate
Prior to configuring SSO, the IP Fabric server must not be using a self-signed
certificate. To create a new signed TLS certificate, please see the instructions
located at IPF Certificates.
Private Certificate Authority (CA)
IP Fabric only trusts certificates issued by CAs listed in the system
openssl trust-store. If your company uses certificates signed by an
internal CA, please reach out to your Solution Architect or open a Support
ticket for further configuration in order to properly enable SSO.
CLI Access
In order to make changes to certain files, you must have access to the osadmin
account to log in to the CLI and gain root access. For more information, please
see CLI Overview.
The IP Fabric API configuration is stored in /opt/nimpee/conf.d/api.json. This
file needs to be created during the first configuration as it does not exist in
the default image. It will also be persistent during upgrades and will not be
changed. Below is a full example of the api.json config file:
In IP Fabric version 6.1.0, the ability to use roleName in the SSO
configuration was added. It is recommended to switch from using roleId to
roleName for consistency and human readability.
JSON Validation
The example below is a malformed JSON due to the comma after app.url:
name – User-defined name of the Identity Provider (IdP) displayed in the
GUI.
Can only contain a-z0-9_. Do not use uppercase.
Used in ipf-dex.yaml for redirectURIs under
staticClients.
This name will be displayed on the login page of the GUI. This name will be
capitalized (sso → Sso), therefore it is recommended to use names such
as azure or okta.
clientId – User-defined value (suggested to keep ipfabric).
clientSecret – User-defined value for a shared secret between IP Fabric and
Dex only.
Can be randomly created for instance using Python:
python -c "import secrets; print(secrets.token_urlsafe())"
Used in ipf-dex.yaml for secret under
staticClients.
roleAssignments – An array of objects.
Objects are in the format of
{groupName: string, roleId?: string|null, roleName?: string|null }
groupName – The name of the group that is configured on the SSO side.
any will provide access to any user by default.
Multiple mappings with the same groupName will get merged (so the user
will receive all corresponding roles on the IP Fabric side).
roleId – The ID of the IP Fabric role.
A value of null will provide no access.
Either roleId or roleName property must be specified, not both.
Please do not confuse roleId with roleName as these are different
values. roleId must be retrieved using the browser Developer Tools or
using the API (example below).
roleName – The name of the IP Fabric role.
A value of null will provide no access.
Either roleName or roleId property must be specified, not both.
Since version 6.1, you can opt to only use roleName instead of
roleId in your configuration.
Since version 6.3, roleName can only contain a-zA-Z0-9_-.
Previously created roles will be automatically modified by removing
not-allowed characters from role name according to the new validation rules.
Make sure specified roleName refers to the existing role in the system.
Example how to find roleId:
SSO Configuration ipf-dex.yaml
While Dex supports various connectors, we strongly recommend using OpenID
Connect (OIDC) for SSO integration (Azure uses a special microsoft connector
and an example is provided below along with SAML). Please check the
official Dex documentation for their
overview.
Dex configuration is located in /etc/ipf-dex.yaml on the IP Fabric appliance.
It has several configuration sections and a full example of the file is located
below. Please note that OIDC, SAML, and Azure have different syntaxes for the
connectors configuration portion, which are covered separately.
# /etc/ipf-dex.yaml# example config in both devOps/etc/ipf-dex.yaml and devOps-install/install/ipf-dex.yamlissuer:https://<FQDN>/dexstaticClients:-id:ipfabricredirectURIs:-"https://<FQDN>/api/<API_VERSION>/auth/external/<API-DEX-PROVIDERS-NAME>"name:IP Fabricsecret:<RANDOM_SECRET>storage:type:memorylogger:level:debugweb:http:127.0.0.1:5556telemetry:http:127.0.0.1:5558grpc:addr:127.0.0.1:5557oauth2:skipApprovalScreen:trueconnectors:-type:oidcid:sso_oidcname:SSO OIDCconfig:issuer:<SSO_ISSUER>redirectURI:https://<FQDN>/dex/callbackclientID:<SSO_CLIENT_ID>clientSecret:<SSO_CLIENT_SECRET>getUserInfo:trueinsecureEnableGroups:truescopes:-openid-profile-email-groups
Keep Default Values
The following lines should be left to the default values:
Dex configuration has at the very top an attribute called issuer. This needs
to be configured to be equal to the url under dex in
api.json.
For example:
issuer:https://demo.ipfabric.io/dex
Skip Approval Screen
The following lines of the configuration control if you would like a Grant
Access screen to be presented to your users on every login. By setting it to
true, the message below won’t be displayed.
oauth2:skipApprovalScreen:true
Static Clients
The staticClients section contains the configuration for the IP Fabric portal
which acts as a client to dex.
staticClients:-id:ipfabricredirectURIs:# IPF version `<6.3.0` URL must contain `v<Major>.<Minor>`-"https://demo.ipfabric.io/api/v5.0/auth/external/sso"# IPF version `>=6.3.2` URL can be set to `v<Major>` only-"https://demo.ipfabric.io/api/v6/auth/external/sso"name:IP Fabricsecret:jqv-W_khLSwJdJMHCjhJefyu-QdeXq9kcz8sAfMrO1Q
id – Unique ID of the client within the Dex configuration.
redirectURIs – Full path to the callback endpoint of the IP Fabric client.
It is in the format of
https://<FQDN>/api/<API_MAJOR_VERSION>/auth/external/<API-DEX-PROVIDERS-NAME>
API-DEX-PROVIDERS-NAME is found in api.json
for name under providers.
Can only contain a-z0-9_. Do not use uppercase.
Please be aware of the API_VERSION property which needs to be updated with
every major version IPF release (i.e. v6 → v7).
redirectURIs after upgrade to 6.3.2
In IP Fabric versions <6.3.2 users were required to change the redirectURIs after every upgrade. Starting in version 6.3.2 a fix has been added to ensure that this is only required after upgrading to a new major release version (i.e. v6 → v7).
Please change the redirectURIs to only include the major version: https://<FQDN>/api/v6/auth/external/sso after upgrade to 6.3.2.
Many of the variables required can be found in the OIDC well-known
configuration endpoint. For example take a look at Google:
.well-known/openid-configuration.
getUserInfo – When enabled, the OpenID Connector will query the UserInfo
endpoint for additional claims.
insecureEnableGroups – Groups claims only refresh when the id token is
refreshed, meaning the regular refresh flow doesn’t update the groups claim.
As such, by default the OIDC connector doesn’t allow groups claims. If you are
okay with having potentially stale group claims, you can use this option to
enable groups claims through the OIDC connector on a per-connector basis.
clientID – A client ID configured or generated on the Identity Provider.
clientSecret – A client secret configured or generated on the Identity
Provider.
scopes – A list of scopes to be returned from the Identity Provider.
The ones listed above are the most common. However, these can differ from
provider to provider.
Scopes are normally found in .well-known/openid-configuration which is
discussed in the OIDC section.
claimMapping – Some providers return non-standard claims (i.e. roles), use
claimMapping to map those claims to standard claims.
Azure
Azure
Please review the
Dex documentation on Azure
for all configuration options and potential caveats as Azure requires
special configuration for proper enablement.
When registration finishes, the Azure portal displays the app registration’s Overview pane. You see the Application (client) ID.
From the Certificates & secrets menu, choose + New client secret
Enter a Name for the secret (e.g. clientSecret). Make sure to copy and save generated value for the clientSecret.
From the API permissions menu, choose + Add a permission
Find User.Read permission (under Microsoft Graph) and grant it to the created application:
From the Token Configuration menu, choose + Add groups claim
All groups: Emits security groups and distribution lists and roles.
Security groups: Emits security groups that the user is a member of in the groups claim.
Directory roles: If the user is assigned directory roles, they’re emitted as a wids claim. (The group’s claim won’t be emitted.)
Groups assigned to the application: Emits only the groups that are explicitly assigned to the application and that the user is a member of. Recommended for large organizations due to the group number limit in token.
From the Azure Active Directory > Enterprise applications menu, search the App that you created (e.g. IP Fabric SSO).
From the Users and groups menu of the app, add any users or groups requiring access to the service.
ssoIssuer – Optional: Issuer value expected in the SAML response.
Pick and use one option to validate the signature of the SAML response:
caData – Base64 encoded certification chain.
ca – File location of containing certification chain.
usernameAttr – Maps SAML name value to IP Fabric’s username.
emailAttr – Maps SAML email value to IP Fabric’s email.
groupsAttr – Maps SAML groups value to IP Fabric’s groupName.
nameIDPolicyFormat – The connector uses the value of the NameID element as
the user’s unique identifier which Dex assumes is both unique and
never-changing. Use nameIDPolicyFormat to ensure this is set to a value
which satisfies these requirements.
YAML Validation
While the validity of the actual configuration is determined by Dex itself, it
can be handy to verify parsing of the configuration YAML. You can use the
following to get a JSON representation of /etc/ipf-dex.yaml: