Integrating EDQ with Azure Active Directory

Registering the EDQ Application in Azure AD

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.

To register the EDQ app in Azure AD,

In the Azure Portal, navigate to the Azure AD instance (named Default Directory by default).
In the Manage menu on the left, click App Registrations.
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)
Click Register to create the new app registration.
The Overview screen is displayed.
Copy and save the Application (client) ID. This ID is used as the Client ID for OAuth2 client credentials authentication.
Click Client credentials on the top left of the screen.
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.
Click API permissions and then click Add a permission.
Under Microsoft APIs, select Microsoft Graph.
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.
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 can now now use the application to request OAuth2 client credentials for use with Microsoft Graph REST API calls.

Parent topic: Integrating EDQ with Azure Active Directory

Enabling OpenID Connect SSO in the Application

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.

To enable SSO using OpenID Connect, follow the steps below:

In the Azure Portal, navigate to the Azure AD instance (named Default Directory by default).
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.
On the Overview screen, click Add an Application URI in the top right of the screen.
On the next screen click Add a platform.
Select Web as the platform type.
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.
Click Configure to save the URI. You can leave the other settings as is.
Click Add URI.
Enter the following URI for the EDQ instance logout flow:
https://server/edq/oidc/loggedout
Click Save at the top to save the changes.

The app registration is now ready for SSO using OpenID connect.

Parent topic: Integrating EDQ with Azure Active Directory

Enabling Multiple URI Redirects for OpenID Authentication

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.

Parent topic: Integrating EDQ with Azure Active Directory

Editing the EDQ login.properties File

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.

Before you edit login.properties, note the following:

Ensure that EDQ supports HTTPS connections.
The Marketplace images implement SSL in the Apache HTTPD front end, so no further actions are necessary.
If you are connecting to EDQ without a web front end, HTTPS must be configured in the application server.

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

Where,

- realm is the custom domain for your Azure AD instance.
- tenant is your Azure tenant ID.
- clientid and clientsecret are the values for your Azure AD application.
- proxy is the host and port of the proxy server required to access the internet from your EDQ server. If a proxy is not required, omit this setting.
- groupfilter is a Microsoft Graph $filter expression to select the groups used with EDQ. The value shown in the example returns all groups whose name starts with edq-. Refer to the Microsoft documentation for details about filtering. Omit this setting if you want all groups to be visible.
- defaultusergroup is the name of the group containing the users who work with EDQ. Here the group edq-users has been used as an example.
- extra.oidc.redirect_uri is the redirect URI entered in the Azure AD application. The URIs must match exactly.
- xgmap is the bootstrap group mapping required for admin login. Here as an example, the Azure group edq-admins is mapped to the EDQ Administrators group. You can set other group mappings in the EDQ console.

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

Parent topic: Integrating EDQ with Azure Active Directory

Enabling OAuth2 Bearer Authentication for Web Services

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.

If Azure AD is configured as the sole identity store for EDQ, the following features are not available:

Basic authentication for calls to EDQ web services.
Authentication for JMX connections.
Explicit login to the EDQ launchpad or Java applications.
Connections to the built-in SSH (SFTP/SCP) server

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:

Parent topic: Integrating EDQ with Azure Active Directory

Configuring the Azure Application to Support Bearer Authentication with EDQ

To configure the Azure application to support Bearer authentication with EDQ, follow the steps below:

In the Azure Portal, navigate to the Azure AD instance (named Default Directory by default).
In the Manage menu on the left, click App Registrations.
On the Overview screen, click Add an Application URI in the top right of the screen and click Set.
A default value such as api://1b843028-71bd-47e7-b62e-7859c0a96627 is provided, but you can use any value after api:// as long as it is unique in the Azure Directory instance.

Note:
For ease of reference, we will assume the value as api://edq for the rest of this topic.
Click Save to store the URI. You can leave the other settings as is.
OAuth2 calls to request client credentials tokens must use the scope api://edq/.default
Applications that call EDQ web services are authorized using application roles or group membership. To define roles for the existing Azure application, click App Roles and then click Create app role.
Enter a display name that is used in the portal, a value which is used for configuration, and a description.
Select Applications as the Allowed member types. For example, roles might be defined for simple web service calls and for system administration.

Parent topic: Enabling OAuth2 Bearer Authentication for Web Services

Creating Client Applications in Azure AD

Calls to EDQ using OAuth2 client credentials are made on behalf of Azure Applications.

To create an application, follow these steps:

Create an app registration as described in Registering the EDQ Application in Azure AD.
Copy and save the Application (client) ID and client secret.
If you are using App Roles for authorization in EDQ, click API permissions and then click Add a permission.
Select My APIs and click the graph+SSO application.
Select the required roles and then Grant admin consent.
The new client application is now associated with the selected roles in the graph+SSO application.
If you are using Group membership for application authorization in EDQ, select the required Azure group and add the new application as a member.

Parent topic: Enabling OAuth2 Bearer Authentication for Web Services

Editing the EDQ login.properties File to Map Roles

Add settings in login.properties to verify the audience and issuer claims in access tokens, and to add rolemap settings to map application roles to EDQ groups. Add the following to login.properties:

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

The rolemap example setting maps the administration role to the EDQ Administrators group and the callers role to the EDQ Data Stewards group. If you are using groups for application authorization in EDQ, the rolemap setting is not required.

Parent topic: Enabling OAuth2 Bearer Authentication for Web Services

Configuring Application Display in EDQ

A client application that makes a call to EDQ services using OAuth2 is allocated an internal "user" ID in the same way as for standard users. In applications, such as Case Management, that display historical information regarding user updates, an application is displayed as App: NAME where NAME is the display name of the application in Azure AD. The display format may be configured using the appusername profile property in login.properties:

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

In the property value {0} is replaced by the application name.

To enable application name display, the list of users retrieved from Azure AD is augmented with a query for applications, which uses the list servicePrincipals API. By default, applications that have never made a client call to EDQ are not included. When an application makes an initial call to EDQ, the name is not immediately available for display in Case Management. If this is a problem, the profile showallapps property can be set such that all applications are retrieved:

azure.prof.showallapps = true

The appfilter profile property can used to filter applications by name:

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

If OAuth2 client calls are not used for an installation, application listing can be disabled by setting the appfilter property to the special value 'none':

azure.prof.appfilter = none

In this case, the Graph Application.Read.All permission is not required.

Parent topic: Enabling OAuth2 Bearer Authentication for Web Services