Versions Compared

Old Version 22

changes.mady.by.user svc_ayfie_onedrive@ayfie.com

Saved on

compared with

New Version Current

changes.mady.by.user svc_ayfie_onedrive@ayfie.com

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Markdown
- [Introduction](#introduction)
- [Prerequisites](#prerequisites)
- [Configure Active Directory User Federation](#configure-active-directory-user-federation)
- [Configuring Single Sign-On](#configuring-single-sign-on)
- [How to Import thePrivate Certificate Authority Root Certificate](#how-to-import-the-#private-certificate-authority-root-certificate)

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

## Prerequisites

- The **LDAP connection URL** to the Active Directory domain, for instance *ldaps://dc01.company.internal*
- The **Users DN**. That is, the full distinguished name (DN) of the LDAP tree where users are stored, for instance *OU=Users, DC=company, DC=internal*
- Create an **Active Directory service account** with Domain User permissions (in the rest of this documentation we will assume that the user was given the name *svcSagaKeycloak*).
    - 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 the Certificate Authority (CA)_ldaps_ connection is notusing a well-known CA. For instance if the certificate is made by the customer's own IT departmentSSL certificate issued by a private Certificate Authority. See [How to Import thePrivate Certificate Authority Root Certificate](#how-to-import-the#private-certificate-authority-root-certificate) for details.

For Single Sign-On there are these additional prerequisites:
- 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)
  - 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)
- UpGo into the*User leftFederation* corner,menu makeoption
sure it is the Saga realm that is being displayed
- Go to *User Federation* menu option
- An *Add Provider* list box will appear- Click *Add new provider*. Select the *LDAP* provider type and the provider's settings page will appear
- Adjust the settings to these values:
  - *ConsoleUI Display Name*: **Active Directory**
  - *ImportConnection UsersURL*: **ON**
  - *Edit Mode*: **READ_ONLY**\<the LDAP connection URL from the prerequisite section above\>**
  - *SyncBind RegistrationsDN*: **OFF**
  - *Vendor*: **Active Directory\<the Bind DN from the prerequisite section above\>**
  - *UsernameBind LDAP attributeCredential*: **sAMAccountName**
  - *Connection URL*: **\<the LDAP connectionPassword URL from the prerequisite section above\>**
  - *Edit Mode*: **READ_ONLY**
  - *Users DN*: **\<the Users DN from the prerequisite section above\>**
  - *Custom UserUsername LDAP Filterattribute*: **(&sAMAccountName**
  - *User LDAP Filter*: **(&(objectCategory=Person)(sAMAccountName=\*))**
    - If one wants to filter users to be imported by a specific Active Directory Group, then extend the filter with a memberOf clause. For example, given that one wants 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))* .
  - *Search Scope*: **Subtree**
  - *BindSync DNRegistrations*: **OFF**\<the
 Bind DN- from*Periodic theChanged prerequisiteUser section above\>Sync*: **ON**
- Click -the *BindTest Credential*: **\<the Password from the prerequisite section above\>**
- Click the *Test connection* connection* and *Test authentication* buttons to verify the configuration.
- Click *Save*
- Go back to the page that was just saved (select *User Federation* and then *Active Directory*)
- Go to Mappers tab:
  - Click *username* mapper and verify the setting:
    - *LDAP Attribute*: **sAMAccountName**
    - Click *Save* and go back up a level
  - Click *Add CreateMapper*
    - *Name*: **user**
    - *Mapper Type*: **user-attribute-ldap-mapper**
    - *User Model Attribute*: **user**
    - *LDAP Attribute*: **sAMAccountName**
    - Click *Save* and go back up a level
  - Click *Add CreateMapper*
    - *Name*: **source**
    - *Mapper Type*: **hardcoded-attribute-mapper**
    - *User Model Attribute*: **source**
    - *Attribute Value*: **ad**
    - Click *Save* and go back up a level
  - Click Create*Add Mapper*
    - *Name*: **upn**
    - *Mapper Type*: **user-attribute-ldap-mapper**
    - *User Model Attribute*: **upn**
    - *LDAP Attribute*: **sAMAccountName**
    - Click *Save* and go back up a level
- GoIn to Settings tab
 the Actions drop-down, select *Sync all users*.
- Click *Synchronize all usersUsers* in section *Manage* atin the bottomleft ofside themenu
page   - ExpandPerform thea *Syncsearch Settings*and sectionvalidate that users -are *Periodicimported Changedto User Sync*: **ON**
  - Click Save
- Click *Users* in section *Manage* in the left side menu
  - Click *View all users* and validate that users are imported to the internal database

## Configuring Single Sign-On

This configuration is optional and only required if one wants to enable 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)
- Go to User Federation menu option and choose *Active Directory*.
- Go to Kerberos Integration section and adjust settings:
    - *Allow Kerberos Authentication*: **ON**
    - *Kerberos Realm*: **\<UPPER_CASE_AD_DOMAIN_NAME\>**
    - *Server Principal*: **HTTP/\the internal database

## Configuring Single Sign-On

This configuration is optional and only required if one wants to enable 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)
- Go to User Federation menu option and choose *Active Directory*.
- Go to Kerberos Integration section and adjust settings:
    - *Allow Kerberos Authentication*: **ON**
    - *Kerberos Realm*: **\<UPPER_CASE_AD_DOMAIN_NAME\>**
    - *Server Principal*: **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, andclick adjusts the settings *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.

## HowPrivate Certificate Authority
to
ImportIf the Certificate_ldaps_ Authorityconnection Rootis Certificateusing a ThisSSL iscertificate theissued procedureby fora extracting theprivate Certificate Authority (CA), the private CA root certificate fromneeds theto domain controller and importing it into Saga. This is only required if the CA is not a well-known authoritybe 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 EnterCertificate *certlm.msc* inAuthority* section of the program search box down in the left corner (or alternatively find the tool via the *Manage Computer Certificate* option in the *Control Panel*)
- Select *Trusted Root Certification* from the list that appears in the left pane
- In the right window, click on *Certificates*
- Find the Root CA from the list of certificates
- Click on the certificate to open it and then click the *Details* tab.
- Select *Copy To File...* and then next the *DER encoded binary X.509 (.CER)* option in the export wizard.
- Store the file under any name but with the required .cer extension
- Copy the file to *D:\Program Files\ayfie\saga\volumes\authority\docker-entrypoint.d* (the path assumes the recommended install directory)
- Restart the Authority Service using this command from *D:\Program Files\ayfie\saga\docker*:
  ```
  docker stop ayfie-saga-authority
  docker rm ayfie-saga-authority
  docker-compose up -d ayfie-saga-authority
  ```[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.