Tutorial: Integrate Azure AD single sign-on with Maverics Identity Orchestrator SAML Connector
Strata provides a simple way to integrate on-premises applications with Azure Active Directory (Azure AD) for authentication and access control.
This article walks you through how to configure Maverics Identity Orchestrator to:
- Incrementally migrate users from an on-premises identity system into Azure AD during login to a legacy on-premises application.
- Route login requests from a legacy web-access management product, such as CA SiteMinder or Oracle Access Manager, to Azure AD.
- Authenticate users to on-premises applications that are protected by using HTTP headers or proprietary session cookies after authenticating the user against Azure AD.
Strata provides software that you can deploy on-premises or in the cloud. It helps you discover, connect, and orchestrate across identity providers to create distributed identity management for hybrid and multi-cloud enterprises.
This tutorial demonstrates how to migrate an on-premises web application that's currently protected by a legacy web access management product (CA SiteMinder) to use Azure AD for authentication and access control. Here are the basic steps:
- Install Maverics Identity Orchestrator.
- Register your enterprise application with Azure AD, and configure it to use Maverics Azure AD SAML Zero Code Connector for SAML-based single sign-on (SSO).
- Integrate Maverics with SiteMinder and the Lightweight Directory Access Protocol (LDAP) user store.
- Set up an Azure key vault, and configure Maverics to use it as its secrets management provider.
- Demonstrate user migration and session abstraction by using Maverics to provide access to an on-premises Java web application.
For additional installation and configuration instructions, go to the Strata website.
- An Azure AD subscription. If you don't have a subscription, you can get a free account.
- A Maverics Identity Orchestrator SAML Connector SSO-enabled subscription. To obtain the Maverics software, contact Strata sales.
Install Maverics Identity Orchestrator
To get started with the Maverics Identity Orchestrator installation, see the installation instructions.
Supported operating systems
- RHEL 7+
- CentOS 7+
Obtain the latest Maverics Redhat Package Manager (RPM) package. Copy the package to the system on which you want to install the Maverics software.
Install the Maverics package, substituting your file name in place of
sudo rpm -Uvf maverics.rpm
After you install Maverics, it will run as a service under
systemd. To verify that the service is running, execute the following command:
sudo systemctl status maverics
By default, Maverics is installed in the /usr/local/bin directory.
After you install Maverics, the default maverics.yaml file is created in the /etc/maverics directory. Before you edit your configuration to include
connectors, your configuration file will look like this:
# © Strata Identity Inc. 2020. All Rights Reserved. Patents Pending. version: 0.1 listenAddress: ":7474"
version field declares which version of the configuration file is being used. If the version isn't specified, the most recent configuration version will be used.
listenAddress declares which address Orchestrator will listen on. If the host section of the address is blank, Orchestrator will listen on all available unicast and anycast IP addresses of the local system. If the port section of the address is blank, a port number is chosen automatically.
tls field declares a map of Transport Layer Security (TLS) objects. The TLS objects can be used by connectors and the Orchestrator server. For all available TLS options, see the
transport package documentation.
Microsoft Azure requires communication over TLS when you're using SAML-based SSO. For information about generating certificates, go to the Let's Encrypt website.
maverics key is reserved for the Orchestrator server. All other keys are available and can be used to inject a TLS object into a given connector.
tls: maverics: certFile: /etc/maverics/maverics.cert keyFile: /etc/maverics/maverics.key
You can define
workflows in their own, separate configuration files and reference them in the maverics.yaml file by using
includeFiles, per the following example:
includeFiles: - workflow/sessionAbstraction.yaml - connector/AzureAD-saml.yaml - connector/siteminder.yaml
This tutorial uses a single maverics.yaml configuration file.
Use Azure Key Vault as your secrets provider
To load secrets, Maverics can integrate with various secret management solutions. The current integrations include a file, Hashicorp Vault, and Azure Key Vault. If no secret management solution is specified, Maverics defaults to loading secrets in plain text out of the maverics.yaml file.
To declare a value as a secret in a maverics.yaml config file, enclose the secret in angle brackets:
connectors: - name: AzureAD type: AzureAD apiToken: <AzureADAPIToken> oauthClientID: <AzureADOAuthClientID> oauthClientSecret: <AzureADOAuthClientSecret>
Load secrets from a file
To load secrets from a file, add the environment variable
MAVERICS_SECRET_PROVIDERin the /etc/maverics/maverics.env file by using:
MAVERICS_SECRET_PROVIDER=secretfile:///<PATH TO SECRETS FILE>
Restart the Maverics service by running:
sudo systemctl restart maverics
The secrets.yaml file contents can be filled with any number of
secrets: AzureADAPIToken: aReallyGoodToken AzureADOAuthClientID: aReallyUniqueID AzureADOAuthClientSecret: aReallyGoodSecret
Set up an Azure key vault
You can set up an Azure key vault by using either the Azure portal or the Azure CLI.
Use the Azure portal
- Sign in to the Azure portal.
- Create a new key vault.
- Add the secrets to the key vault.
- Register an application with Azure AD.
- Authorize an application to use a secret.
Use the Azure CLI
Open the Azure CLI, and then enter the following command:
Create a new key vault by running the following command:
az keyvault create --name "[VAULT_NAME]" --resource-group "[RESOURCE_GROUP]" --location "[REGION]"
Add the secrets to the key vault by running the following command:
az keyvault secret set --vault-name "[VAULT_NAME]" --name "[SECRET_NAME]" --value "[SECRET_VALUE]"
Register an application with Azure AD by running the following command:
az ad sp create-for-rbac -n "MavericsKeyVault" --skip-assignment > azure-credentials.json
Authorize an application to use a secret by running the following command:
az keyvault set-policy --name "[VAULT_NAME]" --spn [APPID] --secret-permissions list get #APPID can be found in the azure-credentials.json generated in the previous step
To load secrets from your Azure key vault, set the environment variable
MAVERICS_SECRET_PROVIDERin the /etc/maverics/maverics.env file by using the credentials found in the azure-credentials.json file, in the following format:
Restart the Maverics service:
sudo systemctl restart maverics
Configure your application in Azure AD for SAML-based SSO
In your Azure AD tenant, go to Enterprise applications, search for Maverics Identity Orchestrator SAML Connector, and then select it.
On the Maverics Identity Orchestrator SAML Connector Properties pane, set User assignment required? to No to enable the application to work for newly migrated users.
On the Maverics Identity Orchestrator SAML Connector Overview pane, select Set up single sign-on, and then select SAML.
On the Maverics Identity Orchestrator SAML Connector SAML-based sign on pane, edit the Basic SAML Configuration by selecting the Edit (pencil icon) button.
Enter the Entity ID by typing a URL in the following format:
https://<SUBDOMAIN>.maverics.org. The Entity ID must be unique across the apps in the tenant. Save the value entered here to be included in the configuration of Maverics.
Enter the Reply URL in the following format:
Enter the Sign on URL in the following format:
In the SAML Signing Certificate section, select the Copy button to copy the App Federation Metadata URL, and then save it to your computer.
Configure Maverics Identity Orchestrator Azure AD SAML Connector
Maverics Identity Orchestrator Azure AD Connector supports OpenID Connect and SAML Connect. To configure the connector, do the following:
To enable SAML-based SSO, set
Create the value for
samlMetadataURLin the following format:
samlMetadataURL:https://login.microsoftonline.com/<TENANT ID>/federationmetadata/2007-06/federationmetadata.xml?appid=<APP ID>.
Define the URL that Azure will be redirected back to in your app after users have logged in with their Azure credentials. Use the following format:
Copy the value from the previously configured EntityID:
Copy the value from the Reply URL that Azure AD will use to post the SAML response:
Generate a JSON Web Token (JWT) signing key, which is used to protect the Maverics Identity Orchestrator session information, by using the OpenSSL tool:
openssl rand 64 | base64
Copy the response to the
Attributes and attribute mapping
Attribute mapping is used to define the mapping of user attributes from a source on-premises user directory into an Azure AD tenant after the user is set up.
Attributes determine which user data might be returned to an application in a claim, passed into session cookies, or passed to the application in HTTP header variables.
Configure the Maverics Identity Orchestrator Azure AD SAML Connector YAML file
Your Maverics Identity Orchestrator Azure AD Connector configuration will look like this:
- name: AzureAD type: azure authType: saml samlMetadataURL: https://login.microsoftonline.com/<TENANT ID>/federationmetadata/2007-06/federationmetadata.xml?appid=<APP ID> samlRedirectURL: https://<AZURECOMPANY.COM>/<MY_APP> samlConsumerServiceURL: https://<AZURE-COMPANY.COM>/<MY_APP> jwtSigningKey: <SIGNING KEY> samlEntityID: https://<SUBDOMAIN>.maverics.org attributeMapping: displayName: username mailNickname: givenName givenName: givenName surname: sn userPrincipalName: mail password: password
Migrate users to an Azure AD tenant
Follow this configuration to incrementally migrate users from a web access management product, such as CA SiteMinder, Oracle Access Manager, or IBM Tivoli. You can also migrate them from a Lightweight Directory Access Protocol (LDAP) directory or a SQL database.
Configure your application permissions in Azure AD to create users
In your Azure AD tenant, go to
App registrationsand select the Maverics Identity Orchestrator SAML Connector application.
On the Maverics Identity Orchestrator SAML Connector | Certificates & secrets pane, select
New client secretand then select on expiration option. Select the Copy button to copy the secret and save it to your computer.
On the Maverics Identity Orchestrator SAML Connector | API permissions pane, select Add permission and then, on the Request API permissions pane, select Microsoft Graph and Application permissions.
On the next screen, select User.ReadWrite.All, and then select Add permissions.
Back on the API permissions pane, select Grant admin consent.
Configure the Maverics Identity Orchestrator SAML Connector YAML file for user migration
To enable the user migration workflow, add these additional properties to the configuration file:
- Enter the Azure Graph URL in the following format:
- Enter the OAuth Token URL in the following format:
oauthTokenURL: https://login.microsoftonline.com/<TENANT ID>/federationmetadata/2007-06/federationmetadata.xml?appid=<APP ID>.
- Enter the previously generated client secret in the following format:
oauthClientSecret: <CLIENT SECRET>.
Your final Maverics Identity Orchestrator Azure AD Connector configuration file will look like this:
- name: AzureAD type: azure authType: saml samlMetadataURL: https://login.microsoftonline.com/<TENANT ID>/federationmetadata/2007-06/federationmetadata.xml?appid=<APP ID> samlRedirectURL: https://<AZURECOMPANY.COM>/<MY_APP> samlConsumerServiceURL: https://<AZURE-COMPANY.COM>/<MY_APP> jwtSigningKey: TBHPvTtu6NUqU84H3Q45grcv9WDJLHgTioqRhB8QGiVzghKlu1mHgP1QHVTAZZjzLlTBmQwgsSoWxGHRcT4Bcw== samlEntityID: https://<SUBDOMAIN>.maverics.org graphURL: https://graph.microsoft.com oauthTokenURL: https://login.microsoftonline.com/<TENANT ID>/oauth2/v2.0/token oauthClientID: <APP ID> oauthClientSecret: <NEW CLIENT SECRET> attributeMapping: displayName: username mailNickname: givenName givenName: givenName surname: sn userPrincipalName: mail password: password
Configure Maverics Zero Code Connector for SiteMinder
You use the SiteMinder connector to migrate users to an Azure AD tenant. You log the users in to legacy on-premises applications that are protected by SiteMinder by using the newly created Azure AD identities and credentials.
For this tutorial, SiteMinder has been configured to protect the legacy application by using forms-based authentication and the
SMSESSION cookie. To integrate with an app that consumes authentication and session information through HTTP headers, you need to add the header emulation configuration to the connector.
This example maps the
username attribute to the
SM_USER HTTP header:
headers: SM_USER: username
proxyPass to the location that requests are proxied to. Typically, this location is the host of the protected application.
loginPage should match the URL of the login form that's currently used by SiteMinder when it redirects users for authentication.
connectors: - name: siteminder-login-form type: siteminder loginType: form loginPage: /siteminderagent/forms/login.fcc proxyPass: http://host.company.com
Configure Maverics Zero Code Connector for LDAP
When applications are protected by a web access management (WAM) product such as SiteMinder, user identities and attributes are typically stored in an LDAP directory.
This connector configuration demonstrates how to connect to the LDAP directory. The connector is configured as the user store for SiteMinder so that the correct user profile information can be collected during the migration workflow and a corresponding user can be created in Azure AD.
baseDNspecifies the location in the directory against which to perform the LDAP search.
urlis the address and port of the LDAP server to connect to.
serviceAccountUsernameis the username that's used to connect to the LDAP server, usually expressed as a bind DN (for example,
serviceAccountPasswordis the password that's used to connect to the LDAP server. This value is stored in the previously configured Azure key vault instance.
userAttributesdefines the list of user-related attributes to query for. These attributes are later mapped into corresponding Azure AD attributes.
- name: company-ldap type: ldap url: "ldap://ldap.company.com:389" baseDN: ou=People,o=company,c=US serviceAccountUsername: uid=admin,ou=Admins,o=company,c=US serviceAccountPassword: <vaulted-password> userAttributes: - uid - cn - givenName - sn - mail - mobile
Configure the migration workflow
The migration workflow configuration determines how Maverics migrates users from SiteMinder or LDAP to Azure AD.
- Uses the SiteMinder connector to proxy the SiteMinder login. User credentials are validated through SiteMinder authentication and then passed to subsequent steps of the workflow.
- Retrieves user profile attributes from the SiteMinder user store.
- Makes a request to the Microsoft Graph API to create the user in your Azure AD tenant.
To configure the migration workflow, do the following:
Give the workflow a name (for example, SiteMinder to Azure AD Migration).
endpoint, which is an HTTP path on which the workflow is exposed, triggering the
actionsof that workflow in response to requests. The
endpointtypically corresponds to the app that's proxied (for example,
/my_app). The value must include both the leading and trailing slashes.
Add the appropriate
actionsto the workflow.
a. Define the
loginmethod for the SiteMinder connector. The connector value must match the name value in the connector configuration.
b. Define the
getprofilemethod for the LDAP connector.
c. Define the
createusermethod for the AzureAD connector.
workflows: - name: SiteMinder to Azure AD Migration endpoint: /my_app/ actions: - connector: siteminder-login-form method: login - connector: company-ldap method: getprofile - connector: AzureAD method: createuser
Verify the migration workflow
If the Maverics service is not already running, start it by executing the following command:
sudo systemctl start maverics
Go to the proxied login URL,
Provide the user credentials that are used to log in to the application while it's protected by SiteMinder.
Go to Home > Users | All Users to verify that the user is created in the Azure AD tenant.
Configure the session abstraction workflow
The session abstraction workflow moves authentication and access control for the legacy on-premises web application to the Azure AD tenant.
The Azure connector uses the
login method to redirect the user to the login URL, assuming that no session exists.
After it's authenticated, the session token that's created as a result is passed to Maverics. The SiteMinder connector's
emulate method is used to emulate the cookie-based session or the header-based session and then decorate the request with any additional attributes required by the application.
Give the workflow a name (for example, SiteMinder Session Abstraction).
endpoint, which corresponds to the app that's being proxied. The value must include both leading and trailing slashes (for example,
Add the appropriate
actionsto the workflow.
a. Define the
loginmethod for the Azure connector. The
connectorvalue must match the
namevalue in the connector configuration.
b. Define the
emulatemethod for the SiteMinder connector.
- name: SiteMinder Session Abstraction endpoint: /my_app/ actions: - connector: azure method: login - connector: siteminder-login-form method: emulate
Verify the session abstraction workflow
Go to the proxied application URL,
You're redirected to the proxied login page.
Enter the Azure AD user credentials.
You should be redirected to the application as though you were authenticated directly by SiteMinder.