Appendix
Extend Azure AD B2C to protect on-premises apps

Extend Azure AD B2C to protect on-premises apps

In this guide, you’ll learn how to integrate Azure Active Directory B2C (Azure AD B2C) with Strata’s Maverics Identity Orchestrator™.

Introduction

Strata extends Azure AD B2C to protect on-premises applications by enforcing consistent access policies, keeping identities in sync, and making it simple to transition applications from legacy identity systems to standards-based authentication and access control provided by Azure AD B2C. Maverics Identity Orchestrator connects to any identity system, transparently migrates users and credentials, synchronizes policies and configurations, and abstracts authentication and session management. Strata’s unique approach to distributed identity management gives enterprises the power to quickly transition from legacy to Azure AD B2C without rewriting applications.

  • Customer Single Sign-On to On-Premises Hybrid Apps - Azure AD B2C supports rich customer single sign-on with Maverics Identity Orchestrator out of the box. Users sign in with their accounts hosted in Azure AD B2C or social identity provider, and Maverics extends SSO to apps that historically have been secured by legacy identity systems like CA SiteMinder.

  • Extend Standards-based SSO to Apps Without Rewriting Them - Use Azure AD B2C to manage user access and enable single sign-on with Maverics Identity Orchestrator SAML or OIDC Connectors.

  • Easy Configuration - Azure AD B2C provides a simple step-by-step user interface for connecting Maverics Identity Orchestrator SAML or OIDC Connectors to Azure AD B2C.

Prerequisites

To get started, you’ll need:

  • An Azure AD subscription. If you don’t have a subscription, you can get a free account.

  • An Azure AD B2C tenant that’s linked to your Azure subscription.

  • An instance of Azure Key Vault to store secrets used by Maverics Identity Orchestrator to connect to Azure AD B2C or other attribute providers such as a LDAP directory or database.

  • An instance of Maverics Identity Orchestrator installed and running in a virtual machine on Azure or the server of your choice running on-premises. For information about how to get the software and access to the installation and configuration documentation, contact [email protected]

  • An on-premises application that you will transition from a legacy identity system to Azure AD B2C.

Scenario Description

Strata’s Maverics integration includes the following components:

  • Azure AD B2C: The authorization server that’s responsible for verifying the user’s credentials. Authenticated users may access on-prem apps using a local account stored in the Azure AD B2C directory.

  • An external social or enterprise Identity Provider: This could be any OpenID Connect provider, Facebook, Google, or Github. Check the documentation for more information on using external identity providers with Azure AD B2C.

  • Strata’s Maverics Identity Orchestrator: The service that orchestrates user sign-on and transparently passes identity to apps through HTTP headers.

Steps

  1. The user makes a request to access the on-premises hosted application. Maverics Identity Orchestrator proxies the request made by the user to the app.

  2. The Orchestrator checks the user’s authentication state. If it does not receive a session token, or the supplied session token is invalid, the Orchestrator sends the user to Azure AD B2C for authentication.

  3. Azure AD B2C sends the authentication request to the configured social identity provider.

  4. The identity provider challenges the user for credentials. Depending on the identity provider, the user might be required to do multi-factor authentication.

  5. The identity provider sends the authentication response back to Azure AD B2C. Optionally, the user may create a local account in the Azure AD B2C directory during this step.

  6. Azure AD B2C sends the user request to the endpoint specified during the Orchestrator app’s registration in the Azure AD B2C tenant.

  7. The Orchestrator evaluates access policies and calculates attribute values to be included in HTTP headers forwarded to the app. During this step, the Orchestrator may call out to additional attribute providers to retrieve the information needed to set the header values correctly.

  8. The Orchestrator sets the header values and sends the request to the app.

  9. The user is now authenticated and has access to the app.

Get Maverics Identity Orchestrator

To get the software you will use to integrate your legacy on-prem app with Azure AD B2C, contact Strata at [email protected].

After getting the software, follow the steps below to determine Orchestrator specific prerequisites and perform the required installation and configuration steps.

Configure Your Azure AD B2C Tenant

Register Your Application

First, you need to register the Orchestrator as an application in your Azure AD B2C tenant. Take note of the tenant name and identifier, client ID, client secret, configured claims, and redirect URI as you will need these later when you configure your Orchestrator instance.

Grant your application Graph API permissions. At a minimum, your application will need the following permissions: offline_access, openid.

Add a redirect URI for your application. This URI will match the oauthRedirectURL parameter of your Orchestrator’s Azure AD B2C connector configuration. It should look something like https://example.com/oidc-endpoint.

Create a User Flow

You will need to create a sign up and sign in flow.

Add an Identity Provider

Choose to sign in your user with either a local account or a social or enterprise identity provider.

Define User Attributes

Define the attributes to be collected during sign up.

Specify Application Claims

Specify the attributes to be returned to the application via your Orchestrator instance. The Orchestrator consumes attributes from claims returned by Azure AD B2C and can retrieve additional attributes from other connected identity systems such as LDAP directories and databases. Those attributes are set in HTTP headers and sent to the upstream on-premises application.

Configure Maverics Identity Orchestrator

In the following sections, you’ll walk through the steps required to configure your Orchestrator instance. For additional support and documentation, reach out to [email protected].

Maverics Identity Orchestrator Server Requirements

You can run your Orchestrator instance on any server, whether on-premises or in a public cloud infrastructure provider such as Azure, AWS, or GCP.

  • OS: RHEL 7.7 or higher, CentOS 7+
  • Disk: 10GB (small)
  • memory: 16GB
  • ports: 22 (SSH/SCP), 443, 80
  • root access for install/administrative tasks.
  • Maverics Identity Orchestrator runs as user maverics under systemd
  • Network egress from the server hosting Maverics Identity Orchestrator with the ability to reach your Azure AD tenant.

Install Maverics Identity Orchestrator

  1. Obtain the latest Maverics RPM package. Place the package on the system on which you’d like to install Maverics. If you are copying the file to a remote host, SCP is a useful tool.

  2. To install the Maverics package, run the following command substituting your filename in place of maverics.rpm.

    sudo rpm -Uvf maverics.rpm

    By default, Maverics is installed in the /usr/local/bin directory.

  3. After installing Maverics, it will run as a service under systemd. To verify the Maverics service is running, run the following command:

    sudo service maverics status

If the Orchestrator installation was successful, you should see a message similar to this:

  	Redirecting to /bin/systemctl status maverics.service
	● maverics.service - Maverics
	   Loaded: loaded (/etc/systemd/system/maverics.service; enabled; vendor preset: disabled)
	   Active: active (running) since Thu 2020-08-13 16:48:01 UTC; 24h ago
	 Main PID: 330772 (maverics)
	    Tasks: 5 (limit: 11389)
	   Memory: 14.0M
	   CGroup: /system.slice/maverics.service
	           └─330772 /usr/local/bin/maverics --config /etc/maverics/maverics.yaml

  1. If the Maverics service fails to start, execute the following command to investigate the problem:

    journalctl --unit=maverics.service --reverse

    The most recent log entry will appear at the beginning of the output.

After installing Maverics, the default maverics.yaml file is created in the /etc/maverics directory.

Maverics Identity Orchestrator Configuration

Next, you need to configure your Orchestrator to protect the application, integrate with Azure AD B2C, store and retrieve secrets from Azure Key Vault, and define where the Orchestrator should read its configuration.

Supplying Configuration Using Environment Variables

We recommend providing config to your Orchestrator instances through environment variables.

MAVERICS_CONFIG This environment variable tells the Orchestrator instance which YAML configuration files to use and where to find them during startup or restarts. Set the environment variable in /etc/maverics/maverics.env.

Create the Orchestrator’s TLS Configuration

The tls field in your maverics.yaml declares the transport layer security configurations your Orchestrator instance will use. Connectors can use TLS objects as well as the Orchestrator server.

The 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

Configure the Azure AD B2C Connector

Orchestrators use Connectors to integrate with authentication and attribute providers. In this case, this App Gateway uses the Azure AD B2C connector as both an authentication and attribute provider. Azure AD B2C uses the social identity provider for authentication. Then it acts as an attribute provider to the Orchestrator, passing attributes in claims set in HTTP headers.

This Connector’s configuration corresponds to the app registered in the B2C tenant.

  1. Copy the client ID, secret, and redirect URI from your app config in your tenant.

  2. Give your Connector a name, shown here as azureB2C, and set the Connector type to be azure. Take note of the Connector name as this value is used in other configuration parameters below.

  3. For this integration, the authType should be set to oidc.

  4. Set the client ID you copied in step 1 as the value for the oauthClientID parameter.

  5. Set the client secret you copied in step 1 as the value for the oauthClientSecret parameter.

  6. Set the redirect URI you copied in step 1 as the value for the oauthRedirectURL parameter.

  7. The Azure AD B2C OIDC Connector uses the well known OIDC endpoint to discover metadata, including URLs and signing keys. Set the value of oidcWellKnownURL to your tenant’s endpoint.

connectors:
  - name: azureB2C
    type: azure
    oidcWellKnownURL: https://<tenant name>.b2clogin.com/<tenant name>.onmicrosoft.com/B2C_1_login/v2.0/.well-known/openid-configuration
    oauthRedirectURL: https://example.com/oidc-endpoint
    oauthClientID: <azureB2CClientID>
    oauthClientSecret: <azureB2CClientSecret>
    authType: oidc

Protect Your On-Prem App with an App Gateway

The Orchestrator’s App Gateway configuration declares how Azure AD B2C should protect your application and how users should access the app.

  1. Create a name for your app gateway. You can use a friendly name or fully qualified hostname as an identifier for your app.

  2. Set the basePath. The example here uses the apps’s root / but this can be any URL path of your application.

  3. Define the protected application in upstream using the host:port convention: https://example.com:8080.

  4. Set the values for error and unauthorized pages.

  5. Set the IDP to determine how authentication for a user will be performed. An Identity Provider determines how to perform authentication for a user who has not presented a valid session as part of the app resource request. Configuration in your Azure AD B2C tenant determines how to challenge a user for credentials, apply additional authentication policies—for example, to require a second factor to complete the authentication process—and decide which claims should be returned to the App Gateway after authentication succeeds. The value for the idps must match your Connector’s name value.

  6. Define the HTTP header names and attribute values that must be provided to the application to establish authentication and control access to the app. Header names are arbitrary and typically correspond to the configuration of the app. Attribute values are namespaced by the Connector that supplies them. In the example below, the values returned from Azure AD B2C are prefixed with the Connector name azureB2C where the suffix is the name of the attribute that contains the required value, for example given_name.

  7. Set the policies within policies to be evaluated and enforced. Policies determine whether a given request will be allowed to proceed. Policies are associated with a location for which the policies are enforced.

Note: Both headers and policies use the createHeader service extension to implement arbitrary logic that significantly enhances the default capabilities.

appgateways:
  - name: Sonar
    basePath: /
    upstream: https://example.com:8080
    errorPage: https://example.com:8080/sonar/error
    unauthorizedPage: https://<orchestrator-host>/sonar/accessdenied

    idps:
    - name: azureB2C

    headers:
      SM_USER: azureB2C.sub
      firstname: azureB2C.given_name
      lastname: azureB2C.family_name

    policies:
      - location: /
        authentication:
          idps:
            - azureB2C

Use Azure Key Vault as Your Secrets Provider

It is critically important to secure the secrets your Orchestrator uses to connect to Azure AD B2C and any other identity system.

Maverics will default to loading secrets in plain text out of maverics.yaml, however, in this tutorial, you’ll use Azure Key Vault as the secrets provider.

Follow the instructions to create a new Vault that your Orchestrator instance will use as a secrets provider. Add your secrets to your vault and take note of the SECRET NAME given to each secret. For example, AzureB2CClientSecret.

To declare a value as a secret in a maverics.yaml config file, wrap the secret with angle brackets:

connectors:
  - name: AzureB2C
    type: azure
    oauthClientID: <AzureB2CClientID>
    oauthClientSecret: <AzureB2CClientSecret>

The value specified within the angle brackets must correspond to the SECRET NAME given to secret in your Azure Key Vault.

To load secrets from Azure KeyVault, set the environment variable MAVERICS_SECRET_PROVIDER in the file /etc/maverics/maverics.env, with the credentials found in the azure-credentials.json file, using the following pattern:

MAVERICS_SECRET_PROVIDER='azurekeyvault://<KEYVAULT NAME>.vault.azure.net?clientID=<APPID>&clientSecret=<PASSWORD>&tenantID=<TENANT>'

Putting It All Together

Here is how the Orchestrator’s configuration will appear when you complete the configurations outlined above.

version: 0.1

tls:
  maverics:
    certFile: certs/maverics.crt
    keyFile: certs/maverics.key

http:
  address: :443
  tls: maverics

connectors:
  - name: azureB2C
    type: azure
    oidcWellKnownURL: https://<tenant name>.b2clogin.com/<tenant name>.onmicrosoft.com/B2C_1_login/v2.0/.well-known/openid-configuration
    oauthRedirectURL: https://example.com/oidc-endpoint
    oauthClientID: <azureB2CClientID>
    oauthClientSecret: <azureB2CClientSecret>
    authType: oidc

appgateways:
  - name: Sonar
    basePath: /
    upstream: http://example.com:8080
    errorPage: http://example.com:8080/sonar/accessdenied
    unauthorizedPage: http://<orchestrator-host>/sonar/accessdenied

    idps:
    - name: azureB2C

    headers:
      SM_USER: azureB2C.sub
      firstname: azureB2C.given_name
      lastname: azureB2C.family_name

    policies:
      - location: /
        authentication:
          idps:
            - azureB2C

Test the Flow

  1. Open a browser and navigate to the on-premises application URL, https://example.com/sonar/dashboard.

  2. The Orchestrator should redirect to the page you configured in your user flow.

  3. Select the identity provider from the list on the page.

  4. Once you are redirected to the identity provider, supply your credentials as requested, including an MFA token if required by that identity provider.

  5. After successfully authenticating, you should be redirected to B2C, which forwards the app request to the Orchestrator redirect URI.

  6. The Orchestrator evaluates policies, calculates headers, and sends the user to the upstream application.

  7. You should see the requested application.

Sonar and Canary demo appsProtecting an API and UI