sssd-idp - Man Page

This manual page describes the configuration of the IdP provider for sssd(8)​. For a detailed syntax reference, refer to the “FILE FORMAT” section of the sssd.conf(5) manual page​.

The IdP provider is a back end used to connect to an OAuth 2​.0 and REST based identity provider (IdP)​. Since products might have individual implementation of the REST API for looking up user and group attributes dedicated code might be required, see the “idp_type” option for details​.

IdPs typically do not provide POSIX attributes like e​.g​. user Id (UID) or home directory​. SSSD's IdP provider will autogenerate the needed attributes​. The default algorithm to generate user IDs (UIDs) and group IDs (GIDs) aims to create reproducible IDs on different systems​. As a drawback it might happen that the algorithm assigns the same ID to different objects and only the first one requested via SSSD will be available​.

Refer to the section “DOMAIN SECTIONS” of the sssd.conf(5) manual page for details on the configuration of an SSSD domain​.

idp_type (string)

Required option that specifies the IdP product​. Currently Entra ID (entra_id) and Keycloak (keycloak) are supported​.

Depending on the IdP product additional platform specific options might follow the name separated by a colon (:)​. E​.g​. for Keycloak the base URI for the user and group REST API must be given​. For Entra ID the base URI for the Microsoft Graph API can be given to use sovereign or government cloud endpoints instead of the default (https://graph​.microsoft​.com/v1​.0)​. E​.g​. “entra_id:https://graph​.microsoft​.us/v1​.0” for the US government cloud (GCC High)​.

Default: Not set (Required)

idp_client_id (string)

ID of the IdP client used by SSSD to authenticate users and as a client to lookup user and group attributes​. This client must offer device authorization according to RFC-8628 and must have permissions to search and read user and group attributes​.

Default: Not set (Required)

idp_client_secret (string)

Password of the IdP client​. The password is required for the id_provider​. If only used as auth_provider it depends on the server side configuration if it is required or not​.

Default: Not set

idp_token_endpoint (string)

IdP endpoint for requesting access tokens​.

Default: Not set (Required)

idp_device_auth_endpoint (string)

IdP endpoint for device authorization according to RFC-8628​. This is required for user authentication​.

Default: Not set

idp_userinfo_endpoint (string)

IdP userinfo endpoint to request user attributes after a successful authentication of the user​. Required for authentication​.

Default: Not set

idp_id_scope (string)

Scope required for looking up user and group attributes with the REST API​. The scopes are used by the server to determine which attributes/claims are returned to the caller​.

Note: In previous versions of SSSD, this option was expected to already be URL-encoded​.

Default: Not set

idp_auth_scope (string)

Scope required during authentication​. The scopes are used by the server to determine which attributes/claims are returned to the caller​.

Currently the tokens returned during user authentication are not used for other purposes hence the only important claim is the subject identifier 'sub' which is used to check if the authenticated user is the one trying to log in​. This might change in future​.

Default: Not set

idp_auth_user_identifier_attr (string)

Attribute used to identify the authenticated user in userinfo data or token claims​.

For hybrid Active Directory and Entra ID deployments where “id_provider = ad” and “auth_provider = idp”, this option must be set explicitly​. No value is derived from the identity provider, because more than one attribute can link an Entra ID object to its on-premises counterpart and only the administrator knows which one the directory synchronization is configured to use​.

Setting this option to “onPremisesImmutableId” is the usual choice for such deployments​. Microsoft Entra Connect populates that attribute with the base64-encoded form of the 16-byte Active Directory “objectGUID” when objectGUID is used as the sourceAnchor​. SSSD decodes the value and converts the raw bytes with the same conversion used for AD objectGUID attributes, so the result matches the UUID stored in the SSSD cache for the AD user​.

Note that Microsoft Entra Connect 1​.1​.524​.0 and later use “ms-DS-ConsistencyGuid” as the sourceAnchor for user objects instead of “objectGUID”​. The value is normally copied from objectGUID for objects that do not have it set yet, in which case the decoded identifier still matches​. It does not match if ms-DS-ConsistencyGuid was populated independently, if users were moved between forests or domains, or if a different attribute such as employeeID was selected as the sourceAnchor​. See Microsoft Entra Connect: Design concepts​^[1] for details on sourceAnchor selection​.

Microsoft Graph does not return “onPremisesImmutableId” by default​. The “idp_userinfo_endpoint” must request it with “$select”, see the example below and the Microsoft Graph user resource type​^[2]​.

If the configured attribute is missing or cannot be decoded (for example cloud-only Entra ID users without “onPremisesImmutableId”), authentication fails​. SSSD does not fall back to another attribute when this option is set​.

Default: not set, “sub” for Keycloak and “id” for other IdP types

idp_request_timeout (integer)

Timeout in seconds for an individual request to the IdP​.

Default: 10

idp_auto_refresh (boolean)

Refresh tokens automatically, after they have reached about half their lifetime​.

Note: Scheduled token refreshes are not preserved across restarts of SSSD​.

Default: false

idmap_range_min (integer)

Specifies the lower (inclusive) bound of the range of POSIX IDs to use for mapping IdP users and group to POSIX IDs​. It is the first POSIX ID which can be used for the mapping​.

The interval between “idmap_range_min” and “idmap_range_max” will be split into smaller ranges of size “idmap_range_size” which will be used by an individual IdP domain​.

Default: 200000

idmap_range_max (integer)

Specifies the upper (exclusive) bound of the range of POSIX IDs to use for mapping IdP users and groups to POSIX IDs​. It is the first POSIX ID which will not be used for POSIX ID-mapping anymore​.

Default: 2000200000

idmap_range_size (integer)

Specifies the number of POSIX IDs available for a single IdP domain​.

Default: 200000

[domain/entra_id]
id_provider = idp
idp_type = entra_id
idp_client_id = 12345678-abcd-0101-efef-ba9876543210
idp_client_secret = YOUR-CLIENT-SECRET
idp_token_endpoint = https://login​.microsoftonline​.com/TENANT-ID/oauth2/v2​.0/token
idp_userinfo_endpoint = https://graph​.microsoft​.com/v1​.0/me
idp_device_auth_endpoint = https://login​.microsoftonline​.com/TENANT-ID/oauth2/v2​.0/devicecode
idp_id_scope = https://graph​.microsoft​.com/​.default
idp_auth_scope = openid profile email

[domain/ad​.example​.com]
id_provider = ad
auth_provider = idp
access_provider = permit

ad_domain = ad​.example​.com
krb5_realm = AD​.EXAMPLE​.COM

idp_type = entra_id
idp_client_id = 12345678-abcd-0101-efef-ba9876543210
idp_client_secret = YOUR-CLIENT-SECRET
idp_token_endpoint = https://login​.microsoftonline​.com/TENANT-ID/oauth2/v2​.0/token
idp_userinfo_endpoint = https://graph​.microsoft​.com/v1​.0/me?$select=id,userPrincipalName,onPremisesImmutableId
idp_device_auth_endpoint = https://login​.microsoftonline​.com/TENANT-ID/oauth2/v2​.0/devicecode
idp_id_scope = https://graph​.microsoft​.com/​.default
idp_auth_scope = openid profile email
idp_auth_user_identifier_attr = onPremisesImmutableId

[domain/keycloak]
idp_type = keycloak:https://master​.keycloak​.test:8443/auth/admin/realms/master/
id_provider = idp
idp_client_id = myclient
idp_client_secret = YOUR-CLIENT-SECRET
idp_token_endpoint = https://master​.keycloak​.test:8443/auth/realms/master/protocol/openid-connect/token
idp_userinfo_endpoint = https://master​.keycloak​.test:8443/auth/realms/master/protocol/openid-connect/userinfo
idp_device_auth_endpoint = https://master​.keycloak​.test:8443/auth/realms/master/protocol/openid-connect/auth/device
idp_id_scope = profile
idp_auth_scope = openid profile email

In the hybrid Active Directory and Entra ID example above, “onPremisesImmutableId” is used during authentication so the IdP result matches the AD objectGUID UUID stored in the SSSD cache​. The attribute must be requested via “$select” on the Graph userinfo endpoint and is only populated for users synchronized from Active Directory with objectGUID as the sourceAnchor​.

sssd(8), sssd.conf(5), sssd-ldap(5), sssd-ldap-attributes(5), sssd-krb5(5), sssd-simple(5), sssd-ipa(5), sssd-ad(5), sssd-idp(5), sssd-sudo(5), sssd-session-recording(5), sss_cache(8), sss_debuglevel(8), sss_obfuscate(8), sss_seed(8), sssd_krb5_locator_plugin(8), sss_ssh_authorizedkeys(1), sss_ssh_knownhosts(1), sssd-ifp(5), pam_sss(8)​. sss_rpcidmapd(5) sssd-systemtap(5)

The SSSD upstream - https://github​.com/SSSD/sssd/

1. Microsoft Entra Connect: Design concepts
   https://learn.microsoft.com/en-us/entra/identity/hybrid/connect/plan-connect-design-concepts
2. the Microsoft Graph user resource type
   https://learn.microsoft.com/en-us/graph/api/resources/user