FlexDeploy can be integrated with a single sign-on service using various options like OpenID Connect, SAML, OAuth etc. You can use an external service like Okta, Microsoft Azure AD, and many more, or use existing corporate single sign-on solution. Note that FlexDeploy does not provide single sign-on and multi-factor authentication services.
Integration mechanisms supported are OpenID Connect, SAML, OAuth. We have verified this using Okta and Microsoft Azure AD using OpenID Connect. For other OpenID Connect providers and other types of integrations, please reach out to us using the support portal.
There are some limitations in the current version of this integration:
Group mapping (Claim in OpenID Connect) is not yet supported. You will need to configure authorization for users using FlexDeploy UI.
The REST API still requires logging in using local realm users, alternatively you can use API Tokens.
Configuration is done using configuration files. There is no UI available at this time.
Once you enable single sign-on, you will not be able to configure or use other Realms for authentication and authorization.
You can further secure this by enabling multi-factor authentication, where users are granted access only after successfully presenting two or more pieces of evidence to an authentication mechanism. This will not be discussed here as it will be done on your single sign-on provider.
Even after enabling single sign-on, you will be able to log in using local users if necessary. If you want to log in with local users, then navigate directly to https://FLEXDEPLOYHOST:FLEXDEPLOYPORT/flexdeploy/next/#/login.
You can enable SSO, MFA, or both as it depends on your Provider.
Enable Single Sign-On and/or Multi Factor Authentication
Single sign-on integration will be done by adding a configuration file on the FlexDeploy application server host. You should keep this file readable only by the FlexDeploy process user. There is no restriction on where this file should be kept, but it’s a good idea to keep it with the FlexDeploy installation files, For example, $FLEXDEPLOY_HOME/sso folder. If you change values in this file, you will need to restart your FlexDeploy server to pick up those changes.
The configuration file can be named as per your wish, but we will use the name fdsso.config for this documentation. The location of the configuration file will need to be added to server startup arguments in setenvoverride.sh file or setenvoverride.bat file. We recommend that this fdsso.config file is not kept under apache-tomcat-flexdeploy folder, as that folder is replaced during upgrade process. Here is the syntax for startup argument:
-Dflexagon.fd.sso.config=FULLY_QUALIFIED_PATH_TO_SSO_CONFIG_FILE
Here are some examples of fdsso.config files for various providers.
Okta (OpenID Connect)
Replace capitalized text with appropriate values. You will need to define an application in your Okta console and update values in the configuration file as shown below.
OKTACLIENTID - get this value from Okta application configuration.
OKTACLIENTSECRET - get this value from Okta application configuration.
OKTADOMAIN - get this value from your Okta domain details.
FLEXDEPLOYHOST - FlexDeploy application host
FLEXDEPLOYPORT - FlexDeploy application port
Example fdsso.config file for Okta (OpenID Connect)
If you are upgrading from 5.7 or before, then excludedPathMatcher.excludedPath and logout.defaultUrl has changed, everything else remains same.
oidcConfig = org.pac4j.oidc.config.OidcConfiguration oidcConfig.clientId = OKTACLIENTID oidcConfig.secret = OKTACLIENTSECRET oidcConfig.discoveryURI = https://OKTADOMAIN.okta.com/.well-known/openid-configuration oktaClient = org.pac4j.oidc.client.OidcClient oktaClient.configuration = $oidcConfig clients.callbackUrl = https://FLEXDEPLOYHOST:FLEXDEPLOYPORT/flexdeploy/callback clients.clients = $oktaClient isAuthenticatedAdmin = org.pac4j.core.authorization.authorizer.IsAuthenticatedAuthorizer excludedPathMatcher = org.pac4j.core.matching.matcher.PathMatcher excludedPathMatcher.excludedPath = /next/#/login config.authorizers = admin:$isAuthenticatedAdmin config.matchers = excludedPath:$excludedPathMatcher ssoFilter = flexagon.fd.ui.security.FlexPac4jFilter ssoFilter.config = $config ssoFilter.clients = OidcClient ssoFilter.matchers = nocache ssoFilter.authorizers = admin logout = io.buji.pac4j.filter.LogoutFilter logout.config = $config logout.localLogout = true logout.centralLogout = true logout.defaultUrl = https://FLEXDEPLOYHOST:FLEXDEPLOYPORT/flexdeploy/next/#/home
Here is what configuration looks like in Okta.
Okta (SAML 2.0)
SSO integration using SAML requires FlexDeploy to be running using HTTPS.
You must also download the Okta Certificate (from within the Okta Edit SAML Settings).
and import it into the keystore which was created as part of the HTTPS configuration (adjust parameters below as appropriate).
/u01/java/jdk1.8.0_281/bin/keytool -import -alias okta -file /var/tmp/okta.cert -keystore /home/oracle/flexdeploy.keystore
Replace capitalized text with appropriate values. You will need to define an application in your Okta console and update values in the configuration file as shown below.
FLEXDEPLOY_HOME - Directory on the server where FlexDeploy is installed
KEYSTORE_PASSWORD - The Java key store password.
PRIVATE_KEY_PASSWORD -The private key password.
OKTA_METADATA_URL - The URL (from Okta) to the identity provider metadata (e.g. https://dev-484624.okta.com/app/exk4c1ilhiTs3dKRb4y5/sso/saml/metadata).
FLEXDEPLOY_HOST - FlexDeploy application host
FLEXDEPLOY_PORT - FlexDeploy application port
Example fdsso.config file for Okta (SAML 2.0)
If you are upgrading from 5.7 or before, then excludedPathMatcher.excludedPath and logout.defaultUrl has changed, everything else remains same.
saml2Config = org.pac4j.saml.config.SAML2Configuration saml2Config.keystorePath = FLEXDEPLOY_HOME/apache-tomcat-flexdeploy/certs/samlKeystore.jks saml2Config.keystorePassword = KEYSTORE_PASSWORD saml2Config.privateKeyPassword = PRIVATE_KEY_PASSWORD saml2Config.identityProviderMetadataPath = OKTA_METADATA_URL saml2Config.maximumAuthenticationLifetime = 3600 saml2Config.serviceProviderEntityId = https://FLEXDEPLOY_HOST:FLEXDEPLOY_PORT/flexdeploy/callback?client_name=SAML2Client saml2Config.serviceProviderMetadataPath = FLEXDEPLOY_HOME/apache-tomcat-flexdeploy/sso/FlexDeployMetadata.xml saml2Client = org.pac4j.saml.client.SAML2Client saml2Client.configuration = $saml2Config clients.callbackUrl = https://FLEXDEPLOY_HOST:FLEXDEPLOY_PORT/flexdeploy/callback clients.clients=$saml2Client isAuthenticatedAdmin = org.pac4j.core.authorization.authorizer.IsAuthenticatedAuthorizer excludedPathMatcher = org.pac4j.core.matching.matcher.PathMatcher excludedPathMatcher.excludedPath = /next/#/login config.authorizers = admin:$isAuthenticatedAdmin config.matchers = excludedPath:$excludedPathMatcher ssoFilter = flexagon.fd.ui.security.FlexPac4jFilter ssoFilter.config = $config ssoFilter.clients = SAML2Client ssoFilter.matchers = nocache ssoFilter.authorizers = admin logout = io.buji.pac4j.filter.LogoutFilter logout.config = $config logout.localLogout = true logout.centralLogout = true logout.defaultUrl = https://FLEXDEPLOY_HOST:FLEXDEPLOY_PORT/flexdeploy/next/#/home
Configuration Tips
If the Java keystore referenced (line 2) does not exist, it will automatically be created, and key will be generated and inserted into the keystore using the passwords provided (line 3 and 4).
The Okta Identity Provider Metadata can be found from within the Sign On tab of your Okta application.
Azure Active Directory (OpenID Connect)
Replace capitalized text with appropriate values.
APPLICATION(CLIENT)ID
CLIENTSECRET
DIRECTORY(TENANT)ID
FLEXDEPLOYHOST
FLEXDEPLOYPORT
Example fdsso.config file for Azure Active Directory
If you are upgrading from 5.7 or before, then excludedPathMatcher.excludedPath and logout.defaultUrl has changed, everything else remains same.
oidcConfig = org.pac4j.oidc.config.AzureAdOidcConfiguration oidcConfig.clientId = APPLICATION(CLIENT)ID oidcConfig.secret = CLIENTSECRET oidcConfig.discoveryURI = https://login.microsoftonline.com/DIRECTORY(TENANT)ID/.well-known/openid-configuration oidcConfig.useNonce = true oidcConfig.tenant = DIRECTORY(TENANT)ID azureAdClient = org.pac4j.oidc.client.AzureAdClient azureAdClient.configuration = $oidcConfig clients.callbackUrl = https://FLEXDEPLOYHOST:FLEXDEPLOYPORT/flexdeploy/callback clients.clients = $azureAdClient isAuthenticatedAdmin = org.pac4j.core.authorization.authorizer.IsAuthenticatedAuthorizer excludedPathMatcher = org.pac4j.core.matching.matcher.PathMatcher excludedPathMatcher.excludedPath = /next/#/login config.authorizers = admin:$isAuthenticatedAdmin config.matchers = excludedPath:$excludedPathMatcher ssoFilter = flexagon.fd.ui.security.FlexPac4jFilter ssoFilter.config = $config ssoFilter.clients = AzureAdClient ssoFilter.matchers = nocache ssoFilter.authorizers = admin logout = io.buji.pac4j.filter.LogoutFilter logout.config = $config logout.localLogout = true logout.centralLogout = true logout.defaultUrl = https://FLEXDEPLOYHOST:FLEXDEPLOYPORT/flexdeploy/next/#/home
Register application in Azure Active Directory.
Capture Application (client) ID and Directory (tenant) ID from App Registration.
Create and capture client secret.
Here is how URL values are configured on Azure App Registration.