Chapter 36. Using Ansible to delegate authentication for IdM users to external identity providers

1. An IdM client user initiates OAuth 2.0 Device Authorization Grant flow, for example, by attempting to retrieve a Kerberos TGT with the kinit utility at the command line.
2. A special code and website link are sent from the Authorization Server to the IdM KDC backend.
3. The IdM client displays the link and the code to the user. In this example, the IdM client outputs the link and code on the command line.

4. The user opens the website link in a browser, which can be on another host, a mobile phone, and so on:

   1. The user enters the special code.
   2. If necessary, the user logs in to the OAuth 2.0-based IdP.
   3. The user is prompted to authorize the client to access information.
5. The user confirms access at the original device prompt. In this example, the user hits the Enter key at the command line.

6. The IdM KDC backend polls the OAuth 2.0 Authorization Server for access to user information.

   What is supported

   • Logging in remotely via SSH with the keyboard-interactive authentication method enabled, which allows calling Pluggable Authentication Module (PAM) libraries.
   • Logging in locally with the console via the logind service.
   • Retrieving a Kerberos ticket-granting ticket (TGT) with the kinit utility.

   What is currently not supported

   • Logging in to the IdM WebUI directly. To log in to the IdM WebUI, you must first acquire a Kerberos ticket.
   • Logging in to Cockpit WebUI directly. To log in to the Cockpit WebUI, you must first acquire a Kerberos ticket.

Procedure

1. On your Ansible control node, create an configure-external-idp-reference.yml playbook:

   ---
   - name: Configure external IdP
     hosts: ipaserver
     become: false
     gather_facts: false
   
     tasks:
     - name: Ensure a reference to github external provider is available
       freeipa.ansible_freeipa.ipaidp:
         ipaadmin_password: "{{ ipaadmin_password }}"
         name: github_idp
         provider: github
         client_ID: 2efe1acffe9e8ab869f4
         secret: 656a5228abc5f9545c85fa626aecbf69312d398c
         idp_user_id: my_github_account_name

   Copy to Clipboard Toggle word wrap
2. Save the file.

3. Run the Ansible playbook. Specify the playbook file, the file storing the password protecting the secret.yml file, and the inventory file:

   $ ansible-playbook --vault-password-file=password_file -v -i inventory configure-external-idp-reference.yml

   Copy to Clipboard Toggle word wrap

Procedure

1. On your Ansible control node, create an enable-user-to-authenticate-via-external-idp.yml playbook:

   ---
   - name: Ensure an IdM user uses an external IdP to authenticate to IdM
     hosts: ipaserver
     become: false
     gather_facts: false
   
     tasks:
     - name: Retrieve Github user ID
       ansible.builtin.uri:
         url: "https://api.github.com/users/my_github_account_name”
         method: GET
         headers:
           Accept: "application/vnd.github.v3+json”
       register: user_data
   
     - name: Ensure IdM user exists with an external IdP authentication
       freeipa.ansible_freeipa.ipauser:
         ipaadmin_password: "{{ ipaadmin_password }}"
         name: idm-user-with-external-idp
         first: Example
         last: User
         userauthtype: idp
         idp: github_idp
         idp_user_id: my_github_account_name

   Copy to Clipboard Toggle word wrap
2. Save the file.

3. Run the Ansible playbook. Specify the playbook file, the file storing the password protecting the secret.yml file, and the inventory file:

   $ ansible-playbook --vault-password-file=password_file -v -i inventory enable-user-to-authenticate-via-external-idp.yml

   Copy to Clipboard Toggle word wrap

1. Retrieve and store an anonymous Kerberos ticket locally.
2. Request the TGT for the idm-user-with-external-idp user by using kinit with the -T option to enable Flexible Authentication via Secure Tunneling (FAST) channel to provide a secure connection between the Kerberos client and Kerberos Distribution Center (KDC).

Procedure

1. Use Anonymous PKINIT to obtain a Kerberos ticket and store it in a file named ./fast.ccache.

   $ kinit -n -c ./fast.ccache

   Copy to Clipboard Toggle word wrap

2. Optional: View the retrieved ticket:

   $ klist -c fast.ccache
   Ticket cache: FILE:fast.ccache
   Default principal: WELLKNOWN/ANONYMOUS@WELLKNOWN:ANONYMOUS
   
   Valid starting       Expires              Service principal
   03/03/2024 13:36:37  03/04/2024 13:14:28  krbtgt/IDM.EXAMPLE.COM@IDM.EXAMPLE.COM

   Copy to Clipboard Toggle word wrap

3. Begin authenticating as the IdM user, using the -T option to enable the FAST communication channel.

   [root@client ~]# kinit -T ./fast.ccache idm-user-with-external-idp
   Authenticate at https://oauth2.idp.com:8443/auth/realms/master/device?user_code=YHMQ-XKTL and press ENTER.:

   Copy to Clipboard Toggle word wrap
4. In a browser, authenticate as the user at the website provided in the command output.
5. At the command line, press the Enter key to finish the authentication process.

Procedure

1. Attempt to log in to the IdM client via SSH.

   [user@client ~]$ ssh idm-user-with-external-idp@client.idm.example.com
   (idm-user-with-external-idp@client.idm.example.com) Authenticate at https://oauth2.idp.com:8443/auth/realms/main/device?user_code=XYFL-ROYR and press ENTER.

   Copy to Clipboard Toggle word wrap
2. In a browser, authenticate as the user at the website provided in the command output.
3. At the command line, press the Enter key to finish the authentication process.