Skip to content

SubjectIDConfiguration

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

Overview

Subject Identifier is a locally unique and never reassigned identifier for the user. It differs from other user claims by the fact that it's presence is always required in id token and userinfo responses. There are two types of subject identifiers, public and and pairwise. If the OP is able to generate both kind of identifiers, client may select the type in registration phase.

Public Subject Identifier is same for each client. It is a case sensitive string of less than 256 ASCII characters. It may be opaque like "AItOawmwtWwcT0k51BayewNvutrJUqsvl6qs7A4" or have plain text form like "tedtester".

Pairwise Subject Identifier is also case sensitive string of less than 256 ASCII but it is different to each client or to group of clients. It must not be reversible to any actual user.

Configuration

Subject Identifier value is any value of any attribute that will be encoded as claim "sub". There must always be exactly one such attribute remaining after filtering phase. The provided example configuration has attribute and data connector defined to generate both public and pairwise subject identifiers for the clients.

<AttributeDefinition id="subject" xsi:type="Simple" activationConditionRef="SubjectRequired">
    <InputDataConnector ref="computedSubjectId" attributeNames="subjectId"/>
    <AttributeEncoder xsi:type="oidcext:OIDCString" name="sub" />
</AttributeDefinition>

<DataConnector id="computedSubjectId" xsi:type="ComputedId"
        generatedAttributeID="subjectId"
        sourceAttributeID="%{idp.oidc.subject.sourceAttribute}"
        salt="%{idp.oidc.subject.salt}"
        algorithm="%{idp.oidc.subject.algorithm:SHA}"
        encoding="%{idp.oidc.subject.encoding:BASE32}">
        <Dependency ref="%{idp.oidc.subject.sourceAttribute}"/>
</DataConnector>

Both the public and pairwise identifier generated by the default setup are opaque to client. The data connector generates automatically correct content (public/pairwise) for the identifier based on client's registration information.

Note the activation condition in the attribute definition. The purpose of the activation condition is not to regenerate the subject in token and userinfo endpoints. Loosing the activation condition and regenerating the subject in each endpoint does not break anything but the logs may become misleading. Also, it should be safe to apply the activation condition in the case attribute is used by some other protocol.

Configuration oidc-subject.properties

  • idp.oidc.subject.sourceAttribute - Comma-delim'd List. List of attributes to search for a value to uniquely identify the subject of a persistent identifier, it MUST be stable, long-lived, and non-reassignable
  • idp.oidc.subject.algorithm - String, defaults to SHA. The hash algorithm used when using computed subject IDs
  • idp.oidc.subject.salt - String. A secret salt for the hash when using computed persistent IDs

Beans

  • SubjectRequired - Activation Condition that returns false in token and userinfo endpoints as subject needs to be resolved only in authorization endpoint.
  • PublicRequired - Activation Condition that returns true if client has registered need for public subject and attribute resolving is performed by authorization endpoint.
  • PairwiseRequired - Activation Condition that returns true if client has registered need for pairwise subject and attribute resolving is performed by authorization endpoint.

Changing the way subject is generated

Subject Identifier is value of any attribute that will be encoded as claim "sub". This means that it may also be quite freely configured for as long as the requirement of having exactly one such attribute remaining after filtering phase in authentication endpoint is fulfilled.

<AttributeDefinition id="subject-public" xsi:type="Simple" sourceAttributeID="uid" activationConditionRef="PublicRequired">
    <Dependency ref="uid" />
    <AttributeEncoder xsi:type="oidcext:OIDCString" name="sub" />
</AttributeDefinition>

<AttributeDefinition id="subject-pairwise" xsi:type="Simple" activationConditionRef="PairwiseRequired">
    <InputDataConnector ref="computedSubjectId" attributeNames="subjectId"/>
    <AttributeEncoder xsi:type="oidcext:OIDCString" name="sub" />
</AttributeDefinition>

This example definition creates a non-opaque public type of subject and uses the provided data connector to generate pairwise type of subject. Note the use of activation conditions to select always one or the other per client's registration data.

(Migrated)

Clone this wiki locally