Chapter 2. Using external identity providers to authenticate to IdM
Chapter 2. Using external identity providers to authenticate to IdM You can associate users with external identity providers (IdP) that support the OAuth 2 device authorization flow. When these users authenticate with the SSSD version available in RHEL 9.1 or later, they receive RHEL Identity Management (IdM) single sign-on capabilities with Kerberos tickets after performing authentication and authorization at the external IdP. Notable features include: Adding, modifying, and deleting references to external IdPs with ipa idp-* commands. Enabling IdP authentication for users with the ipa user-mod --user-auth-type=idp command. 2.1. The benefits of connecting IdM to an external IdP As an administrator, you might want to allow users stored in an external identity source, such as a cloud services provider, to access RHEL systems joined to your Identity Management (IdM) environment. To achieve this, you can delegate the authentication and authorization process of issuing Kerberos tickets for these users to that external entity. You can use this feature to expand IdM's capabilities and allow users stored in external identity providers (IdPs) to access Linux systems managed by IdM. 2.2. How IdM incorporates logins via external IdPs SSSD 2.7.0 contains the sssd-idp package, which implements the idp Kerberos pre-authentication method. This authentication method follows the OAuth 2.0 Device Authorization Grant flow to delegate authorization decisions to external IdPs: 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. A special code and website link are sent from the Authorization Server to the IdM KDC backend. 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. The user opens the website link in a browser, which can be on another host, a mobile phone, and so on: The user enters the special code. If necessary, the user logs in to the OAuth 2.0-based IdP. The user is prompted to authorize the client to access information. The user confirms access at the original device prompt. In this example, the user hits the Enter key at the command line. 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. Additional resources Authentication against external Identity Providers RFC 8628: OAuth 2.0 Device Authorization Grant 2.3. Creating a reference to an external identity provider To connect external identity providers (IdPs) to your Identity Management (IdM) environment, create IdP references in IdM. Complete this procedure to create a reference called my-keycloak-idp to an IdP based on the Keycloak template. For more reference templates, see Example references to different external IdPs in IdM . Prerequisites You have registered IdM as an OAuth application to your external IdP, and obtained a client ID. You can authenticate as the IdM admin account. Your IdM servers are using RHEL 9.1 or later. Your IdM servers are using SSSD 2.7.0 or later. Procedure Authenticate as the IdM admin on an IdM server. Create a reference called my-keycloak-idp to an IdP based on the Keycloak template, where the --base-url option specifies the URL to the Keycloak server in the format server-name.USDDOMAIN:USDPORT/prefix . Verification Verify that the output of the ipa idp-show command shows the IdP reference you have created. Additional resources Example references to different external IdPs in IdM Options for the ipa idp-* commands to manage external identity providers in IdM The --provider option in the ipa idp-* commands ipa help idp-add 2.4. Example references to different external IdPs in IdM The following table lists examples of the ipa idp-add command for creating references to different IdPs in IdM. Identity Provider Important options Command example Microsoft Identity Platform, Azure AD --provider microsoft --organization Google --provider google GitHub --provider github Keycloak, Red Hat Single Sign-On --provider keycloak --organization --base-url Note The Quarkus version of Keycloak 17 and later have removed the /auth/ portion of the URI. If you use the non-Quarkus distribution of Keycloak in your deployment, include /auth/ in the --base-url option. Okta --provider okta Additional resources Creating a reference to an external identity provider Options for the ipa idp-* commands to manage external identity providers in IdM The --provider option in the ipa idp-* commands 2.5. Options for the ipa idp-* commands to manage external identity providers in IdM The following examples show how to configure references to external IdPs based on the different IdP templates. Use the following options to specify your settings: --provider the predefined template for one of the known identity providers --client-id the OAuth 2.0 client identifier issued by the IdP during application registration. As the application registration procedure is specific to each IdP, refer to their documentation for details. If the external IdP is Red Hat Single Sign-On (SSO), see Creating an OpenID Connect Client . --base-url base URL for IdP templates, required by Keycloak and Okta --organization Domain or Organization ID from the IdP, required by Microsoft Azure --secret (optional) Use this option if you have configured your external IdP to require a secret from confidential OAuth 2.0 clients. If you use this option when creating an IdP reference, you are prompted for the secret interactively. Protect the client secret as a password. Note SSSD in RHEL 9.1 only supports non-confidential OAuth 2.0 clients that do not use a client secret. If you want to use external IdPs that require a client secret from confidential clients, you must use SSSD in RHEL 9.2 and later. Additional resources Creating a reference to an external identity provider Example references to different external IdPs in IdM The --provider option in the ipa idp-* commands 2.6. Managing references to external IdPs After you have created a reference to an external identity provider (IdP), you can find, show, modify, and delete that reference. This example shows you how to manage a reference to an external IdP named keycloak-server1 . Prerequisites You can authenticate as the IdM admin account. Your IdM servers are using RHEL 9.1 or later. Your IdM servers are using SSSD 2.7.0 or later. You have created a reference to an external IdP in IdM. See Creating a reference to an external identity provider . Procedure Authenticate as the IdM admin on an IdM server. Manage the IdP reference. To find an IdP reference whose entry includes the string keycloak : To display an IdP reference named my-keycloak-idp : To modify an IdP reference, use the ipa idp-mod command. For example, to change the secret for an IdP reference named my-keycloak-idp , specify the --secret option to be prompted for the secret: To delete an IdP reference named my-keycloak-idp : 2.7. Enabling an IdM user to authenticate via an external IdP To enable an IdM user to authenticate via an external identity provider (IdP), associate the external IdP reference you have previously created with the user account. This example associates the external IdP reference keycloak-server1 with the user idm-user-with-external-idp . Prerequisites Your IdM client and IdM servers are using RHEL 9.1 or later. Your IdM client and IdM servers are using SSSD 2.7.0 or later. You have created a reference to an external IdP in IdM. See Creating a reference to an external identity provider . Procedure Modify the IdM user entry to associate an IdP reference with the user account: Verification Verify that the output of the ipa user-show command for that user displays references to the IdP: 2.8. Retrieving an IdM ticket-granting ticket as an external IdP user If you have delegated authentication for an Identity Management (IdM) user to an external identity provider (IdP), the IdM user can request a Kerberos ticket-granting ticket (TGT) by authenticating to the external IdP. Complete this procedure to: Retrieve and store an anonymous Kerberos ticket locally. 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). Prerequisites Your IdM client and IdM servers use RHEL 9.1 or later. Your IdM client and IdM servers use SSSD 2.7.0 or later. You have created a reference to an external IdP in IdM. See Creating a reference to an external identity provider . You have associated an external IdP reference with the user account. See Enabling an IdM user to authenticate via an external IdP . The user that you are initially logged in as has write permissions on a directory in the local filesystem. Procedure Use Anonymous PKINIT to obtain a Kerberos ticket and store it in a file named ./fast.ccache . Optional: View the retrieved ticket: Begin authenticating as the IdM user, using the -T option to enable the FAST communication channel. In a browser, authenticate as the user at the website provided in the command output. At the command line, press the Enter key to finish the authentication process. Verification Display your Kerberos ticket information and confirm that the line config: pa_type shows 152 for pre-authentication with an external IdP. The pa_type = 152 indicates external IdP authentication. 2.9. Logging in to an IdM client via SSH as an external IdP user To log in to an IdM client via SSH as an external identity provider (IdP) user, begin the login process on the command linel. When prompted, perform the authentication process at the website associated with the IdP, and finish the process at the Identity Management (IdM) client. Prerequisites Your IdM client and IdM servers are using RHEL 9.1 or later. Your IdM client and IdM servers are using SSSD 2.7.0 or later. You have created a reference to an external IdP in IdM. See Creating a reference to an external identity provider . You have associated an external IdP reference with the user account. See Enabling an IdM user to authenticate via an external IdP . Procedure Attempt to log in to the IdM client via SSH. In a browser, authenticate as the user at the website provided in the command output. At the command line, press the Enter key to finish the authentication process. Verification Display your Kerberos ticket information and confirm that the line config: pa_type shows 152 for pre-authentication with an external IdP. 2.10. The --provider option in the ipa idp-* commands The following identity providers (IdPs) support OAuth 2.0 device authorization grant flow: Microsoft Identity Platform, including Azure AD Google GitHub Keycloak, including Red Hat Single Sign-On (SSO) Okta When using the ipa idp-add command to create a reference to one of these external IdPs, you can specify the IdP type with the --provider option, which expands into additional options as described below: --provider=microsoft Microsoft Azure IdPs allow parametrization based on the Azure tenant ID, which you can specify with the --organization option to the ipa idp-add command. If you need support for the live.com IdP, specify the option --organization common . Choosing --provider=microsoft expands to use the following options. The value of the --organization option replaces the string USD{ipaidporg} in the table. Option Value --auth-uri=URI https://login.microsoftonline.com/USD{ipaidporg}/oauth2/v2.0/authorize --dev-auth-uri=URI https://login.microsoftonline.com/USD{ipaidporg}/oauth2/v2.0/devicecode --token-uri=URI https://login.microsoftonline.com/USD{ipaidporg}/oauth2/v2.0/token --userinfo-uri=URI https://graph.microsoft.com/oidc/userinfo --keys-uri=URI https://login.microsoftonline.com/common/discovery/v2.0/keys --scope=STR openid email --idp-user-id=STR email --provider=google Choosing --provider=google expands to use the following options: Option Value --auth-uri=URI https://accounts.google.com/o/oauth2/auth --dev-auth-uri=URI https://oauth2.googleapis.com/device/code --token-uri=URI https://oauth2.googleapis.com/token --userinfo-uri=URI https://openidconnect.googleapis.com/v1/userinfo --keys-uri=URI https://www.googleapis.com/oauth2/v3/certs --scope=STR openid email --idp-user-id=STR email --provider=github Choosing --provider=github expands to use the following options: Option Value --auth-uri=URI https://github.com/login/oauth/authorize --dev-auth-uri=URI https://github.com/login/device/code --token-uri=URI https://github.com/login/oauth/access_token --userinfo-uri=URI https://openidconnect.googleapis.com/v1/userinfo --keys-uri=URI https://api.github.com/user --scope=STR user --idp-user-id=STR login --provider=keycloak With Keycloak, you can define multiple realms or organizations. Since it is often a part of a custom deployment, both base URL and realm ID are required, and you can specify them with the --base-url and --organization options to the ipa idp-add command: Choosing --provider=keycloak expands to use the following options. The value you specify in the --base-url option replaces the string USD{ipaidpbaseurl} in the table, and the value you specify for the --organization `option replaces the string `USD{ipaidporg} . Option Value --auth-uri=URI https://USD{ipaidpbaseurl}/realms/USD{ipaidporg}/protocol/openid-connect/auth --dev-auth-uri=URI https://USD{ipaidpbaseurl}/realms/USD{ipaidporg}/protocol/openid-connect/auth/device --token-uri=URI https://USD{ipaidpbaseurl}/realms/USD{ipaidporg}/protocol/openid-connect/token --userinfo-uri=URI https://USD{ipaidpbaseurl}/realms/USD{ipaidporg}/protocol/openid-connect/userinfo --scope=STR openid email --idp-user-id=STR email --provider=okta After registering a new organization in Okta, a new base URL is associated with it. You can specify this base URL with the --base-url option to the ipa idp-add command: Choosing --provider=okta expands to use the following options. The value you specify for the --base-url option replaces the string USD{ipaidpbaseurl} in the table. Option Value --auth-uri=URI https://USD{ipaidpbaseurl}/oauth2/v1/authorize --dev-auth-uri=URI https://USD{ipaidpbaseurl}/oauth2/v1/device/authorize --token-uri=URI https://USD{ipaidpbaseurl}/oauth2/v1/token --userinfo-uri=URI https://USD{ipaidpbaseurl}/oauth2/v1/userinfo --scope=STR openid email --idp-user-id=STR email Additional resources Pre-populated IdP templates
kinit admin ipa idp-add my-keycloak-idp --provider keycloak --organization main --base-url keycloak.idm.example.com:8443/auth --client-id id13778 ------------------------------------------------ Added Identity Provider reference "my-keycloak-idp" ------------------------------------------------ Identity Provider reference name: my-keycloak-idp Authorization URI: https://keycloak.idm.example.com:8443/auth/realms/main/protocol/openid-connect/auth Device authorization URI: https://keycloak.idm.example.com:8443/auth/realms/main/protocol/openid-connect/auth/device Token URI: https://keycloak.idm.example.com:8443/auth/realms/main/protocol/openid-connect/token User info URI: https://keycloak.idm.example.com:8443/auth/realms/main/protocol/openid-connect/userinfo Client identifier: ipa_oidc_client Scope: openid email External IdP user identifier attribute: email ipa idp-show my-keycloak-idp ipa idp-add my-azure-idp --provider microsoft --organization main --client-id <azure_client_id> ipa idp-add my-google-idp --provider google --client-id <google_client_id> ipa idp-add my-github-idp --provider github --client-id <github_client_id> ipa idp-add my-keycloak-idp --provider keycloak --organization main --base-url keycloak.idm.example.com:8443/auth --client-id <keycloak_client_id> ipa idp-add my-okta-idp --provider okta --base-url dev-12345.okta.com --client-id <okta_client_id> kinit admin ipa idp-find keycloak ipa idp-show my-keycloak-idp ipa idp-mod my-keycloak-idp --secret ipa idp-del my-keycloak-idp ipa user-mod idm-user-with-external-idp --idp my-keycloak-idp --idp-user-id idm-user-with-external-idp@idm.example.com --user-auth-type=idp --------------------------------- Modified user "idm-user-with-external-idp" --------------------------------- User login: idm-user-with-external-idp First name: Test Last name: User1 Home directory: /home/idm-user-with-external-idp Login shell: /bin/sh Principal name: idm-user-with-external-idp@idm.example.com Principal alias: idm-user-with-external-idp@idm.example.com Email address: idm-user-with-external-idp@idm.example.com UID: 35000003 GID: 35000003 User authentication types: idp External IdP configuration: keycloak External IdP user identifier: idm-user-with-external-idp@idm.example.com Account disabled: False Password: False Member of groups: ipausers Kerberos keys available: False ipa user-show idm-user-with-external-idp User login: idm-user-with-external-idp First name: Test Last name: User1 Home directory: /home/idm-user-with-external-idp Login shell: /bin/sh Principal name: idm-user-with-external-idp@idm.example.com Principal alias: idm-user-with-external-idp@idm.example.com Email address: idm-user-with-external-idp@idm.example.com ID: 35000003 GID: 35000003 User authentication types: idp External IdP configuration: keycloak External IdP user identifier: idm-user-with-external-idp@idm.example.com Account disabled: False Password: False Member of groups: ipausers Kerberos keys available: False kinit -n -c ./fast.ccache 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 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.: klist -C Ticket cache: KCM:0:58420 Default principal: idm-user-with-external-idp@IDM.EXAMPLE.COM Valid starting Expires Service principal 05/09/22 07:48:23 05/10/22 07:03:07 krbtgt/IDM.EXAMPLE.COM@IDM.EXAMPLE.COM config: fast_avail(krbtgt/IDM.EXAMPLE.COM@IDM.EXAMPLE.COM) = yes 08/17/2022 20:22:45 08/18/2022 20:22:43 krbtgt/IDM.EXAMPLE.COM@IDM.EXAMPLE.COM config: pa_type(krbtgt/IDM.EXAMPLE.COM@IDM.EXAMPLE.COM) = 152 [user@client ~]USD 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. [idm-user-with-external-idp@client ~]USD klist -C Ticket cache: KCM:0:58420 Default principal: idm-user-with-external-idp@IDM.EXAMPLE.COM Valid starting Expires Service principal 05/09/22 07:48:23 05/10/22 07:03:07 krbtgt/IDM.EXAMPLE.COM@IDM.EXAMPLE.COM config: fast_avail(krbtgt/IDM.EXAMPLE.COM@IDM.EXAMPLE.COM) = yes 08/17/2022 20:22:45 08/18/2022 20:22:43 krbtgt/IDM.EXAMPLE.COM@IDM.EXAMPLE.COM config: pa_type(krbtgt/IDM.EXAMPLE.COM@IDM.EXAMPLE.COM) = 152 ipa idp-add MySSO --provider keycloak --org main --base-url keycloak.domain.com:8443/auth --client-id <your-client-id> ipa idp-add MyOkta --provider okta --base-url dev-12345.okta.com --client-id <your-client-id>