OIDCProfileConfigurations

The DefiningProfileConfigurations topic discusses how Profile Configurations can be enabled at different levels of granularity. The “net.shibboleth.plugin.shibd.oidc” protocol plugin will contribute support for these profile beans into the system:

• OIDC.SSO (OpenID Connect SSO)

• OIDC.Logout (OpenID Connect Browser Single Logout) (not yet supported)

When these beans are explicitly defined rather than used via automatic registration, their individual settings become subject to control at whatever level of granularity is needed. The following is a brief summary and (heavily excerpted) examples of a few of the more important or commonly-needed settings available. Complete reference information is available at OIDCSettingsReference.

Browser SSO Settings

useRequestObject

(TODO: make this just about the settings, not the context, move that)

Typically, all OAuth 2.0 and hence OIDC authorization request parameters are sent from the SP to the OpenID Provider as URL parameters. This has several possible limitations:

• Aside from some transport-level protections afforded by TLS, there are no application-level cryptographic assurances that the parameters have not been tampered with between the SP issuing the request and the OpenID Provider receiving it. For example, by a malicious web browser extension.

• URL length limits may be exceeded, especially if the request includes a complex Claims (TODO claimslink) parameter.

• Any sensitive information contained in parameters can end up exposed in browser history and server logs.

To provide integrity and confidentiality for a request, OIDC defines a request parameter that can encode a Request Object JWT to secure authorisation request parameters, prevent tampering, and provide confidentiality. This can be enabled globally for all requests using the sp.oidc.requestobject.used property, or per relying party:

When enabled, the OpenID Provider must support the use of the request parameter, which it advertises in its metadata document using the request_parameter_supported value; otherwise, the SP will fall back to plain OAuth 2.0 request parameters. Request parameters that are contained in the Request Object JWT supersede those passed by OAuth 2.0 URL request parameters.

OAuth 2.0 and OpenID Connect also support the request_uri parameter (defined in RFC 9101), which allows the Service Provider to host a Request Object and pass only a reference to it in the authorization request. The OpenID Provider then retrieves the Request Object over a back‑channel (server‑to‑server), rather than receiving the full request via the front‑channel redirect.

For more information about signing and encrypting the request object, see (TODO: break that out from the RP-Proxy)

The use of the Request Object is perhaps rare in practice, unless working in a ‘high-security’ environment and wanting to conform to an OAuth2.0 profile like FAPI.

scopes

In OIDC, OAuth 2.0 scopes are used to request specific sets of information to be exposed as claim values. These claims are typically returned in the UserInfo response. Scopes may either be provided by the Agent or managed individually on the Hub.

The openid scope is added automatically to signify to the OpenID Provider that this is an OpenID Connect request.

retrieveUserInfoEndpointClaims

The ID Token returned by the OpenID Provider during the authentication flow contains End-User identity claims about who authenticated and how they authenticated. If you want to obtain additional user profile attributes, for example, email, preferred name, you’ll likely need to obtain these from the UserInfo endpoint:

It is important to note that the ID Token can carry profile claims or any arbitrary claims, so enabling the UserInfo endpoint may not always be necessary.

TODO: for more information about handling the UserInfo response, see YYY.

disallowedFeatures

There are a number of bitmask constants defined that regulate what OIDC options an Agent is permitted to send to the Hub to override behavior, whether defaulted or explicit, when making OIDC requests. By default, Agents are given permission to control these options (mostly for legacy compatibility reasons). Most commonly, if you were to set such an option within the Hub explicitly, you would tend to also want to restrict the ability for Agents to override it.

Options controllable include these beans:

• OIDC.SSO.FEATURE_ESSENTIAL_ACR_REQUEST

• OIDC.SSO.FEATURE_LOGIN_HINT

• OIDC.SSO.FEATURE_FORCEAUTHN

• OIDC.SSO.FEATURE_RESOURCE_INDICATOR

• OIDC.SSO.FEATURE_SCOPE

To set more than one, you use a Set as the property value with each bit you want set:

authnContextClassRefs

The Authentication Context Class Reference (acr) claim in OpenID Connect (OIDC) is analogous to the SAML <AuthnContextClassRef> element and is used to indicate the level or strength of authentication that was performed.

The semantics of requesting specific ACR values depend on whether the OpenID Provider (OP) supports the claims parameter. If the OP supports the claims parameter, the ACR will be requested as essential, meaning that the OP must perform an authentication meeting the requested ACR value; otherwise, it must return an error response.

If the OP does not support the claims parameter, the ACR is requested on a voluntary basis, and the OP is not required to enforce or satisfy the requested authentication strength.

In the higher education sector, the REFEDS MFA Profile is an example of a value designed for interoperable signalling:

(TODO, add authnContextClassRefs to RP profile config)

ACR responses can be evaluated at the Hub or be sent to the Agent for checking/enforcement. By default, the Hub validates that any of the mandatory (essential) ACR claims requested are returned in the id_token. This can be disabled:

You’d then need to ensure the ACR is filtered and returned to the Agent for interrogation.

extractStandardAttributes

As with the SAML version, the OIDC plugin can also emulate the population of “special/standard” variables that the legacy SP uses, as discussed in SAMLBasics.

The default value of this setting is controlled by the global property sp.oidc.extractStandardAttributes, which is false by default. Related properties control the names of the IdPAttributes created.