OpenLDAP schema upgrade

This is an instruction how to upgrade the LDAP schema for a Connect2id server 2.x installation to Connect2id server 3.x if an OpenLDAP directory backend is used.

The schema changes

Summary of the schema changes:

Adds new boolean authzAccessTokenEncrypt attribute to authorisation records. Used to indicate whether the access tokens for a long-lived (persisted) authorisation must be encrypted.
Adds new authzRefreshTokenLifetime attribute to authorisation records. Used to enable optional refresh token expiration.
Adds new authzRefreshTokenIssueDate attribute to authorisation records. Used to enable optional refresh token expiration.
Modifies the authzRefreshTokenSalt attribute for authorisation records. Adds an authzRefreshTokenSecret alias which is made the main attribute name.

The client registration schema has not been changed in Connect2id server 3.x.

Note that existing directory records are compatible with the new schema. The schema changes simply facilitate some new features introduced in Connect2id server 3.x. Therefore, no migration of existing data is needed.

The LDAP schemas for the Connect2id server are made available in a dedicated Git repo. They have their version numbers:

Connect2id server 2.x: LDAP schema version 1.0
Connect2id server 3.x: LDAP schema version 1.4

The on-line configuration in OpenLDAP

OpenLDAP uses on-line configuration (OLC) to enable schema changes with zero downtime. This is facilitated by storing the configuration in a special directory tree at the cn=config root, which may be viewed and modified with a regular LDAP client / browser.

Accessing the schema

Access to the cn=config directory tree requires administrator permissions and can be facilitated in two ways:

From the command line on the OpenLDAP host: from a superuser account (e.g. via sudo).
Remotely from an LDAP client by making a connection to the OpenLDAP server: with the admin DN and password credentials; these are typically set up by the administrator when the OpenLDAP directory is created.

If you’re using a generic LDAP client, such as Apache Directory Studio, the connection must be authenticated with the root DN and password, and the cn=config tree must be specified (otherwise the client will connect to the default data tree).

Locate the authorisation records schema

Before we can update the authorisation records schema we must find out its DN (record address) on the cn=schema, cn=config directory branch. The schema names are prefixed by a number, such as {1}, to indicate their precedence when the OpenLDAP server loads them (in case they have dependent attributes).

From the command line on the OpenLDAP host:

sudo ldapsearch -Q -LLL -Y EXTERNAL -H ldapi:/// -b cn=schema,cn=config '(cn=*oidcAuthz)' dn

If you’re using a remote LDAP connection make a search request under the cn=schema,cn=config branch using the (cn=*oidcAuthz) filter.

Write down the search result, that is the DN of the OpenID Connect authorisation records schema, e.g.

cn={5}oidcAuthz,cn=schema,cn=config

Modify the authorisation records schema

Important: Try this first on a test or development LDAP directory. Proceed with production when you’re sure the upgrade works correctly and there are no issues with your particular OpenLDAP setup.

Step 1.

Apply the following LDIF file upgrade the attribute definitions.

Remember to replace the dn: cn={5}oidcAuthz... with the actual DN of the authorisation schema that you recorded above!

dn: cn={5}oidcAuthz,cn=schema,cn=config
changetype: modify
replace: olcAttributeTypes
olcAttributeTypes: (  1.3.6.1.4.1.40805.2.1.1 NAME 'authzAccessToken'
        DESC 'OAuth 2.0 access token'
        EQUALITY caseExactMatch
        ORDERING caseExactOrderingMatch
        SUBSTR caseExactSubstringsMatch
        SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
        SINGLE-VALUE
        USAGE userApplications
        X-ORIGIN 'OAuth 2.0' )
olcAttributeTypes: (  1.3.6.1.4.1.40805.2.1.2 NAME 'authzAccessTokenLifetime'
        DESC 'OAuth 2.0 access token lifetime, in seconds'
        EQUALITY integerMatch
        ORDERING integerOrderingMatch
        SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
        SINGLE-VALUE
        USAGE userApplications
        X-ORIGIN 'OAuth 2.0' )
olcAttributeTypes: (  1.3.6.1.4.1.40805.2.1.3 NAME 'authzAccessTokenEncoding'
        DESC 'OAuth 2.0 access token encoding'
        EQUALITY caseExactMatch
        ORDERING caseExactOrderingMatch
        SUBSTR caseExactSubstringsMatch
        SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
        SINGLE-VALUE
        USAGE userApplications
        X-ORIGIN 'OAuth 2.0' )
olcAttributeTypes: (  1.3.6.1.4.1.40805.2.1.23 NAME 'authzAccessTokenEncrypt'
        DESC 'OAuth 2.0 access token encrypt flag'
        EQUALITY booleanMatch
        SYNTAX 1.3.6.1.4.1.1466.115.121.1.7
        SINGLE-VALUE
        USAGE userApplications
        X-ORIGIN 'OAuth 2.0' )
olcAttributeTypes: (  1.3.6.1.4.1.40805.2.1.4 NAME 'authzRefreshToken'
        DESC 'OAuth 2.0 refresh token'
        EQUALITY caseExactMatch
        ORDERING caseExactOrderingMatch
        SUBSTR caseExactSubstringsMatch
        SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
        SINGLE-VALUE
        USAGE userApplications
        X-ORIGIN 'OAuth 2.0' )
olcAttributeTypes: (  1.3.6.1.4.1.40805.2.1.5 NAME ('authzRefreshTokenSecret' 'authzRefreshTokenSalt')
        DESC 'OAuth 2.0 refresh token salt'
        EQUALITY caseExactMatch
        ORDERING caseExactOrderingMatch
        SUBSTR caseExactSubstringsMatch
        SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
        SINGLE-VALUE
        USAGE userApplications
        X-ORIGIN 'OAuth 2.0' )
olcAttributeTypes: (  1.3.6.1.4.1.40805.2.1.6 NAME 'authzIssueRefreshToken'
        DESC 'OAuth 2.0 issue refresh token switch'
        EQUALITY booleanMatch
        SYNTAX 1.3.6.1.4.1.1466.115.121.1.7
        SINGLE-VALUE
        USAGE userApplications
        X-ORIGIN 'OAuth 2.0' )
olcAttributeTypes: (  1.3.6.1.4.1.40805.2.1.24 NAME 'authzRefreshTokenLifetime'
        DESC 'OAuth 2.0 refresh token lifetime, in seconds'
        EQUALITY integerMatch
        ORDERING integerOrderingMatch
        SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
        SINGLE-VALUE
        USAGE userApplications
        X-ORIGIN 'OAuth 2.0' )
olcAttributeTypes: (  1.3.6.1.4.1.40805.2.1.25 NAME 'authzRefreshTokenIssueDate'
        DESC 'Refresh token issue date'
        EQUALITY generalizedTimeMatch
        ORDERING generalizedTimeOrderingMatch
        SYNTAX 1.3.6.1.4.1.1466.115.121.1.24
        SINGLE-VALUE
        USAGE userApplications
        X-ORIGIN 'OAuth 2.0' )
olcAttributeTypes: (  1.3.6.1.4.1.40805.2.1.7 NAME 'authzIssuer'
        DESC 'Authorization issuer'
        EQUALITY caseExactMatch
        ORDERING caseExactOrderingMatch
        SUBSTR caseExactSubstringsMatch
        SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
        SINGLE-VALUE
        USAGE userApplications
        X-ORIGIN 'OAuth 2.0' )
olcAttributeTypes: (  1.3.6.1.4.1.40805.2.1.8 NAME 'authzIssueDate'
        DESC 'Authorization issue date'
        EQUALITY generalizedTimeMatch
        ORDERING generalizedTimeOrderingMatch
        SYNTAX 1.3.6.1.4.1.1466.115.121.1.24
        SINGLE-VALUE
        USAGE userApplications
        X-ORIGIN 'OAuth 2.0' )
olcAttributeTypes: (  1.3.6.1.4.1.40805.2.1.9 NAME 'authzUpdateDate'
        DESC 'Authorization issue date'
        EQUALITY generalizedTimeMatch
        ORDERING generalizedTimeOrderingMatch
        SYNTAX 1.3.6.1.4.1.1466.115.121.1.24
        SINGLE-VALUE
        USAGE userApplications
        X-ORIGIN 'OAuth 2.0' )
olcAttributeTypes: (  1.3.6.1.4.1.40805.2.1.10 NAME 'authzSubject'
        DESC 'Authorization subject'
        EQUALITY caseExactMatch
        ORDERING caseExactOrderingMatch
        SUBSTR caseExactSubstringsMatch
        SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
        SINGLE-VALUE
        USAGE userApplications
        X-ORIGIN 'OAuth 2.0' )
olcAttributeTypes: (  1.3.6.1.4.1.40805.2.1.11 NAME 'authzClientID'
        DESC 'Authorized client'
        EQUALITY caseExactMatch
        ORDERING caseExactOrderingMatch
        SUBSTR caseExactSubstringsMatch
        SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
        SINGLE-VALUE
        USAGE userApplications
        X-ORIGIN 'OAuth 2.0' )
olcAttributeTypes: (  1.3.6.1.4.1.40805.2.1.12 NAME 'authzAudience'
        DESC 'Authorized audience'
        EQUALITY caseExactMatch
        ORDERING caseExactOrderingMatch
        SUBSTR caseExactSubstringsMatch
        SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
        USAGE userApplications
        X-ORIGIN 'OAuth 2.0' )
olcAttributeTypes: (  1.3.6.1.4.1.40805.2.1.13 NAME 'authzScopeValue'
        DESC 'Authorized scope value'
        EQUALITY caseExactMatch
        ORDERING caseExactOrderingMatch
        SUBSTR caseExactSubstringsMatch
        SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
        USAGE userApplications
        X-ORIGIN 'OAuth 2.0' )
olcAttributeTypes: (  1.3.6.1.4.1.40805.2.1.14 NAME 'authzSavedScopeValue'
        DESC 'Saved scope value from a previous authorisation'
        EQUALITY caseExactMatch
        ORDERING caseExactOrderingMatch
        SUBSTR caseExactSubstringsMatch
        SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
        USAGE userApplications
        X-ORIGIN 'OAuth 2.0' )
olcAttributeTypes: (  1.3.6.1.4.1.40805.2.1.15 NAME 'authzData'
        DESC 'Auxiliary authorization data, as JSON object'
        EQUALITY caseExactMatch
        ORDERING caseExactOrderingMatch
        SUBSTR caseExactSubstringsMatch
        SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
        SINGLE-VALUE
        USAGE userApplications
        X-ORIGIN 'OAuth 2.0' )
olcAttributeTypes: (  1.3.6.1.4.1.40805.2.1.16 NAME 'authzLastAccessDate'
        DESC 'Authorization last access date'
        EQUALITY generalizedTimeMatch
        ORDERING generalizedTimeOrderingMatch
        SYNTAX 1.3.6.1.4.1.1466.115.121.1.24
        SINGLE-VALUE
        USAGE userApplications
        X-ORIGIN 'OAuth 2.0' )
olcAttributeTypes: (  1.3.6.1.4.1.40805.2.1.17 NAME 'oidcIDToken'
        DESC 'OpenID Connect ID token'
        EQUALITY caseExactMatch
        ORDERING caseExactOrderingMatch
        SUBSTR caseExactSubstringsMatch
        SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
        SINGLE-VALUE
        USAGE userApplications
        X-ORIGIN 'OpenID Connect 1.0' )
olcAttributeTypes: (  1.3.6.1.4.1.40805.2.1.18 NAME 'oidcClaimName'
        DESC 'Consented OpenID Connect claim name, with optional language tag'
        EQUALITY caseExactMatch
        ORDERING caseExactOrderingMatch
        SUBSTR caseExactSubstringsMatch
        SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
        USAGE userApplications
        X-ORIGIN 'OpenID Connect 1.0' )
olcAttributeTypes: (  1.3.6.1.4.1.40805.2.1.19 NAME 'oidcSavedClaimName'
        DESC 'Saved consented OpenID Connect claim name from a previous authorisation, with optional language tag'
        EQUALITY caseExactMatch
        ORDERING caseExactOrderingMatch
        SUBSTR caseExactSubstringsMatch
        SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
        USAGE userApplications
        X-ORIGIN 'OpenID Connect 1.0' )
olcAttributeTypes: (  1.3.6.1.4.1.40805.2.1.20 NAME 'oidcClaimsLocales'
        DESC 'OpenID Connect claims locales, space separated, by order of preference'
        EQUALITY caseExactMatch
        ORDERING caseExactOrderingMatch
        SUBSTR caseExactSubstringsMatch
        SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
        SINGLE-VALUE
        USAGE userApplications
        X-ORIGIN 'OpenID Connect 1.0' )
olcAttributeTypes: (  1.3.6.1.4.1.40805.2.1.21 NAME 'oidcPresetUserInfoClaims'
        DESC 'Preset OpenID Connect UserInfo claims, as JSON object'
        EQUALITY caseExactMatch
        ORDERING caseExactOrderingMatch
        SUBSTR caseExactSubstringsMatch
        SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
        SINGLE-VALUE
        USAGE userApplications
        X-ORIGIN 'OpenID Connect 1.0' )
olcAttributeTypes: (  1.3.6.1.4.1.40805.2.1.22 NAME 'oidcSessionID'
        DESC 'Subject session identifier (SID)'
        EQUALITY caseExactMatch
        ORDERING caseExactOrderingMatch
        SUBSTR caseExactSubstringsMatch
        SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
        SINGLE-VALUE
        USAGE userApplications
        X-ORIGIN 'OpenID Connect 1.0' )

To apply the LDIF file from the command on the OpenLDAP host:

sudo ldapmodify -Y EXTERNAL -H ldapi:/// -f authz-schema-attributes-update.ldif

The OpenLDAP directory will automatically assign new {xxxx} prefixes to the attributes.

Step 2.

Apply the following LDIF file to upgrade the object class definitions.