EDQ can integrate with Azure AD as an identity store. You need to register the EDQ app in Azure AD so that user and group queries can use the Microsoft Graph v1.0 REST APIs to access data in Azure AD.

1. In the Azure Portal, navigate to the Azure AD instance (named Default Directory by default).
2. In the Manage menu on the left, click App Registrations.
3. Click New Registration and do the following:
   • Enter a name. For example, edqgraph.
   • Select Accounts in this organizational directory only (Default Directory only - Single tenant)
4. Click Register to create the new app registration.
   The Overview screen is displayed.
5. Copy and save the Application (client) ID. This ID is used as the Client ID for OAuth2 client credentials authentication.
6. Click Client credentials on the top left of the screen.
7. Click New client secret and do the following:
   • Enter a description.
   • Select the expiry date for the client secret.
   • Click Add.
   • Copy and save the new secret value.

     Note:

     Ensure that you update the EDQ configuration before the secret expires.
8. Click API permissions and then click Add a permission.
9. Under Microsoft APIs, select Microsoft Graph.
10. The application runs as a background service and not as a real signed-in user. Do the following to set the permissions:
    • Select Application Permissions.
    • Expand Application and select Application.Read.All.
    • Expand Group and select Group.Read.All.
    • Expand User and select User.Read.All.

    Note:

    The single permission Directory.Read.All covers user, group, and application access.
11. On the API Permissions page, click Grant admin consent for Default Directory.
    This allows the application to use the permissions without further consent prompts.

You need to configure the redirect URIs to the EDQ servers to enable SSO using OpenID Connect. You can add the redirect URIs of any additional EDQ servers so that the single app registration can support multiple servers.

1. In the Azure Portal, navigate to the Azure AD instance (named Default Directory by default).
2. In the Manage menu on the left, click App Registrations and select the app you newly registered in Registering the EDQ Application in Azure AD.
3. On the Overview screen, click Add an Application URI in the top right of the screen.
4. On the next screen click Add a platform.
5. Select Web as the platform type.
6. Enter the call back URI for the EDQ instance in the following format:
   https://server/edq/oidc/callback

   where server is the host name of your EDQ installation. This URI is used to support the login flow. If a web server such as Apache HTTPD or Nginx is being used as a front end or load balancer for EDQ, enter the name of that server.

7. Click Configure to save the URI. You can leave the other settings as is.
8. Click Add URI.
9. Enter the following URI for the EDQ instance logout flow:
   https://server/edq/oidc/loggedout
10. Click Save at the top to save the changes.

The OpenID integration framework is enhanced in EDQ 12.2.1.4.3 to allow configuration of multiple redirect URIs based on the incoming host name. This allows login through the load balancer or to a specific host behind the load balancer.

You can set up logins to EDQ instances in the following ways:

• Using automatic URI: Set the redirect URL in login.properties to auto. In this case, the URL is derived from the HTTP request as https://HOST/edq/oidc/callback.

  For example, if the user refers to https://lb.example.com/edq/ the redirect URI is constructed as https://lb.example.com/edq/oidc/callback. If the user refers to https://instance1.example.com/edq/ the redirect URI is constructed as https://instance1.example.com/edq/oidc/callback. The host name is derived from reading the X-Forwarded-Host HTTP header. If X-Forwarded-Host is not present, then the Host header is used.

• Using host to URI mappings: Define a map from host name to URI in login.properties. In this case, the host name is compared against each mapping and the first match is used. In addition to the special value auto, you can use none to indicate that no redirection should take place. This allows normal internal logins to the EDQ Launchpad and other applications. For more control, the host name can be a regex, prefixed with ~. If there is no match, the default redirect URI is used.

  For example,

  azure.extra.oidc.redirect_map = localhost -> none, \
                                          testhost -> none, \
                                          myalias -> https://lb.example.com/edq/oidc/callback,
                                          ~host\\d+\.example\.com -> auto

  In this example:

  • References to https://localhost/edq/ or https://testhost/edq/ do not redirect and give direct login access.
  • References to https://myalias/edq/ use the load balancer redirect.
  • References to https://host23.example.com/edq/ redirect to https://host23.example.com/edq/oidc/callback.

User authentication in EDQ is configured using a file named security/login.properties in the EDQ configuration area. The file should be created in the "local" configuration. If the directory "security" does not exist in this location you must create it manually. You need to edit login.properties and define a realm for Azure AD.

Refer to the WebLogic or Tomcat documentation for more details.

Set login.properties as follows:

# Realms 
realms = azure 
# yourdomain.com users and groups at Azure AD 
azure.realm                   = yourdomain.com
azure.label                   = Azure AD
azure.type                    = azure 
azure.clientid                = clientid
azure.clientsecret            = clientsecret
azure.tenant                  = tenant ID
azure.proxy                   = <proxy server>:port
azure.prof.groupfilter        = startsWith(displayName, 'edq-')
azure.prof.userdisplayname    = userName
azure.prof.defaultusergroup   = edq-users 
azure.extra.oidc              = true
azure.extra.oidc.redirect_uri = https://server/edq/oidc/callback
azure.xgmap                   = edq-admins -> Administrators

After the server is restarted, references to the EDQ launchpad will redirect to the Microsoft login page.

Authentication in Azure AD is based on SSO mechanisms such as OpenID Connect and SAML. There is no support for programmatic authentication with a username and password.

To continue to use JMX (JConsole, JMXTools) connections to EDQ, the recommended approach is to enable the "internal" realm in login.properties:

realms = internal, azure

and use internal users such as "dnadmin" for JMX authentication.

For web service authentication with Azure AD, EDQ supports authentication using OAuth2 Bearer access tokens. A caller will use the client credentials or authorization code flows to acquire an access token and then pass this to EDQ in an Authorization header. For example,

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Im5PbzNa ......

User credentials obtained from the authorization code flow are mapped using the user identity in the same way as normal logins.

See the Azure documentation for more information about access tokens and token validation.

Client credentials are mapped using application roles, as described in the following sections:

• Configuring the Azure Application to Support Bearer Authentication with EDQ
  
• Creating Client Applications in Azure AD
  
• Editing the EDQ login.properties File to Map Roles
  
• Configuring Application Display in EDQ
  

azure.extra.oauth2.token.aud = api://edq
azure.extra.oauth2.token.iss = https://sts.windows.net/TENANTID/
azure.extra.oauth2.rolemap   = administration -> Administrators, callers -> Data Stewards

azure.prof.appusername = OAuth2 application: {0}

azure.prof.showallapps = true

azure.prof.appfilter   = startsWith(displayName, 'Studio')

azure.prof.appfilter = none