Search
SupportConsoleDevelopersStart a trialContact

6.6. External Registration

download PDF
External Registration obtains the token type (TPS profile) from the authenticated user LDAP record. It also allows certificate/key recovery information to be specified in the same user record.
An External Registration TPS profile is similar to the Internal Registration profile discussed previously. It allows you to specify new certificate enrollments for both client-side and server-side key generation. Unlike Internal Registration, it allows you to choose specific certificate (and its matching keys) to be retrieved and loaded onto the token.

Note

Switching registration types between Internal and External Registration means you have to format all previously registered tokens before you can continue using them.

6.6.1. Enabling External Registration

External Registration can only be enabled globally for an entire TPS instance. The following example shows a set of global configuration parameters pertaining to External Registration: 
externalReg.allowRecoverInvalidCert.enable=true
externalReg.authId=ldap1
externalReg.default.tokenType=externalRegAddToToken
externalReg.delegation.enable=true
externalReg.enable=true
externalReg.recover.byKeyID=false
externalReg.format.loginRequest.enable=true
externalReg.mappingResolver=keySetMappingResolver

6.6.2. Customizing User LDAP Record Attribute Names

Authentication parameters pertaining to External Registration are shown in the following example (with their default values): 
auths.instance.ldap1.externalReg.certs.recoverAttributeName=certsToAdd
auths.instance.ldap1.externalReg.cuidAttributeName=tokenCUID
auths.instance.ldap1.externalReg.tokenTypeAttributeName=tokenType
The LDAP record attribute names can be customized here. Make sure that the actual attributes in the user's LDAP records match this configuration.

6.6.3. Configuring certsToAdd attributes

The certsToAdd attribute takes multiple values in the following form: 
<cert serial # in decimal>,<CA connector ID>,<key ID>,<kra connector ID>
For example: 
59,ca1,0,kra1

Important

By default, key recovery searches for the key by certificate, which makes the <key ID> value irrelevant. However, the TPS can optionally be configured to search for the key using this attribute, and therefore it is typically simpler to set the value to 0. That value is invalid, which avoids the possibility of retrieving an unmatched key.
Recovering by key ID is not recommended, because the KRA can not verify if the certificate matches with the key in this situation.
When specifying the certsToAdd attribute with only certificate and CA information, the TPS assumes that the certificate in question is already on the token, and that it should be preserved. This concept is called Key Retention.
The following examples show relevant attributes in the user LDAP record: 
tokenType: externalRegAddToToken
certstoadd: 59,ca1,0,kra1
certstoadd: 134,ca1,0,kra1
Certstoadd: 24,ca1

6.6.4. Token to User Matching Enforcement

Optionally, you can set the system up so that the token used for registration must match the token record card-unique ID (CUID) attribute in the user record. If this attribute (tokencuid) is missing from the record, CUID matching is not enforced. 
Tokencuid: a10192030405028001c0
Another attribute about External Registration is that the Token Policies on each token are bypassed.

Note

For the certificate and keys to be “recovered” in External Registration, connector information for CA and KRA is specified in the user LDAP record. Any CA and/or KRA connector information specified in the TPS profile pertaining to the certificate/keys to be “recovered” is to be ignored. 
certstoadd: 59,ca1,0,kra1

6.6.5. Delegation Support

Delegation support is useful where a user has delegates who can act on their behalf (for example, an executive at a company has one or more delegates) in terms of authentication (logins), data encryption and decryption, or signing (with limitations).
An example scenario could be that each delegate has their own token which they use to act on behalf of the executive. This token contains a combination of the following certificates and keys (determined by TPS profiles):
  • Authentication certificate/keys: The CN contains the name and unique ID of the delegate. The Subject Alternative Name (SAN) extension contains the Principal Name (UPN) of the executive.
  • Encryption certificate: An exact copy of the executive's encryption certificate.
  • Signing certificate: The CN contains the delegate's name and unique ID. The SAN contains the RFC822Name of the executive.
Use the following parameter to enable delegation support: 
externalReg.delegation.enable=true

Important

To work around a bug, manually set the op.enroll.delegateISEtoken.keyGen.encryption.ca.profileId parameter in the /var/lib/pki/instance_name/tps/conf/CS.cfg file to caTokenUserDelegateAuthKeyEnrollment: 
op.enroll.delegateISEtoken.keyGen.encryption.ca.profileId=caTokenUserDelegateAuthKeyEnrollment

6.6.6. SAN and DN Patterns

The auths.instance.<authID>.ldapStringAttributes in the authentication instance configuration specifies which attributes will be retrieved during authentication. For example: 
auths.instance.ldap1.ldapStringAttributes=mail,cn,uid,edipi,pcc,firstname,lastname,exec-edipi,exec-pcc,exec-mail,certsToAdd,tokenCUID,tokenType
Once retrieved from the user's LDAP record, the values of these attributes can be referenced and used to form the Subject Alternative Name (SAN) or Distinguished Name (DN) of the certificate in the format of $auth.<attribute name>$. For example: 
op.enroll.delegateIEtoken.keyGen.authentication.SANpattern=$auth.exec-edipi$.$auth.exec-pcc$@EXAMPLE.com
op.enroll.delegateIEtoken.keyGen.authentication.dnpattern=cn=$auth.firstname$.$auth.lastname$.$auth.edipi$,e=$auth.mail$,o=TMS Org
When patterns are used in TPS profiles for SAN and DN, it is important to ensure the CA enrollment profile specified in the TPS profile is set up correctly. For example:
On TPS, in profile delegateIEtoken
op.enroll.delegateIEtoken.keyGen.authentication.ca.profileId=caTokenUserDelegateAuthKeyEnrollment
On CA, in enrollment profile caTokenUserDelegateAuthKeyEnrollment
The subjectDNInputImpl plug-in must be specified as one of the inputs in order to allow the DN to be specified by the TPS profile above: 
input.i2.class_id=subjectDNInputImpl
input.i2.name=subjectDNInputImpl
Similarly, to allow the SAN to be specified by the above TPS profile, the subjectAltNameExtInputImpl plug-in must be specified: 
input.i3.class_id=subjectAltNameExtInputImpl
input.i3.name=subjectAltNameExtInputImpl
The subjAltExtpattern must be specified as well: 
policyset.set1.p6.default.params.subjAltExtPattern_0=(UTF8String)1.3.6.1.4.1.311.20.2.3,$request.req_san_pattern_0$
In the above example, the OID 1.3.6.1.4.1.311.20.2.3 is the OID for the User Principal Name (UPN), and request.req_san_pattern_0 is the first SAN pattern specified in the delegateIEtoken SAN pattern.
You can specify multiple SANs at the same time. On the TPS side, specify multiple SANs in the SANpattern, delimited by a comma (","). On the CA side, a corresponding amount of subjAltExtPattern needs to be defined in the following format: 
policyset.<policy set id>.<policy id>.default.params.subjAltExtPattern_<ordered number>=
In the above, the <ordered number> starts with 0 and increases by one for each SAN pattern specified on the TPS side: 
policyset.set1.p6.default.params.subjAltExtPattern_0=
policyset.set1.p6.default.params.subjAltExtPattern_1=
...
The following is a complete example:

Example 6.1. SANpattern and DNpattern configuration

The LDAP record contains the following information: 
givenName: user1a
mail: user1a@example.org
firstname: user1a
edipi: 123456789
pcc: AA
exec-edipi: 999999999
exec-pcc: BB
exec-mail: user1b@EXAMPLE.com
tokenType: delegateISEtoken
certstoadd: 59,ca1,0,kra1
TPS External Registration profile delegateIEtoken contains:
  • SANpattern: 
    op.enroll.delegateISEtoken.keyGen.authentication.SANpattern=$auth.exec-edipi$.$auth.exec-pcc$@EXAMPLE.com
  • DNPattern: 
    op.enroll.delegateISEtoken.keyGen.authentication.dnpattern=cn=$auth.firstname$.$auth.lastname$.$auth.edipi$,e=$auth.mail$,o=TMS Org
CA caTokenUserDelegateAuthKeyEnrollment contains: 
input.i2.class_id=subjectDNInputImpl
input.i2.name=subjectDNInputImpl
input.i3.class_id=subjectAltNameExtInputImpl
input.i3.name=subjectAltNameExtInputImpl

policyset.set1.p6.constraint.class_id=noConstraintImpl
policyset.set1.p6.constraint.name=No Constraint
policyset.set1.p6.default.class_id=subjectAltNameExtDefaultImpl
policyset.set1.p6.default.name=Subject Alternative Name Extension Default
policyset.set1.p6.default.params.subjAltExtGNEnable_0=true
policyset.set1.p6.default.params.subjAltExtPattern_0=(UTF8String)1.3.6.1.4.1.311.20.2.3,$request.req_san_pattern_0$
policyset.set1.p6.default.params.subjAltExtType_0=OtherName
policyset.set1.p6.default.params.subjAltNameExtCritical=false
policyset.set1.p6.default.params.subjAltNameNumGNs=1
The resulting certificate then contains: 
Subject: CN=user1a..123456789,E=user1a@example.org,O=TMS Org
Identifier: Subject Alternative Name - 2.5.29.17
Critical: no
Value:
  OtherName: (UTF8String)1.3.6.1.4.1.311.20.2.3,999999999.BB@EXAMPLE.com
Red Hat logoGithubRedditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.