STEP 4. Configuring Authentication Server (DEX)

The current implementation of the Authentication and Authorization feature, is based on OAuth2 authorization framework, and needs to have available an Authentication Server (DEX). The next configurations are made in the context of using the Authentication Server (DEX), which is provided in the IBM® ADDI installer.

Note: These configurations are only made if the authentication of the users, who have access to the resources, is used.

The provided Authentication Server is based on DEX and provides an authentication solution, which connects through LDAP to Secure Storage. For more information about DEX, go to the DEX documentation.

Note: DEX can be replaced by any other Authentication Server that supports the OAuth2 protocol.

Follow the configuration steps that are needed to have up and running Authentication Server (DEX):

Configure the parameters that are present in the dex.yaml file
Make Authentication Server (DEX) available in IBM AD Configuration Server
Restart Authentication Server (DEX)

1. Configure the parameters that are present in the dex.yaml file

On the machine where Authentication Server is installed, go to <IBM ADDI Installation Folder>/Authentication Server (DEX)/sample-conf/ and copy the dex.yaml file to <IBM ADDI Installation Folder>/Authentication Server (DEX)/conf/. Open the dex.yaml file by using a text editor and enter the desired values for the properties that are detailed below.

Note: The parameters are represented in YAML as mappings that consist of a parameter key and the value that is associated to that key. The format of the mapping is the parameter key represented by a string, which is terminated by a trailing colon that is followed by a space. The value for that parameter key is represented by a string that follows the key's colon and space. Example:

my_parameter: my_value

Set the issuer parameter as follows.
1. If the communication to and from DEX is done through https, the issuer parameter has the following format:
  Note: This step implies the use of certificates. If you want to set the communication to be secured, make sure that a certificate authority issues a signed certificate (.crt) and a private key for the certificate (.key).
```
https://<machine name where DEX is installed>.<machine domain>:<port>/dex
```
  Example:
```
issuer: https://WIN-ASK7V692EKB.ferdinand2.com:7600/dex
```
2. If the communication to and from DEX is done through http, the issuer parameter has the following format:
```
http://<machine name where DEX is installed>.<machine domain>:<port>/dex
```
  Example:
```
issuer: http://WIN-ASK7V692EKB.ferdinand2.com:7600/dex
```
The next section can be configured as follows:
1. If the communication to and from DEX is done through https, generate the TLS certificates for Authentication Server (DEX) and add the paths for the certificate(.crt) and the key(.key) files in the TLSCert and TLSKey fields. The default port is 7600.
```
storage:
  type: sqlite3
  config:
    file: dex.db
frontend:
  theme: addi
web:
  https: 0.0.0.0:7600
  TLSCert: C:\certs\dex.crt
  TLSKey: C:\certs\dex.key
```
2. If the communication to and from DEX is done through http, comment the TLSCert and TLSKey fields.
```
storage:
  type: sqlite3
  config:
    file: dex.db
frontend:
  theme: addi
web:
  http: 0.0.0.0:7600
  #TLSCert: 
  #TLSKey: 
```
The skipApprovalScreen parameter can be set to true or false. The true value offers the possibility to skip the "Grant access screen" after the user logs in.
```
oauth2:
  skipApprovalScreen: true
```
The connectors section can be configured as follows:
1. Set the host parameter, including the default port 389 or 636.
  The host parameter has the following format:
```
host: << IP:PORT >>
```
  Example:
```
config:
    host: WIN-NSSMI7A1KJQ.ferdinand2.com:636
```
2. The InsecureNoSSL parameter can be set as follows:
  - If the host parameter was set using the default port 389, set the InsecureNoSSL to true.
```
insecureNoSSL: true
```
  - If the host parameter was set using the default port 636, set the InsecureNoSSL to false.
```
insecureNoSSL: false
```
3. Set the bindDN parameter by adding the account that has the rights for the LDAP bind action.
  Note: To add the account that has rights for LDAP bind action run adsiedit.msc on the Active Directory machine and load the current domain. Right click on CN=Users and CN=Administrator, select Properties and search for distinguishedName attribute. For more information, see ADSI Edit (adsiedit.msc).
```
# This would normally be a read-only user.
    bindDN: CN=Administrator,CN=Users,DC=ferdinand2,DC=com
```
4. Set the bindPW parameter by adding the account's password that has the rights for the LDAP bind action.
```
bindPW: password
```
5. Do not modify the value of the usernamePrompt parameter.
```
usernamePrompt: email address
```

Under the userSearch section, only modify the value of the baseDN parameter:

Note: The baseDN parameter contains the base location of all User Accounts.

userSearch:
      baseDN: dc=ferdinand2,dc=com
      filter: "(objectClass=person)"
      username: userPrincipalName
      # "DN" (case sensitive) is a special attribute name. It indicates that
      # this value should be taken from the entity's DN not an attribute on
      # the entity.
      idAttr: DN
      emailAttr: userPrincipalName
      nameAttr: cn

Under the groupSearch section, only modify the value of the baseDN parameter:

Note: The baseDN parameter contains the base distinguished name of the groups in LDAP registry.

groupSearch:
      baseDN: cn=Users,dc=alpaca,dc=com
      filter: "(objectClass=group)"

      # A user is a member of a group when their DN matches
      # the value of a "member" attribute on the group entity.
      userAttr: DN
      groupAttr: member

      # The group name should be the "cn" value.
      nameAttr: cn

The StaticClients section, can be configured as follows:
```
staticClients:
- id: analyze-client
  redirectURIs:
  - 'http://127.0.0.1:9999/callback'
  name: 'AD Client'
  secret: 38fcbc1a-3a65-11e9-b210-d663bd873d93
```
Where:
- id is the generic name that is given for IBM AD Analyze Client.
- redirectURLs takes as value the localhost IP and a generic port that is used for callback to Authentication Server (DEX).
- name takes as value AD Client.
- secret is a secret that is shared among application.

Configuration Examples:

When the communication to and from DEX is done through https the dex.yaml file is configured as follows:

issuer: https://WIN-ASK7V692EKB.ferdinand2.com:7600/dex
storage:
  type: sqlite3
  config:
    file: dex.db

frontend:
  theme: addi
  
web:
  https: 0.0.0.0:7600
  TLSCert: C:\certs\dex.crt
  TLSKey: C:\certs\dex.key
  
oauth2:
  skipApprovalScreen: true
 
connectors:
- type: ldap
  name: ADLDAP
  id: ldap
  config:
    host: WIN-NSSMI7A1KJQ.ferdinand2.com:636

    
    # No TLS for this setup.
    insecureNoSSL: false

    # This would normally be a read-only user.
    bindDN: CN=Administrator,CN=Users,DC=ferdinand2,DC=com
    bindPW: Admin15_

    usernamePrompt: email address

    userSearch:
      baseDN: dc=ferdinand2,dc=com
      filter: "(objectClass=person)"
      username: userPrincipalName
      # "DN" (case sensitive) is a special attribute name. It indicates that
      # this value should be taken from the entity's DN not an attribute on
      # the entity.
      idAttr: DN
      emailAttr: userPrincipalName
      nameAttr: cn

    groupSearch:
      baseDN: dc=ferdinand2,dc=com
      filter: "(objectClass=group)"
      # A user is a member of a group when their DN matches
      # the value of a "member" attribute on the group entity.
      userAttr: DN
      groupAttr: member

      # The group name should be the "cn" value.
      nameAttr: cn

staticClients:
- id: analyze-client
  redirectURIs:
  - 'http://127.0.0.1:9999/callback'
  name: 'AD Client'
  secret: 38fcbc1a-3a65-11e9-b210-d663bd873d93

When the communication to and from DEX is done through http the dex.yaml file is configured as follows:

issuer: http://WIN-ASK7V692EKB.ferdinand2.com:7600/dex
storage:
  type: sqlite3
  config:
    file: dex.db

frontend:
  theme: addi
  
web:
  http: 0.0.0.0:7600
  #TLSCert: 
  #TLSKey:
  
oauth2:
  skipApprovalScreen: true
 
connectors:
- type: ldap
  name: ADLDAP
  id: ldap
  config:
    host: WIN-NSSMI7A1KJQ.ferdinand2.com:389

    
    # No TLS for this setup.
    insecureNoSSL: true

    # This would normally be a read-only user.
    bindDN: CN=Administrator,CN=Users,DC=ferdinand2,DC=com
    bindPW: Admin15_

    usernamePrompt: email address

    userSearch:
      baseDN: dc=ferdinand2,dc=com
      filter: "(objectClass=person)"
      username: userPrincipalName
      # "DN" (case sensitive) is a special attribute name. It indicates that
      # this value should be taken from the entity's DN not an attribute on
      # the entity.
      idAttr: DN
      emailAttr: userPrincipalName
      nameAttr: cn

    groupSearch:
      baseDN: dc=ferdinand2,dc=com
      filter: "(objectClass=group)"
      # A user is a member of a group when their DN matches
      # the value of a "member" attribute on the group entity.
      userAttr: DN
      groupAttr: member

      # The group name should be the "cn" value.
      nameAttr: cn

staticClients:
- id: analyze-client
  redirectURIs:
  - 'http://127.0.0.1:9999/callback'
  name: 'AD Client'
  secret: 38fcbc1a-3a65-11e9-b210-d663bd873d93

2. Make Authentication Server (DEX) available in IBM AD Configuration Server

The authentication process is conducted through DEX or through any other Authentication Server that supports the OAuth2 protocol. Authentication Server (DEX), which is delivered through the IBM ADDI installer, is an identity service that uses OpenID Connect and it is used in the following configurations.

Go to IBM AD Configuration Server and make Authentication Server (DEX) available for the other IBM AD components as follows:

Access Start Menu > IBM Application Discovery and Delivery Intelligence > Launch IBM Application Discovery Configuration Service Admin, and go to Configure > Environments > "Your environment" > Servers > Authentication Server (DEX). The Authentication Server (DEX) settings page is displayed.
Enter the following information:

Application ID

Expects the generic name that is given for IBM AD Analyze Client.

Secret

Expects a secret that is shared between Authentication Server (DEX) and IBM AD Analyze Client.

Callback URL

Expects a URL composed by localhost IP and a generic port that is used for callback to Authentication Server (DEX).

Timeout (in seconds)

Expects the time for the client to respond.

Authentication server host

Expects the authentication server host that is used by Authentication Server (DEX).

Authentication discovery path

Expects the authentication discovery path that is used by Authentication Server (DEX).
If you want to use Authentication Server (DEX), make sure that the Enable Authentication check box is selected.
Click Save.

3. Restart Authentication Server (DEX)

Once the configuration is done, go to the Dashboard tab, in IBM® AD Configuration Server, click the menu button of Authentication Server (DEX), and select Restart Service.

Note: Wait until the service is restarted, this can take a few minutes to complete.

If the service does not start, check the dex.log file under <IBM ADDI Installation Folder>/Authentication Server/ folder.