Foreman SSO with Microsoft Entra ID

Tutorials
,
1

Hi guys,

I’ve currently managed to get user authentication working using OIDC directly from Entra ID. I’ve seen this issue come around on the community a couple times, no one seems to have got this working, so I thought I’d share the steps I took to configure it.
There are a few holes in this, haven’t got a few things like like app-initiated IDP sign-out and pulling in groups from Entra ID working, but at a very base level I’ve got user authentication and user auto-creation working. Below are the steps I took to configure this, both on the Entra and Foreman side. This has been tested on Foreman 3.11, with both Foreman and Foreman-Katello installs.

Configuring Entra ID

  1. In the Entra admin center, navigate to Identity → Applications → App registrations.

  2. Create a new app registration. Give the application a name (e.g. Foreman). Configure the Redirect URI to “Web” and “https://your-foreman-fqdn/users/extlogin/redirect-uri". Click “Register”.

  • Take note of the Application ID and Tenant ID, you’ll need them later.

  1. Navigate to Authentication. Enable ID tokens and click “Save”.

  2. Navigate to Certificates & secrets. Generate a new client secret.

  • Take note of the Client Secret you just generated, you’ll need it later.

  1. Navigate to Token configuration. Click “Add optional claim” and add the “email”, “given_name”, “family_name”, and
    “preferred_username” claims. You will need to turn on the MS Graph “email” and “profile”
    permissions when prompted.

  2. Navigate to API permissions. Grant admin consent for your organisation to the MS Graph API permissions.

Configuring Foreman

  1. Install the OIDC module.
dnf install -y mod_auth_openidc
  1. Create the OIDC config file for Apache in /etc/httpd/conf.d/05-foreman-ssl.d/example_openidc.conf
OIDCProviderMetadataURL https://login.microsoftonline.com/<tenant-id>/v2.0/.well-known/openid-configuration
OIDCClientID <application-ID>
OIDCClientSecret <application-secret>
OIDCRedirectURI https://<your-foreman-fqdn>/users/extlogin/redirect_uri
OIDCCryptoPassphrase <random-string>
OIDCRemoteUserClaim preferred_username
OIDCScope "openid email profile"
OIDCResponseType id_token

<Location /users/extlogin>
    AuthType openid-connect
    Require valid-user
    LogLevel debug

    RequestHeader set REMOTE_USER %{OIDC_CLAIM_preferred_username}e
    RequestHeader set REMOTE_USER_EMAIL %{OIDC_CLAIM_email}e
    RequestHeader set REMOTE_USER_FIRSTNAME %{OIDC_CLAIM_given_name}e
    RequestHeader set REMOTE_USER_LASTNAME %{OIDC_CLAIM_family_name}e
</Location>
  1. Load the authn_core_module and authz_user_module, by adding the following lines in /etc/httpd/conf.modules.d/10-auth_openidc.conf.
LoadModule authn_core_module modules/mod_authn_core.so
LoadModule authz_user_module modules/mod_authz_user.so
  1. Navigate to Administer → Settings → Authentication in the Foreman Web UI, and configure
    the following settings;

Authorize login delegation = Yes
Authorize login delegation auth source user autocreate = External
OIDC JWKs URL = https://login.microsoftonline.com/*tenant-id*/discovery/v2.0/keys
OIDC Audience = application-ID
OIDC Issuer = https://login.microsoftonline.com/*tenant-id*/v2.0
OIDC Algorithm = RS256

  1. Restart the Apache Web Server
systemctl restart httpd
  1. Test at https://your-foreman-fqdn/users/extlogin
5 Likes
2

Great write up, thanks for sharing @theunofficalyvonne!

Do you know if the configuration steps can be achieved through our installer options too? I guess the OIDC setup should be possible since Keycloak support for introduced. The benefit of that approach would be, that the configuration wouldn’t get overridden on subsequent installer run, e.g. on Foreman upgrade.

1 Like
3

Hi there!

Wow that’s pretty nice that it’s finally working now! :slight_smile:
Last time I looked into it, the certificate chain broke everything.

Just to make this doesn’t break the next time when you run foreman-installer, you need to call the httpd config file in a specific way: i.e. foreman-openidc_oidc_keycloak_Foreman_Realm.conf (Keycloak OIDC Prerequisites)
If you don’t do that, foreman-installer will delete that file on the next run again.
+ the foreman-installer --foreman-keycloak true --foreman-keycloak-app-name "foreman-openidc" --foreman-keycloak-realm "*Foreman_Realm*" command might be necessary to be run to make it stick :+1:

Glad you could make it work, will have to test that soon :slight_smile:

1 Like
4

Hey @Marek_Hulan,
As far as I’m aware, no (or not easily/not documented), based on what I’ve come across.
Looks like @lumarel addressed the concern, RE: losing the configuration on next installer run, in his reply (greatly appreciated!), I have yet to confirm in my environment (watch this space).
Like I said before, there are definitely a few holes in this method, I’ll update as I have more answers.

5

I have it somehow working but the Foreman stucks on “The page you were looking fore doesn’t exist”

In the Foreman logs I can see

ActionController::RoutingError (No route matches [GET] “/users/extlogin/redirect_uri”):

Any ideas?

6

looks like it doesn’t work if you have your system enrolled into freeIPA.

7

I got Foreman to leverage user groups it receives from the id_token acquired from an Entra IdP

<Location /users/extlogin>
  AuthType openid-connect
  Require valid-user
  Loglevel debug

  RequestHeader set REMOTE_USER %{OIDC_CLAIM_preferred_username}e
  RequestHeader set REMOTE_USER_EMAIL %{OIDC_CLAIM_email}e
  RequestHeader set REMOTE_USER_FIRSTNAME %{OIDC_CLAIM_given_name}e
  RequestHeader set REMOTE_USER_LASTNAME %{OIDC_CLAIM_family_name}e
  # Pass the roles into Foreman from the roles in the id_token
  RequestHeader set REMOTE_USER_GROUPS %{OIDC_CLAIM_roles}e
</Location>

If you already have user groups that inherit the desired roles you can add an external user group to the user group with a name that matches the OIDC_CLAIM_roles value being passed from the IdP

Since you have the LogLevel set to debug you can see what values apache is receiving from the IdP in the apache logs