Page Comparison

- [Introduction](#introduction)
- [Prerequisites](#prerequisites)
- [Configure Active Directory User Federation](#configure-active-directory-user-federation)
- [Configuring Active Directory With LDAPSSingle Sign-On](#configuring-activesingle-directorysign-with-ldapson)
  - [ExportingPrivate Certificate Authority From The Domain Controller](#exporting#private-certificate-authority-from-the-domain-controller)
- [Configuring Single Sign-On](#configuring-single-sign-on)

## Introduction

The Authority Service can be configured to sync up with external user databases to provide single-sign on in two ways:

- Via User Federation (the method used to sync up with Active Directory)
- Via Identity Brokering (the method used to sync up with Azure Active Directory)

This documentation describes how to set the Authority Service up to do user federation with Active Directory.

Once the Authority Service has been set up to sync with Active Directory, the Authority Service will upon a user login first try to find the user in its internal user database. If the user is not there, the Authority Service will then retrieve the user's data from Active Directory and store it internally.
In
addition to this type of on-demand syncing, the Authority Service can also be configured to do the syncing as a scheduled background task.

## Prerequisites

- The **LDAP connection URL** to the Active Directory domain. It could be , for exampleinstance *ldaps://dc01.company.internal* or *ldap://dc01.company.internal
- The **Users DN**. - TheThat is, the full distinguished name (DN) of the LDAP tree where users are stored. The DN is the parent of LDAP users, for instance *OU=Users, DC=company, DC=internal*.
- AnCreate an **Active Directory service account** whichwith willDomain beUser usedpermissions by(in the Authorityrest Serviceof tothis accessdocumentation Activewe Directory.will assume that the user was -given In Active directory create user namedthe name *svcSagaKeycloak*). The
user only requires Domain User- permissions.
    - Once the user is made, run a *dsquery* command to get the Bind DN string (ie.The **password** of service account *svcSagaKeycloak*
    - The **Bind DN** string of service account *svcSagaKeycloak*, for instance *CN=svcSagaKeycloak,OU=ServiceAccounts,OU=Users,DC=company,DC=internal*
- Import the **Private Certificate Authority root certificate** if  _ldaps_ connection is using a SSL certificate issued by a private Certificate Authority. See [Private Certificate Authority](#private-certificate-authority) for details.

For ##Single ConfigureSign-On Activethere Directoryare Userthese Federationadditional prerequisites:
- Go to the Authority Service Admin Console, consult *Configuring the Authority Service* in the [Install The output file **keycloak.keytab** from running the command below with a Domain Admin user
  ```
  ktpass -out keycloak.keytab -princ HTTP/<GATEWAY_HOSTNAME>@<UPPER_CASE_AD_DOMAIN_NAME> -mapUser <USER_NAME>@<UPPER_CASE_AD_DOMAIN_NAME> -pass <USER_PASSWORD> -kvno 0 -ptype KRB5_NT_PRINCIPAL -crypto <CRYPTO>
  ```
  - The Saga **\<GATEWAY_HOSTNAME\>**, for instance *search.company.com*. See Section *Gateway Hostname* of the [Ayfie Locator Installation Guide](#https://ayfie-dev.atlassian.net/wiki/spaces/SAGA/pages/2400714758/Ayfie+Locator+Installation+Guide).
  - Up in the left corner, make sure it is the Saga realm that is being displayed.
- Go to User Federation menu option
- On the right side, there is a list box labeled Add Provider. Select the LDAP provider type and you will be sent to the provider's settings page.
- Adjusts settings:
  - In Console Display Name, enter the display name *Active Directory*.
  - In Vendor, choose *Active Directory*.
  - In Import Users, set to *On*. Authority Service will import users into the internal database.
  - In Edit Mode, set to *Read Only*. You will be unable to modify the username, email address, first and last names, or any other mapped attributes. Updates to passwords are not supported.
  - In Sync registrations, set to *Off*. Users created in Authority Service will not be synced back to Active Directory.
  - In Username LDAP attribute, set to *sAMAccountName*. This will set username of imported user to it’s Active Directory user name.
  - In Custom User LDAP Filter, set to The **\<UPPER_CASE_AD_DOMAIN_NAME\>**, for instance *COMPANY.INTERNAL*
  - The service user **\<USER_NAME\>**, for instance *svcSagaKeycloak*
  - The service user **\<USER_PASSWORD\>**, for instance *super_secret*
  - The encryption type to use **\<CRYPTO\>**, for instance *AES256-SHA1*
    - See [ktpass](https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/ktpass) for the supported encryption types
    - One must make sure the chosen encryption type is allowed in the domain, see article [Network security: Configure encryption types allowed for Kerberos](https://learn.microsoft.com/en-us/windows/security/threat-protection/security-policy-settings/network-security-configure-encryption-types-allowed-for-kerberos)

## Configure Active Directory User Federation

- Log in to the Authority Service Admin Console (section *Configuring the Authority Service* of the [Ayfie Locator Install Guide](#https://ayfie-dev.atlassian.net/wiki/spaces/SAGA/pages/2400714758/Ayfie+Locator+Installation+Guide) explains how)
- Go to *User Federation* menu option
- Click *Add new provider*. Select the *LDAP* provider type and the provider's settings page will appear
- Adjust the settings to these values:
  - *UI Display Name*: **Active Directory**
  - *Connection URL*: **\<the LDAP connection URL from the prerequisite section above\>**
  - *Bind DN*: **\<the Bind DN from the prerequisite section above\>**
  - *Bind Credential*: **\<the Password from the prerequisite section above\>**
  - *Edit Mode*: **READ_ONLY**
  - *Users DN*: **\<the Users DN from the prerequisite section above\>**
  - *Username LDAP attribute*: **sAMAccountName**
  - *User LDAP Filter*: **(&(objectCategory=Person)(sAMAccountName=\*))* This will only import users with sAMAccountName attribute set.
    **
    - If one wantwants to filter users to be imported by a specific Active Directory Group, then extend the filter with a memberOf clause. For example, given that youone wantwants to import users in the *SagaUsers* group only and the distinguished name of that group is *CN=SagaUsers,OU=Groups,DC=company,DC=internal*, then use following filter *(&(objectCategory=Person)(sAMAccountName=\*)(memberOf=CN=SagaUsers,OU=Groups,DC=company,DC=internal))* .
  - In Connection URL, set the LDAP connection URL.
  - In *Search Scope, set to *: **Subtree**.
  - In Bind DN and Bind Credential, set with the Active Directory service user created in prerequisites.*Sync Registrations*: **OFF**
  - *Periodic Changed User Sync*: **ON**
- Click the *Test connection* and *Test authentication* buttons andto verify validatethe successconfiguration.
- Click *Save*
- Go back to the page that was just saved (select *User Federation menu option* and choosethen *Active Directory*.)
- Go to Mappers tab:
  - Click *username* mapper to edit.and verify the setting:
    - In *LDAP Attribute, set to *: **sAMAccountName*.*
    - Click Save.*Save* and go back up a level
  - Click Create.*Add Mapper*
    - In *Name,*: set **user*.*
    - In *Mapper Type,*: set **user-attribute-ldap-mapper*.*
    - In *User Model Attribute,*: set **user**.
    - In *LDAP Attribute,*: set **sAMAccountName**.
    - Click Save.*Save* and go back up a level
  - Click Create. *Add Mapper*
    - In *Name,*: set **source*.*
    - In *Mapper Type,*: set **hardcoded-attribute-mapper**.
    - In *User Model Attribute*: Name*, set *source*.*
    - In *Attribute Value,*: set **ad*.*
    - Click Save.*Save* and go back up a level
  - Click Create. *Add Mapper*
    - In *Name,*: set **upn**.
    - In *Mapper Type,*: set **user-attribute-ldap-mapper**.
    - In *User Model Attribute,*: set **upn*.*
    - In *LDAP Attribute,*: set **sAMAccountName*.*
    - Click Save.
- Go to Settings tab.
  - Click *Syncronize*Save* and go back up a level
- In the Actions drop-down, select *Sync all users*.
  - GoClick to*Users* Syncin Settings section   - Configure Syncronization method. The recommended method is *Periodic Changed User Sync*.
  - Click Save.
- Go to Users menu option.
  - Click *View all users**Manage* in the left side menu
  - Perform a search and validate that users are imported to the internal database.

## Configuring ActiveSingle DirectorySign-On
With
LDAPSThis configuration Activeis Directoryoptional userand federationonly throughrequired LDAPSif requiresone thatwants theto domainenable controller has a valid SSL certificate issued by a well-known authority. Otherwise the Certificate Authority has to be manually imported into the Authority Service.

To import the certificate, copy the certificate file Single Sign-On, something that is done via Kerberos.
- Copy the keycloak.keytab file from the prerequisite section above to *D:\Program Files\ayfie\saga\volumes\authority\docker-entrypoint.d\* (the path assumes recommended install directory)
and- thenGo restartto theUser AuthorityFederation Service.menu option ###and Exportingchoose Certificate Authority From The Domain Controller

To export Certificate Authority from the domain controller, do the following:
 - Open control panel.*Active Directory*.
- Go to Kerberos Integration section and adjust settings:
    - Open *ManageAllow ComputerKerberos CertificatesAuthentication*.
 - Go to *Trusted Root Certification* and find the Root CA.: **ON**
    - Open the certificate, go to details.*Kerberos Realm*: **\<UPPER_CASE_AD_DOMAIN_NAME\>**
    - Select*Server Principal*Copy To File...* and then the *DER encoded binary X.509 (.CER)* option in the export wizard.

## Configuring Single Sign-On

**_NOTE:_** This configuration is optional. Perform following steps only if you want to enable Kerberos Single Sign-On.

- Run the following command on domain controller to assign a SPN to the user and generate a keytab file:

  ```
  ktpass -out keycloak.keytab -princ HTTP/GatewayHostName@COMPANY.INTERNAL -mapUser svcSagaKeycloak@COMPANY.INTERNAL -pass password! -kvno 0 -ptype KRB5_NT_PRINCIPAL -crypto RC4-HMAC-NT
  ```
    - Replace *GatewayHostname*, with the Gateway Hostname set in Saga, see [Install Guide](#https://ayfie-dev.atlassian.net/wiki/spaces/SAGA/pages/2400714758/Ayfie+Locator+Installation+Guide).
    - Replace *COMPANY.INTERNAL* with the Active Directory domain name.
    - Replace *svcSagaKeycloak@COMPANY.INTERNAL* with the service user created in [Prerequisites](#prerequisites).
- Copy keycloak.ktab file to *D:\Program Files\ayfie\saga\volumes\authority\docker-entrypoint.d\* (the path assumes recommended install directory).
- Go to User Federation menu option and choose *Active Directory*.
- Go to Kerberos Integration section and adjust settings:
    - In Allow Kerberos Authentication, set to *On*.
    - In Kerberos Realm, set  domain name ie. *COMPANY.INTERNAL*
    - In Server Principal, set according to SPN set on domain user (ie. HTTP/locator.internal@COMPANY.INTERNAL)
    - In Keytab, set *c:\docker-entrypoint.d\keycloak.ktab*.
    - In Use Kerberos For Password Authentication, set to *On*.
    - Click Save.

An additional requirement is that the FQDN used to access Saga applications, has to be added to the Local Intranet Zone on the client machines (unless this already happens automatically for all domain users).: **HTTP/\<Gateway Hostname\>@\<UPPER_CASE_AD_DOMAIN_NAME\>**)
    - *Keytab*: **c:\docker-entrypoint.d\keycloak.keytab**
    - *Use Kerberos For Password Authentication*: **ON**
- Click *Save*
- Go to *Authentication* menu option, click the *browser* flow and adjusts the settings to these values:
  - *Kerberos*: **Alternative**

An additional requirement is that the FQDN used to access Saga applications, has to be added to the Local Intranet Zone on the client machines (unless this already happens automatically for all domain users) for Edge and Chrome browsers. For Firefox one must make sure the setting *network.negotiate-auth.trusted-uris* in *about:config* contains the *\<Gateway Hostname\>* from the prerequisites section.

## Private Certificate Authority

If the _ldaps_ connection is using a SSL certificate issued by a private Certificate Authority (CA), the private CA root certificate needs to be imported into the authority service Docker container. Such cases will produce an "unable to find valid certification path to requested target" error message in the logs (service.log). The most typical such use case is when the customer's own IT department operates as the CA. Consult the *Private Certificate Authority* section of the [Installation Guide](https://ayfie-dev.atlassian.net/wiki/spaces/SAGA/pages/2400714758/Ayfie+Locator+Installation+Guide) for how to import the private CA root certificate.