Skip to main content
Version: 7.2405.x.x LTS

Nevis SecToken

The SecToken concept and security considerations are described in the chapter Concept Description. This chapter contains the technical specification of the SecToken (format, algorithms, libraries).

SecToken data format​

The SecToken format consists of multiple semantic layers, each corresponding to the task of a software component. The design focusses on the following requirements:

  • extensibility (possibility of adding new attributes without the need to change existing software)
  • self-describing
  • size (as small as possible)

The external XML representation of the SecToken is based on the default encoding ISO-8859-1 (if not stated otherwise in the XML header).

Generic SecToken format​

The generic SecToken is a container that allows arbitrary (binary or character) data to be signed.

A sample SecToken looks as follows:

Example SecToken

<secToken version='1.0' signTime='20030204133740+0100' ttl='60'>
    <attr>
        <field name='userid'>userid</field>
        <field name='sessid'>ABC3dca335f_3</field>
        <field name='name2'>value2</field><field name='name1'>value1</field>
    </attr>
    <signature format='1.0' alg='SHA256withRSA' fingerPrint='F1:A3:DF:D1:F5:0D:C0:25:10:E6:34:DF:17:80:D2:E6'> PiGv/v4vEWIAAgIR6mDybfSVGmDtTq7f8AFQ4O1IwKbXP2u9IEr7anSoYELhwRp8q+PlFn1dWHJrARHBvlZ+Uz3HbWe/
J0uk2CZDU5ptH0JzdHSfbLEijlVbvbbV0JfM+gVD7cnicrmNk64ZfA4Pi8R0xSmQ4mJ02gS3nJwu/1o=
    </signature>
</secToken>

Elements and attributes are as follows:

  • secToken

    This is the start element of a Nevis security token. The XML DOCTYPE element was omitted to avoid wasting precious space.

  • version

    Version string of the SecToken in the form: [<prefix>]<major> "." <minor>

    where:

    • <major> reflects incompatible changes.
    • <minor> reflects optional new elements and attributes.
    • <prefix> reflects a typed token format. The prefix "CSSO-" is used to provide the most common fields as elements, instead of attributes. These are: sessid, userid, entryid, esauthid and authLevel.

    Supported versions are:

    • 1.0 (generic format)
    • CSSO-1.0 (typed format)
    • ASN1-1.1 (attribute certificate format)

  • signTime

    This time string reflects the SecToken's generation time either as GMT or local time, depending on the postfix.

    Format: YYYYMMDDhhmmssZ

    where:

    • YYYY: Year (4 digits, range 0..9999])
    • MM: Month (2 digits, range [1..12])
    • DD: Day (2 digits, range [1..31])
    • hh: Hour (2 digits, range [0..23])
    • mm: Minute (2 digits, range [0..59])
    • ss: Second (2 digits, range [0..59])
    • Z: Constant character "Z", signaling "zero" timezone (GMT), or "(+|-)hhmm". E.g., "+0100" for MET in winter and "+0200" for MET in summer.

    This format is common for PKI specifications and is derived from the ISO-9694-1. The corresponding XML schema type (xsd:dateTime, derived from ISO-8601) can easily be supported.

  • ttl

    Period of validity of the SecToken measured in seconds.

  • attr

    This element signals the beginning of the data section.

  • field

    This element signals the beginning of generic named value. Multiple field elements are supported. The order of their appearance is relevant for signature verification.

  • name

    The unique name of a generic named value.

  • enc

    The (optional) encoding of the field's value. Supported options are:

    • none: Plain string, no encoding (default, optional)
    • base64: base64 encoding

  • signature

    This element signals the beginning of the signature section. The value of this element is always base64-encoded because a signature consists of binary data.

  • format

    The format element is part of the SecToken's signature section. The format element unambiguously identifies a signed token format. The available values of this element are the same as for the version attribute. For a description of the supported values and the formatting details, see the description of the version attribute further above in this list.

  • alg

    The algorithm used for signing the data (fields), and the value of the attributes version, signTime, and ttl. The following algorithms are supported:

    • SHA1withRSA
    • SHA256withRSA
    • MD2withRSA
    • MD5withRSA

    The notation is the standard notation in Java for signature algorithms. A signature algorithm consists of a hash function in conjunction with an encryption algorithm.

  • fingerPrint

    An md5 hash value of the signer's DER-encoded X509 certificate.

    This attribute also reflects a reference to the signing entity (e.g., the nevisAuth instance that generated the security token) if not specified otherwise (see the authentication part of specification).

Authentication SecToken data format​

The authentication SecToken adds authentication and session information. The format defined in the chapter Generic SecToken format is enhanced to reflect well-known SecToken attributes. These well-known authentication attributes are:

info

Note that the attribute names are case-sensitive.

  • userid: The authenticated (internal) primary key, representing a unique session owner.
  • authLevel: The authentication strength used to identify the user (e.g., STRONG, WEAK, PROSPECT).
  • sessid: The key for a unique global session.
  • entryid: The ID of a unique entry point into the Nevis Web SSO environment.
  • esauthid (optional): name of the issuing authentication service.

They can be represented in two ways:

  • By using the generic field mechanism of the generic SecToken:

    <secToken version="1.0" signTime="20011114190059Z" ttl="600">
        <attr>
            <field name="userid">some</field>
            <field name="sessid">7iSqaesgnp39Cy9Mlnc3Iz6</field
            <field name="entryid">isiweb:SSO1:instance1</field>
            <field name="esauthid">EsAuthInst1</field>
            <field name="authLevel">STRONG</field>
        </attr>
        <signature format="1.0" alg="SHA256withRSA"
                   fingerPrint="F1:A3:DF:D1:F5:0D:C0:25:10:E6:34:DF:17:80:D2:E6"/>
    </secToken>

  • By using the enhanced authentication type SecToken (and local time MET in winter, instead of GMT):

    <secToken version="CSSO-1.0" signTime="20011114200059+0100" ttl="600">
        <attr>
            <userid>some</userid>
            <sessid>7iSqaesgnp39Cy9Mlnc3Iz6</sessid
            <entryid>isiweb:classic:SSO1</entryid>
            <esauthid>EsAuthInst1</esauthid>
            <authLevel>STRONG</authLevel>
            <mappings>
                <accountid domain="ApplDomain">other</accountid>
            </mapping>
        </attr>
        <signature format="CSSO-1.0" alg="SHA256withRSA"
     fingerPrint="F1:A3:DF:D1:F5:0D:C0:25:10:E6:34:DF:17:80:D2:E6"/>
    </secToken>

Version 1.0 supports the above listed attributes, therefore version-1.0-compatible code needs to support both approaches.

The following list explains the SecToken authentication attributes and elements:

  • userid

    This attribute is a unique identifier for the authenticated user. It may differ from the login information a user provided on authentication. The userid attribute reflects the unique (primary) key in the SSO user authentication database.

  • sessid

    This attribute is a unique identifier for the global session that was created for the user identified by the attribute userid.

    The nevisAuth attribute sessid consists of:

    • 132bit true random data
    • 6bit nevisAuth instance identifier in case multiple redundant nevisAuth instances are used

  • entryid

    This attribute is an identifier for the entry point into the SSO environment.

    Sample usage: In the Nevis environment, this ID is generated by nevisProxy, added to the SecToken on global session creation by nevisAuth, and is verified again by nevisProxy (for being unchanged). A content provider is now able to enforce authorization restrictions on the entry point.

    If nevisProxy is used as an entry point, the value of this field has the following format: isiweb:SSOdomain:InstanceId

    where:

    • isiweb: Constant string
    • SSOdomain: The value of ClntSessAppid
    • InstanceId: A configurable optional constant defining the installation.

  • esauthid

    This attribute is optional and references the nevisAuth instance that generated the token. It is needed when the fingerPrint attribute (see the previous table) is not referencing a certificate used by only one nevisAuth. The fingerPrint or esauthid attribute is required by components to find out which nevisAuth instance to contact for global session access.

  • authLevel

    This attribute reflects the authentication strength. The following levels are currently defined:

    • PROSPECT: Unverified (self-registered) user.
    • WEAK: Weak authentication, e.g., userid/password.
    • STRONG: Strong authentication, e.g., with additional one-time password or certificate (challenge).

    The corresponding security roles on nevisProxy might be auth.prospect, auth.weak and auth.strong, respectively.

  • mappings

    This attribute defines application-domain-specific mappings of the user ID into an application environment context. The application domain is defined by the domain attribute and the domain-specific identity by the accountid attribute.

  • accountid

    This attribute is used to specify a mapping of the authenticated user principal into an application environment.

    So the user may have the following IDs:

    • loginid: Known by the user for login (e.g., John Doe).
    • userid: The global primary key of the user's identity (e.g., CN of an LDAP person).
    • accountid: The primary key of the user's identity within an application domain (e.g., contract number of a contract management system).

  • domain

    This attribute defines the application environment of the accountid element.

SecToken verification​

Verifying a SecToken implies the following steps:

  1. Optional: Check if the SecToken is already valid: signTime - local_clock_tolerance > now
  2. Check if the SecToken is still valid: signTime + ttl + local_clock_tolerance > now
  3. Extract SecToken signature information, decode the signature (base64), decrypt it using the public key hinted by the fingerPrint attribute and the signature algorithm specified by the alg attribute. You have now HASH(1).
  4. Extract SecToken data (signTime and ttl attribute values and the attr section), append the signTime and ttl to the attr section, and create an SHA256 hash (or whatever hash algorithm is specified in the alg attribute of the signature element). You get HASH(2).
  5. Compare the two hash values HASH(1) and HASH(2).
info

To also allow signature verification in case of an unknown encoding type, the atttribute values are not decoded. Decoding must be done upon use, which allows to ignore SecToken information that is not needed.

The SecToken generated by nevisAuth does not contain any newlines to support delegation without URL encoding via HTTP protocols. The following sample token shows which parts need to be extracted for verification:

<secToken version="CSSO-1.0" signTime="20011114190059Z" ttl="600">
  <attr><userid>some</userid><sessid>7iSqaesgnp39Cy9Mlnc3Iz6</sessid<entryid>isiweb:classic:instance1</entryid><esauthid>EsAuthInst1</esauthid><authLevel>STRONG</authLevel></attr>
  <signature format="CSSO-1.0" alg="SHA256withRSA" fingerPrint="F1:A3:DF:D1:F5:0D:C0:25:10:E6:34:DF:17:80:D2:E6"/>
</secToken>

Relevant data of the sample token for HASH(2):

<attr><userid>some</userid><sessid>7iSqaesgnp39Cy9Mlnc3Iz6</sessid<entryid>isiweb:classic:instance1</entryid><esauthid>EsAuthInst1</esauthid><authLevel>STRONG</authLevel></attr>20011114190059Z600

Global Session Join​

To further enhance security, the nevisAuth that generated the SecToken and started the global session (see the attribute esauthid) may be contacted to check if the corresponding session really exists. By joining the global session, the verifier is notified when the global session terminates. This mechanism provides additional security, as local sessions are terminated, as soon as the user logs out and therefore may not be accessed by malicious clients from the intranet anymore.

SecToken Caching​

To boost SecToken performance verification, a SecToken cache may be used. In this case, successfully verified SecTokens may be stored in a cache. This omits expensive calls to the crypto library. The verification in this case consists of the following steps:

  1. Check if the SecToken is still valid
  2. Check if the SecToken is in the cache; if so, the request can proceed, otherwise:
  3. Perform verification as documented above.
  4. Cache the verified token (depending on the cache algorithms used).

The Nevis session manager, the IPlanet plug-in, and Ninja are using such a cache mechanism. Their specific implementation properties are:

  • The cache is initialized with a cacheSize and a cacheTimeout.
  • The cacheSize approximately indicates how many SecTokens are maximally stored in the cache (the actual size can temporarily grow larger than cacheSize, but the "cache cleaner", invoked depending on the cacheTimeout, removes entries to downsize the cache).
  • A "cache cleaner" thread removes expired SecTokens and downsizes the cache if it is too large.

APIs​

Token verification libraries are available for

  • Java: 1.7 or higher (any supported platform, but PKCS# 11 support is currently only available on Linux)
  • C+: Sun WS6, Linux gcc-3 and Microsoft .NET. For C+ libraries compiled for different platforms contact Nevis Support.