Integrating EDQ with Cognito User Pools

Creating the User Pool

EDQ can integrate with Amazon Cognito user pool as an identity store. User and group logins happen using Amazon Cognito REST APIs. To use EDQ with Amazon Cognito, you need to first create a user pool using the Amazon Cognito console.

To create an Amazon Incognito user pool, follow these steps.

Login to the Amazon Cognito console. If prompted, enter your AWS credentials.
Choose User Pools.
In the top-right corner of the page, choose Create a user pool to open the wizard. You can also use an existing user pool.
Choose your password policy, multi-factor authentication (MFA) requirements, and user account recovery options.
Configure user sign-up experience to determine how new users will verify their identities when signing up. Ensure that email and name are selected as required attributes. Cognito does not provide a default "Organization" attribute. If this is required for EDQ, create a custom attribute.
Configure user message delivery as required to send email and SMS messages to your users for sign-up, account confirmation, MFA, and account recovery. There is no need to configure message delivery if users will be created by administrators with preset initial passwords.
In Integrate your app, name your user pool, configure the hosted UI, and create an app client. For more information, see Add an App to Enable the Hosted Web UI
In Integrate your app, select Confidential client as the type, and ensure that Generate a client secret is selected.
In Allowed callback URLs enter https://server/edq/oidc/callback
If you wish to use an existing user pool, you can add a new App client supporting the Authorization code grant flow and configure the callback URLs. You can add additional callback URLs after the pool is created to allow multiple EDQ instances to be supported.
In Advanced app client settings, add https://server/edq/oidc/loggedout as an allowed sign-out URL.

If you are using WebLogic, it may be necessary to include the port number in the sign-out URL. Add https://server:443/edq/oidc/loggedout as an additional sign-out URL.
Review your choices in the summary screen and click Create user pool to proceed.

Parent topic: Integrating EDQ with Cognito User Pools

Creating an IAM User for REST API Calls

Calls to the Cognito REST APIs are authenticated with standard AWS request signatures. We recommend that you create an IAM user with only the permissions needed by EDQ. First create an IAM policy with the required permissions. Create an IAM user and attach the new policy, either directly or via a group. Create credentials for the user and note the key and associated secret.

Parent topic: Integrating EDQ with Cognito User Pools

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 Cognito.

Before you edit login.properties, click App client information in the user pool summary and copy the Client ID and Client secret.

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 = cognito

cognito.realm                   = yourdomain.com
cognito.label                   = Cognito user pool
cognito.type                    = cognito

cognito.region                  = eu-west-1
cognito.pool                    = eu-west-1_z9wkvtsPx
cognito.proxy                   = proxyserver:port
cognito.access_key              = AKIAVWUKAYEFKZM7GFVU
cognito.access_secret           = lapirJ3l8n4+lD43TCDReFXexS....
cognito.prof.defaultusergroup   = edq-users
cognito.xgmap                   = edq-admins -> Administrators

cognito.extra.oidc              = true
cognito.extra.oidc.clientid     = 2p4st7jlu6ne49rchiump9ulqc
cognito.extra.oidc.clientsecret = ...
cognito.extra.oidc.redirect_uri = https://server/edq/oidc/callback

Where,

realm is the domain you wish to use with your Amazon Cognito user pool.
region is the user pool region.
pool is the user pool ID.
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.
access_key and access_secret to the access key and secret for the IAM user.
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.clientid and extra.oidc.clientsecret are the values for your user pool app client.
extra.oidc.redirect_uri is the redirect URI entered in the Cognito application. The URIs must match exactly.
xgmap is the bootstrap group mapping required for admin login. Here as an example, the Cognito 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 Cognito login page. You can provide your own login page or customize the standard page using CSS.

User Attribute Selection

Parent topic: Integrating EDQ with Cognito User Pools

User Attribute Selection

Internal and external users in EDQ are represented by a username, email address, full name (such as John Smith), telephone number, and organization name. Full name, telephone, and organization are stored as "vcard" attributes, to allow for future expansion. When integrating with Cognito user pools these values are derived by reading attributes from user objects:

Value	Cognito user attribute	Overriding property in login.properties
username	Username	cognito.prof.usernameattr
email address	email	cognito.prof.vcard.email.pref
full name	name	cognito.prof.vcard.fn
telephone number	phone_number	cognito.prof.vcard.tel.work
organization		cognito.prof.vcard.org

Cognito does not have a standard Organization attribute. If you defined a custom attribute for this when the user pool was created, you can refer to it in login.properties. For example:

cognito.prof.vcard.org = custom:organization

vcard. properties can specify multiple attributes. The first attribute with a non-empty value is used as the result. For example, if there are custom organization and department attributes, you can set the following:

cognito.prof.vcard.org = custom:department custom:organization

You can also configure a cognito.prof.userdisplayname property. The value is an expression constructed from user attributes. The resulting value is used whenever a user is displayed in EDQ. If not set, username@realm is used. For example john.smith@yourdomain.com. If the user name is an email address, or you have only a single realm, you can override cognito.prof.userdisplayname to use a different attribute. For example, set the following to use the user name as the display name:

cognito.prof.userdisplayname = Username

The value is an expression so that you can specify more exotic values. For example, set the following to create values such as john.smith (John Smith):

cognito.prof.userdisplayname = Username || ' (' || name || ')'

Parent topic: Editing the EDQ login.properties File

Enabling OAuth2 Bearer Authentication for Web Services

EDQ integration with Cognito user pools is based on SSO mechanisms such as OpenID Connect SSO authentication. There is no support for programmatic authentication with a username and password.

If Cognito 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 server

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

realms = internal, cognito

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

For web service authentication with Cognito, 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 eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Im5PbzNaRHJPRFhFSzFqS1doWHNs......

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

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

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

Parent topic: Integrating EDQ with Cognito User Pools

Configuring Custom Scopes in the User Pool

Authorization for client credentials calls is done by mapping custom OAuth2 scopes to EDQ groups. The first step is to create the required custom scopes in the user pool.

To configure custom scopes in the user pool:

In the Resource servers section of the user pool properties click Create resource server.
Enter a Resource server name and Resource server identifier. The URI does not refer to a real server instance so you can use a simple URI such as urn:edq.
Click Add custom scope.
Enter a Scope name and description.
Click Create.

Parent topic: Enabling OAuth2 Bearer Authentication for Web Services

Configuring Client Credentials Application

After you have added the custom scopes in the user pool, you need to map them in the user pool properties.

To configure client credentials:

In the user pool properties, create a new client.
Select Confidential client and ensure that Generate a client secret is enabled.
Remove the callback URL and select Client credentials as the OAuth 2.0 grant type.
In the Custom scopes section, select the scope you defined with the resource server in Configuring Custom Scopes in the User Pool.

Parent topic: Enabling OAuth2 Bearer Authentication for Web Services

Configuring EDQ

In login.properties add scopemap settings to map scopes to EDQ groups:

cognito.extra.oauth2.scopemap = urn:edq/callws -> Data Stewards

Here scopemap maps the urn:edq/callws custom scope to the EDQ Data Stewards group.

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, which display historical information regarding user updates, an application is displayed as App: NAME where NAME is the display name of the application client. The display format may be configured using the appusername profile property in login.properties:

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

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

To enable application name display, the list of users retrieved from Cognito is augmented with a query for application clients, which uses the ListUserPoolClients API. By default, application clients 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 showapps property can be set to "all" so that all applications are retrieved.

cognito.prof.showapps = all

To disable application listing, set showapps to "none". In this case, the IAM user does not need to have the ListUserPoolClients permission.

cognito.prof.showapps = none

Parent topic: Enabling OAuth2 Bearer Authentication for Web Services