Howto14r1:Single Sign On - oAuth Login with KeyCloak

From innovaphone wiki
Jump to navigation Jump to search

If you have difficulty understanding the written language, we recommend to use https://deepl.com for translation.If installed, you can also use the translation function of your browser by right-clicking.

Applies To

  • PBX Versions 14r1 and greater

Problem Details

The situation is that you want a single sign on into myApps from your windows client.

System Requirements

  • PBX
  • Seperate Linux Debian / Ubuntu / Docker
  • Keycloak https://www.keycloak.org/
  • Admin Access to the PBX Systems
  • Admin Access to Active Directory, DNS-Server, Group Policies
  • IP Addresses and DNS of the PBX Systems

Client Requirements

Kerberos works only with:

  • myApps Windows Launcher
  • Chrome Browser
  • Edge Browser
  • (Firefox) - only with a Kerberos AddOn

Mainpoints

  • Keycloak runs on Linux Debian/Ubuntu and also in Dockerenvironment
  • Keycloak needs a Database
    • As first class databases we aim to support one traditional relational database, and a cloud native database. With this in mind we have selected PostgreSQL and CockroachDB as the best candidates.
  • https://www.keycloak.org/2022/02/dbs
  • Keycloak starts a Webserver on the System or in the Container.

Important to know

Also important to know what Protocols are needed between the Infrastructure and Keycloak in our case.

  • We need LDAP(S) to our OnPremise Active Directory - TCP 389 / 636
  • Kerberos TCP/UDP 88
  • PBX and Clients only use HTTPS to the HTTPS Port of Keycloak
  • TLS is used as Strict TLS. So you have to be sure that all TLS/SSL Communication is valid.
    • For example for LDAPS. If you have you Domaincontroller with IP-Adress 192.168.1.1 and DNS adc01.domain.org you can't do LDAPS to ldaps:192.168.1.1 because the Server Certificate is signed to the FQDN. So you have to use ldaps:adc01.domain.org:636 for LDAPS Binding.
    • Also the Certificates of the Domain-CA should be trusted from the Keycloakserver

Before you start

  • Plan your infrastructure and get an overview
  • Choose an IP for the Keycloakserver
  • Assign a valid DNS Entry to this IP => e.g. keycloak.domain.org
  • Than (after the steps before) start with installing a debian or ubuntu or ... any supported system which can run Keycloak
  • Do a basic install of keycloak
  • Login into keycloak and set needed access credentials
  • Create an REALM e.g. "innovaphone" over the UI. So we don't want to work in the Master Realm.

Steps in the Domain / Active Directory

You need an Serviceaccount in the Active Directory. This Account needs the SPN (Service Principal Name) for HTTP Protokoll to the keycloakserver. Also you need to generate an keytab file and transfer it on the Keycloakserver.

  • Creating a service account in Active Directory
  • Log in to your Active Directory server.

'Open the ‘Active Directory users and computers’. 'Create a new user account that will be used for the Keycloak service. For example: 

   User name: keycloak
   Login name: keycloak@DOMAIN.COM
  • Make sure that the account does not have the ‘Password never expires’ attribute set (optional, but recommended).

Creating a Service Principal Name (SPN)

  • command for bash: setspn -A HTTP/<hostname> DOMAIN\[username from the service account above)
    • <hostname> is the FQDN (Fully Qualified Domain Name) of the server on which Keycloak is running, and DOMAIN is the name of your Active Directory domain.
  • e.g. your keycloak server fqdn is: "keycloak.domain.org" and your Domain is "DOMAIN".
    • command for bash: setspn -A HTTP/keycloak.example.com EXAMPLE\keycloak

Generate the keytab file

Now you need to generate a keytab file that is used by Keycloak to authenticate against the Kerberos server.

The ktpass command is used to create a keytab file. Example of the command:

bash command: ktpass /out keycloak.keytab /princ HTTP/@DOMAIN.COM /mapuser DOMAIN\keycloak /crypto AES256-SHA1 /ptype KRB5_NT_PRINCIPAL /pass /kvno 0

Explanation of the parameters: 

   /out keycloak.keytab: The name of the generated keytab file.
   /princ HTTP/<hostname>@DOMAIN.COM: The complete Kerberos principal (SPN) in the format HTTP/FQDN@REALM. The realm is usually the capitalised name of your domain.
   /mapuser DOMAIN\keycloak: The user that is linked to the SPN.
   /crypto AES256-SHA1: Encryption algorithm. You can also use RC4-HMAC-NT if older encryption standards are required.
   /ptype KRB5_NT_PRINCIPAL: The type of Kerberos principal.
   /pass <password>: The password of the service account.
   /kvno 0: Key version number (can be omitted if not required).

Example

bash command: ktpass /out c:\keycloak.keytab /princ HTTP/keycloak.example.com@EXAMPLE.COM /mapuser EXAMPLE\keycloak /crypto AES256-SHA1 /ptype KRB5_NT_PRINCIPAL /pass MeinSicheresPasswort /kvno 0

  • Once the keytab file has been generated, you must transfer it to the Keycloak server. Save the file in a secure location to which the Keycloak server has access, for example in /etc/keycloak/

After that, check also the following in Active Directory

  • The Encryption has to be set to the given value of the keytab-file

Windows Client Security

  • As Kerberos to Website is not done nativly because of security topics the FQDN to Keycloak has to be assigned to the Intranet Security Zone of your Clients. This could be done via Group Policy Management

Steps in Keycloak

  • Assign a valid Certificate to the Webserver of Keycloak. All your clients have to trust this certificate.
    • Alternativly, you can assign a selfsigned certificate an set the A-Record of the DNS Name "keycloak.domain.org" to the Reverseproxy from intern and external DNS Server and route the HTTPS Traffic over the Reverse Proxy.
      • Make Sense if the Reverseprocy runs with a valid wildard for *.domain.org or if the reverse proxy uses lets encrypt
  • in the created REALM. Go to "User Federation" => "Add New Provider" => "LDAP" and fill out the LDAP Credantials (Remember the hints before to LDAPS and use the FQDN).
  • As user, use the created Service Account from above with its password.
    • You can check the bind now.

Activate Kerberos integration

  • Now the Backend is ready.
    • The next Step is a client Interface for the PBX.
    • Go to your REALM => Clients => Create Client

.

After this, it should look like:


Steps in innovaphone PBX

  • Go to PBX / Authentication and Change to "OAuth and PBX" or "OAuth Only"

Also you have to check, if the Certificate is trusted by the PBX. So please control, if the Certificate is rejected.

Result

If you have done all these Steps correct ...

  • your Client got the new security settings for the intranetzone,
    • if not, check the needed settings or try an "gpupdate /force"
  • you are logged in on your Windows Domain and reach all destinations
    • Kerberos is not working from workstations, which are not in the domain
  • you should be able now to get a automatic login into your myApps in..
    • myApps Windows Launcher
    • Chrome
    • Edge
Retrieved from "https://wiki.innovaphone.com/index.php?title=Howto14r1:Single_Sign_On_-_oAuth_Login_with_KeyCloak&oldid=76705"