Red Hat Training

A Red Hat training course is available for RHEL 8

Chapter 106. Using external identity providers to authenticate to IdM

This section discusses the following topics:

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

106.1.1. 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:

  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.

106.2. 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. These 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.
--base-url
base URL for IdP templates, required by Keycloak and Okta
--organization
Domain or Organization ID from the IdP, required by Microsoft Azure

Prerequisites

  • You have registered IdM as an OAuth application to your external IdP, and obtained a client ID.

    Note

    There are two types of OAuth 2.0 clients, non-confidential and confidential. IdM supports both, however, currently, SSSD in RHEL 8.7 only supports non-confidential OAuth 2.0 clients. It is expected that an upcoming release will include a fix for this issue.

  • You can authenticate as the IdM admin account.
  • Your IdM servers are using RHEL 8.7 or later.
  • Your IdM servers are using SSSD 2.7.0 or later.

Procedure

  1. Authenticate as the IdM admin on an IdM server.

    [root@server ~]# kinit admin
  2. Create a reference to the required IdP in IdM as outlined in the following table.

    Identity ProviderImportant optionsCommand example

    Microsoft Identity Platform,
    Azure AD

    --provider microsoft
    --organization

    # ipa idp-add my-azure-idp \
      --provider microsoft \
      --organization main \
      --client-id <azure_client_id>

    Google

    --provider google

    # ipa idp-add my-google-idp \
      --provider google \
      --client-id <google_client_id>

    GitHub

    --provider github

    # ipa idp-add my-github-idp \
      --provider github \
      --client-id <github_client_id>

    Keycloak,
    Red Hat Single Sign-On

    --provider keycloak
    --organization
    --base-url

    # ipa idp-add my-keycloak-idp \
      --provider keycloak \
      --organization main \
      --base-url keycloak.idm.example.com:8443/auth \
      --client-id <keycloak_client_id>
    Note

    The Quarkus version of Keycloak 17 and later have removed the /auth/ part 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

    # ipa idp-add my-okta-idp \
      --provider okta
      --base-url dev-12345.okta.com \
      --client-id <okta_client_id>

    For example, the following command creates 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.$DOMAIN:$PORT/prefix.

    [root@server ~]# ipa idp-add my-keycloak-idp \
                     --provider keycloak --organization main \
                     --base-url keycloak.idm.example.com:8443/auth \
                     --client-id id13778
    ------------------------------------------------
    Added Identity Provider server "my-keycloak-idp"
    ------------------------------------------------
      Identity Provider server 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

Verification

  • Verify that the output of the ipa idp-show command shows the IdP reference you have created.

    [root@server ~]# ipa idp-show my-keycloak-idp

Additional resources

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

Procedure

  1. Authenticate as the IdM admin on an IdM server.

    [root@server ~]# kinit admin
  2. Manage the IdP reference.

    • To find an IdP reference whose entry includes the string keycloak:

      [root@server ~]# ipa idp-find keycloak
    • To display an IdP reference named my-keycloak-idp:

      [root@server ~]# ipa idp-show 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:

      [root@server ~]# ipa idp-mod my-keycloak-idp --secret
    • To delete an IdP reference named my-keycloak-idp:

      [root@server ~]# ipa idp-del my-keycloak-idp

106.4. 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 external-idp-user.

Prerequisites

Procedure

  • Modify the IdM user entry to associate an IdP reference with the user account:

    [root@server ~]# ipa user-mod external-idp-user \
                   --idp keycloak-server1 \
                   --idp-user-id external-idp-user@idm.example.com \
                   --user-auth-type=idp
    ---------------------------------
    Modified user "external-idp-user"
    ---------------------------------
      User login: external-idp-user
      First name: Test
      Last name: User1
      Home directory: /home/external-idp-user
      Login shell: /bin/sh
      Principal name: external-idp-user@idm.example.com
      Principal alias: external-idp-user@idm.example.com
      Email address: external-idp-user@idm.example.com
      UID: 35000003
      GID: 35000003
      User authentication types: idp
      External IdP configuration: keycloak
      External IdP user identifier: external-idp-user@idm.example.com
      Account disabled: False
      Password: False
      Member of groups: ipausers
      Kerberos keys available: False

Verification

  1. Verify that the output of the ipa user-show command for that user displays references to the IdP:

    [root@server ~]# ipa user-show external-idp-user
      User login: external-idp-user
      First name: Test
      Last name: User1
      Home directory: /home/external-idp-user
      Login shell: /bin/sh
      Principal name: external-idp-user@idm.example.com
      Principal alias: external-idp-user@idm.example.com
      Email address: external-idp-user@idm.example.com
      ID: 35000003
      GID: 35000003
      User authentication types: idp
      External IdP configuration: keycloak
      External IdP user identifier: external-idp-user@idm.example.com
      Account disabled: False
      Password: False
      Member of groups: ipausers
      Kerberos keys available: False

106.5. Retrieving an IdM ticket-granting ticket as an IdP user

To retrieve a Kerberos ticket-granting ticket (TGT) as a user from an external identity provider (IdP), request an anonymous Kerberos ticket, and enable Flexible Authentication via Secure Tunneling (FAST) channel to provide a secure connection between the Kerberos client and Kerberos Distribution Center (KDC).

Prerequisites

Procedure

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

    [root@client ~]# kinit -n -c ./fast.ccache
  2. Begin authenticating as the user, using the -T option to enable the FAST communication channel.

    [root@client ~]# kinit -T ./fast.ccache external-idp-user
    Authenticate at https://oauth2.idp.com:8443/auth/realms/master/device?user_code=YHMQ-XKTL and press ENTER.:
  3. In a browser, authenticate as the user at the website provided in the command output.
  4. 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.

    [root@client ~]# klist -C
    Ticket cache: KCM:0:58420
    Default principal: external-idp-user@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

106.6. Logging in to an IdM client via SSH as an 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

Procedure

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

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

Verification

  • Display your Kerberos ticket information and confirm that the line config: pa_type shows 152 for pre-authentication with an external IdP.

    [external-idp-user@client ~]$ klist -C
    Ticket cache: KCM:0:58420
    Default principal: external-idp-user@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

106.7. List of templates for external identity providers

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 ${ipaidporg} in the table.

--provider=google

Choosing --provider=google expands to use the following options:

OptionValue

--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:

OptionValue

--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:

[root@client ~]# ipa idp-add MySSO --provider keycloak \
    --org main --base-url keycloak.domain.com:8443/auth \
    --client-id <your-client-id>

Choosing --provider=keycloak expands to use the following options. The value you specify in the --base-url option replaces the string ${ipaidpbaseurl} in the table, and the value you specify for the --organization `option replaces the string `${ipaidporg}.

--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:

[root@client ~]# ipa idp-add MyOkta --provider okta --base-url dev-12345.okta.com --client-id <your-client-id>

Choosing --provider=okta expands to use the following options. The value you specify for the --base-url option replaces the string ${ipaidpbaseurl} in the table.

OptionValue

--auth-uri=URI

https://${ipaidpbaseurl}/oauth2/v1/authorize

--dev-auth-uri=URI

https://${ipaidpbaseurl}/oauth2/v1/device/authorize

--token-uri=URI

https://${ipaidpbaseurl}/oauth2/v1/token

--userinfo-uri=URI

https://${ipaidpbaseurl}/oauth2/v1/userinfo

--scope=STR

openid email

--idp-user-id=STR

email

Additional resources