Skip to content

AttributeEncoderPluginConfiguration

Jump to bottom
Scott Cantor edited this page Feb 16, 2021 · 64 revisions

This page documents oidc extension specific attribute encoders. Reader is assumed to be familiar with Shibboleth IdP 3 AttributeEncoderPluginConfiguration. In the simplest form not much is different from the case of resolving attributes to SAML responses. If you have a resolved attribute and want to release it as a oidc claim, you need to attach oidc specific attribute encoder to it.

Example

Attaching a oidc encoder for mail attribute.

    <AttributeDefinition xsi:type="Simple" id="mail" sourceAttributeID="mail">
        <Dependency ref="myLDAP" />
        <AttributeEncoder xsi:type="SAML1String" name="urn:mace:dir:attribute-def:mail" encodeType="false" />
        <AttributeEncoder xsi:type="SAML2String" name="urn:oid:0.9.2342.19200300.100.1.3" friendlyName="mail" encodeType="false" />
        <AttributeEncoder xsi:type="oidcext:OIDCString" name="email" />
    </AttributeDefinition>

Endpoint Attribute Resolving Principle

Some cases are less straight forward than the previous example though. Authorize, Token and Userinfo endpoints all go trough attribute resolution and filtering phases. The motivation for this is to create as stateless as possible OIDC implementation. Each endpoint is able to resolve attributes independently and therefore information of the attributes to be released needs not to be stored to server side. This guarantees also up to date values for claims returned if access token is refreshed for extended period of time.

There are few obvious downsides in this stateless approach though. One is that depending on the response type same attribute may be resolved more than once. This is particularly awkward if the attribute is costly and the intention is only to authenticate the user. If there are such costly attributes use solution like ResultCache for instance. The second is that attribute resolution phases in Token and Userinfo endpoints are not able to resolve attributes based on session/context information as it is not available. This places a requirement of robustness to your attribute resolvers. Your resolvers must not expect the session/contexts information to be always available but should instead fail gracefully and give up the task. For this type of attributes there is a setToToken flag that instructs Authorize endpoint to encode the attributes unsolvable in later phases to Authorization Code and or Access Token directly thus making them available for Token and Userinfo endpoints. This naturally increases the size of the code/token.

Schema Name and Location

Attribute encoders are specified with the xsi:type attribute in a <AttributeEncoder> . The oidc extension encoder types are defined in the org.geant.idpextension.oidc.attribute.encoder schema, which is located at https://github.com/CSCfi/shibboleth-idp-oidc-extension/blob/master/idp-oidc-extension-impl/src/main/resources/schema/idp-oidc-extension-attribute-encoder.xsd and used by the reference installation from classpath:/schema/idp-oidc-extension-attribute-encoder.xsd

Common Attributes to all oidc encoders

  • activationConditionRef
  • asArray, set values to JSON Array. Default value is "false".
  • stringDelimiter, delimiter used when catenating multiple values to single string. Default is " ".
  • setToToken, Default is "false". If set to true the value is encoded to Authorization Code or to Access/Refresh Token to ensure availability in Token and Userinfo endpoints. Note that the code / token is always opaque to the client. Client notices only that the code / token may be bit longer than usually.
  • placeToIDToken, Default is "false". By default attributes are delivered in userinfo response unless response type is "id_token". Setting the flag true will include attribute in id token regardless of response type.
  • denyUserinfo, Default is "false". By default attributes are delivered in userinfo response unless response type is "id_token". Setting the flag true excludes attribute from userinfo response.

AttributeEncoder Plugin Types

Configuring Attributes Using IdP4 Attribute Registry

The following applies when using attribute registry introduced in Shibboleth IdP version 4 with OIDC plugin version 2. It is an alternative method to the attribute resolver configuration documented above.

Example

    <bean parent="shibboleth.TranscodingProperties">
        <property name="properties">
            <props merge="true">
            <prop key="id">cn</prop>
            <prop key="transcoder">SAML2StringTranscoder SAML1StringTranscoder OIDCStringTranscoder</prop>
            <prop key="saml2.name">urn:oid:2.5.4.3</prop>
            <prop key="saml1.name">urn:mace:dir:attribute-def:cn</prop>
            <prop key="oidc.name">cn</prop>
            <prop key="oidc.inToken">true</prop>
            <prop key="displayName.en">Common name</prop>
            <prop key="description.en">Common name of a person</prop>
            </props>
        </property>
    </bean>

Available transcoders

Currently transcoders may be used to encode attributes to a relying party. Decoding attributes from an authenticating OpenID Provider is not supported.

  • OIDCStringTranscoder
  • OIDCScopedStringTranscoder
  • OIDCByteTranscoder

Available options

  • oidc.asArray whether to encode data to JSON array. Default is "false".
  • oidc.asInteger whether to encode data to JSON integer. Default is "false".
  • oidc.asBoolean whether to encode data to boolean. Default is "false".
  • oidc.stringDelimiter separator to use when not encoding multiple values to array. Default is " ".
  • oidc.inToken whether to encode data into authorization code and access token. Default is "false".
  • oidc.forceIDToken whether to forcibly include data in ID token regardless of response type. Default is "false".
  • oidc.denyUserInfo whether to deny inclusion in user_info token regardless of response type. Default is "false".

(Migrated)

Clone this wiki locally