Token assemblers and keystores

Token assembler

SecTokens are generated by token assemblers, which are able to externalize all formats documented in Nevis SecToken. Token assemblers are used to specify:

• Which key to use for signing the token for which SSO domain or even application (see Selector element)

  caution

  When using multiple signers, the private key should be protected with the same password. You can also set the password getter for all keys, except the first one, to a program or file that fetches the password without direct user interaction. This is because the server is already detached from the controlling terminal when reading the certificates.

• Which token format to use and what attributes to add, based on the SSO domain or even application resource.

The token assembler for a minimal authentication SecToken as specified in Nevis SecToken looks as follows:

<TokenAssembler name="DefaultTokenAssembler">
   <Selector default="true"/>
   <TokenSpec version="CSSO-1.0" ttl="28800" useGmt="true" algorithm="SHA256withRSA">
      <field src="session" key="ch.nevis.session.sessid" as="sessid"/>
      <field src="session" key="ch.nevis.session.userid" as="userid"/>
      <field src="session" key="ch.nevis.session.authlevel" as="authLevel"/>
      <field src="session" key="ch.nevis.session.esauthid" as="esauthid"/>
      <field src="session" key="ch.nevis.session.entryid" as="entryid"/>
      <!-- generic fields, required by Nevis reverse proxy -->
      <field src="session" key="ch.nevis.session.domain" as="domain"/>
   </TokenSpec>
   <Signer key="DefaultSigner"/>
</TokenAssembler>

• Selector

  This element defines under which condition the token assembler should be used.

  Valid attributes are:

  • default="true" Always use it when no other selector matches
  • domain="SSO1" Use it for logins in SSO domain "SSO1"
  • resource="/some/appl" Use it for accesses to content provider "/some/appl"

• TokenSpec

  This element defines the well-known SecToken attributes.

  Valid attribute values are:

  • version="1.0" XML only generic token
  • version="CSSO-1.0" Generic authentication token
  • ttl="28800" The token's absolute validity time in seconds
  • useGmt="true" Use GMT time and timestamp format YYYYMMDDhhmmssZ
  • useGmt="false" Use local time and format YYYYMMDDhhmmss+nnnn
  • algorithm="SHA256withRSA" Use the specified signing algorithm. If the attribute algorithm is not specified, SHA256withRSA will be used.

• field

  Fields define from where to retrieve a value for the specified attribute and under what name the attribute should be visible in the SecToken.

  Valid attributes are:

  • src="session" Retrieve attribute from the authentication session
  • src="const" The value of the key attribute is set
  • src="request" Retrieve a value from the current input request (set by client)
  • src="notes" Retrieve attribute from the notes written by AuthStates
  • key="some" Extract attribute some from source specified by src or treat the key as a value if src="const"
  • as="other" Set attribute into SecToken using name other

  For a list of Nevis session attributes, see Session indexing.

• Signer

  This element references the KeyObject to use from the KeyStore for signing.

KeyStores

The KeyStore element describes a collection of key material references used for token signing and verification or by a plugin. The following sample shows a KeyStore that describes the common setup of a failsafe nevisAuth installation, where both nevisAuth instances have one private key each for signing. Both nevisAuth instances need three keys:

• a private key for signing
• their own public key for verifying their own tokens
• the public key of the other nevisAuth instance for verifying tokens issued at that instance

KeyStore example

<KeyStore id="DefaultKeyStore">
    <KeyObject name="DefaultSigner"
        certificate="/var/opt/keybox/nevis/authSigner_keystore.jks?alias=authSigner"
        privateKey="/var/opt/keybox/nevis/authSigner_keystore.jks?alias=authSigner"
        passPhrase="pipe:///opt/neviskeybox/bin/keystorepwget"
    />
    <KeyObject name="AlternativeSigner"
      certificate="/var/opt/keybox/nevis/alternative_signer.pem"
    />
</KeyStore>

The KeyStore element requires an id attribute to identify the KeyStore.

The KeyObject element has the following attributes:

• name (string, required)

  Name referenced by TokenAssembler's Signer element

• certificate

  See Certificates keys and public key infrastructure

• privateKey

• passPhrase