<?xml version="1.0" encoding="US-ASCII"?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [

<!ENTITY RFC2078 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2078.xml">
<!ENTITY RFC2119 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml">
<!ENTITY RFC2222 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2222.xml">
<!ENTITY RFC4511 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4511.xml">
]>

<?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?>

<?rfc strict="yes" ?>
<?rfc toc="yes"?>
<?rfc tocdepth="4"?>
<?rfc symrefs="yes"?>
<?rfc sortrefs="yes" ?>
<?rfc compact="yes" ?>
<?rfc subcompact="no" ?>
<rfc category="std" docName="draft-wibrown-ldapssotoken-02" ipr="trust200902">

<front>

    <title abbrev="LDAP SSO Token">Draft LDAP Single Sign On Token Processing</title>


   <author fullname="William Brown" initials="W.B." surname="Brown">
     <organization>Red Hat Asia-Pacific Pty Ltd</organization>

     <address>
       <postal>
         <street>Level 1, 193 North Quay</street>
         <city>Brisbane</city>
         <code>4000</code>
         <region>Queensland</region>
         <country>AU</country>
       </postal>

       <phone></phone>

       <email>wibrown@redhat.com</email>

       <!-- uri and facsimile elements may also be added -->
     </address>
   </author>

   <author fullname="Simo Sorce" initials="S.S." surname="Sorce" role="editor">
     <organization>Red Hat, Inc.</organization>

     <address>
       <postal>
         <street></street>

         <city></city>

         <region></region>

         <code></code>

         <country></country>
       </postal>

       <phone></phone>

       <email>simo@redhat.com</email>

       <!-- uri and facsimile elements may also be added -->
     </address>
   </author>

   <author fullname="Kieran Andrews" initials="K.A." surname="Andrews" role="editor">
     <organization>The University of Adelaide</organization>

     <address>
       <postal>
         <street></street>

         <city>Adelaide</city>

         <region>South Australia</region>

         <code>5005</code>

         <country>AU</country>
       </postal>

       <phone></phone>

       <email>kieran.andrews@adelaide.edu.au</email>

       <!-- uri and facsimile elements may also be added -->
     </address>
   </author>

   <date year="2017"></date>


    <area>General</area>

   <workgroup>Internet Engineering Task Force</workgroup>

    <!-- I am not sure of the appropriate keywords here -->
   <keyword>draft-wibrown-ldapssotoken</keyword>

   <abstract>
     <t>LDAP Single Sign On Token is a SASL (Simple Authentication and Security Layer
        <xref target="RFC2222">RFC 2222</xref>) mechanism to allow single sign-on to an LDAP
        Directory Server environment. Tokens generated by the LDAP server can be transmitted through other
        protocols and channels, allowing a broad range of clients and middleware to take advantage
        of single sign-on in environments where Kerberos v5 or other Single Sign On mechanisms may not be avaliable.</t>
   </abstract>

</front>


<middle>

    <section title="Introduction">
        <t>The need for new, simple single sign-on capable systems has arisen
        with the development of new technologies and systems. For these systems
        we should be able to provide a simple, localised and complete single
        sign-on service. This does not aim to replace Kerberos V5. It is designed for when Kerberos
        is too invasive for installation in an environment.
        </t>


        <t>Tokens generated by this system should be able to be transmitted over
        different protocols allowing middleware to relay tokens to clients.
        Clients can then contact the middleware natively and the middleware can
        negotiate the client authentication with the LDAP server.</t>

        <!-- Use terms to describe instead -->
        <t>This implementation will provide an LDAP extended operation to create
        tokens which a client may cache, or relay to a further client. The token
        can then be sent in a SASL bind request to the LDAP server. The token
        remains valid over many binds. Finally, Tokens
        for a client are always able to be revoked at the LDAP Server using an
        LDAP extended operation, allowing global
        logout by the user or administrator.</t>


    </section>

    <section title="Requirements Language">
        <t>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
        "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
        document are to be interpreted as described in <xref
        target="RFC2119">RFC 2119</xref>.</t>
    </section>

    <section title="Format">
        <t>This document has two components. A SASL Mechanism, and LDAP extended operations.</t>
        <t>There is no strict requirement for the two to coexist: The LDAP Operation
        is an implementation of the service providing tokens, and the SASL Mechanism to authenticate them.</t>
        <t>In theory, an alternate protocol and database could generate and authenticate these tokens.</t>
    </section>

    <section title="SASL Component">
        <section title="Token formats">
            <t>Token formats are server implementation specific: As they
            are the only entity that will decrypt and consume them, they have
            the option to provide these in any format they wish. </t>
            <t>This means the client will only see an opaque data structure, and will only
            need to transmit this opaque structure as part of the authentication request.</t>

            <t>For the token system to operate correctly the server MUST
            generate tokens that contain at least these three values:</t>
            <t>
                <list style="symbols">
                    <t>Date Time Issued</t>
                    <t>Date Time Until</t>
                    <t>User Unique Id</t>
                </list>
            </t>
            <t>As the client does not ever see the contents the User Unique Id can be
            anything within the database that uniquely identifies the user
            that is the holder of the token.</t>
            <t>The User Unique Id MUST be an UTF8 String.</t>
            <t>The token format MUST be encrypted. The token format can be
            decrypted with either a asymmetric or symmetric keying system. </t>
            <t>The token format MUST have a form of data authentication.
            This can be through authenticated encryption, or validation of a hash.</t>
            <t>The Date Time Issued MUST be a complete timestamp in UTC, to
            prevent issues with changing timezones.</t>
            <t>Without these guarantees, the token system is not secure,
            and is vulnerable to credential forgery attacks.</t>

            <t>Here is an EXAMPLE ASN.1 format that would be encrypted and
            sent to the client:</t>
            <figure align="left" anchor="asn_token_example">
                <artwork align="left"><![CDATA[
LDAPSSOToken ::= SEQUENCE {
    DateTimeIssued GeneralizedTime,
    DateTimeUntil  GeneralizedTime,
    UserUniqueId   UTF8String }
                ]]></artwork>
            </figure>
            <t>This would be encrypted with AES-GCM and transmitted to the
            client.</t>

            <!-- make this an xref -->
            <t>Another example would be to use a fernet token
            <xref target="FERNETSPEC">Fernet Specification</xref>.</t>

            <figure align="left" anchor="fernet_token_example">
                <artwork align="left"><![CDATA[
Version || Timestamp || IV || Ciphertext || HMAC
                ]]></artwork>
            </figure>

            <t>Timestamp can be considered to be the DateTimeIssued as:</t>

            <t>"This field is a 64-bit unsigned big-endian integer. It records
            the number of seconds elapsed between January 1, 1970 UTC and the
            time the token was created."</t>

            <t>We can then create a Cipher text containing:</t>

            <figure align="left" anchor="fernet_tokendata_example">
                <artwork align="left"><![CDATA[
Date Time Until || User Unique Id
                ]]></artwork>
            </figure>

            <t>The Date Time Until is a 64-bit unsigned big-endian integer. It is,
            like Date Time Issued, the number of seconds since January 1, 1970
            UTC, and the token creation time added to the number of seconds of
            the requested life time. </t>

            <t>This example format satisfies all of our data requirements for the sso token
            system.</t>

        </section>

        <section title="SASL Client">
            <t>The client will request a token from the authentication server.
            The acquisition method for the token is discussed in section XXX.</t>
            <t>For authentication, the client MUST send the token as it was received.
            IE changes to formatting are not permitted.</t>
            <t>The client MUST send the an appropriate authid in  <xref target="RFC2078">RFC 2078</xref>
            form. This authid MUST internally match the User Unique Id in the token. The server
            is responsible for this validation.</t>
            <t>The client MAY transform the token if acting in a proxy fashion.
            However this transformation must be deterministic and able to be
            reversed to satisfy the previous requirement.</t>
            <figure align="left" anchor="server_transform_example">
                <artwork align="left"><![CDATA[
+-------+              +-------------+              +--------+
| LDAP  |              | HTTP server |              | Client |
|       |              |             | <- Login --  |        |
|       | <-- Bind --  |             |              |        |
|       | - Success -> |             |              |        |
|       | <- Req Token |             |              |        |
|       | -- Token --> |             |              |        |
|       | <- Unbind -  |             |              |        |
|       | - Success -> |             |              |        |
|       |              | Html Escape |              |        |
|       |              |             | -- Safe -->  |        |
|       |              |             |     Token    |        |
|       |              |             |              | Store  |
|       |              |             | < Request +- |        |
|       |              | Reverse esc |    Token     |        |
|       | < Token Bind |             |              |        |
|       | - Success -> |             |              |        |
|       | <- Operation |             |              |        |
|       | <- Unbind -  |             |              |        |
|       | - Success -> |             |              |        |
|       |              |             | - Response > |        |
+-------+              +-------------+              +--------+
                ]]></artwork>
            </figure>
            <t>This example shows how a client is issued with a token when
            communicating with a web server via the HTTP intermediate. The Client
            does not need to be aware of the SASL/LDAP system in the background,
            or the token's formatting rules. Provided the HTTP server in
            proxy, if required to transform the token, is able to undo the
            transformations, this is a valid scenario. For example, HTML escaping
            a base64 token.</t>
        </section>

        <section title="SASL Authentication">
            <t>The client issues a SASL bind request with the mechanism name
            LDAPSSOTOKEN.</t>
            <t>The client sends an appropriate authid in  <xref target="RFC2078">RFC 2078</xref>
            form.</t>
            <t>The client provides the encrypted token that was provided in
            the LDAPSSOTokenResponse Token Field.</t>
            <t>The token is decrypted and authenticated based on the token
            format selected by the server. The server MAY attempt multiple
            token keys and or formats to find the correct issuing format and
            key.</t>
            <t>If the token decryption fails, the attempt with this key and
            format MUST be considered to fail.</t>
            <t>If the values have been tampered with, IE hash authentication fails, the attempt with the key
            and format MUST be considered to fail. </t>
            <t>The token decryption MUST return a valid DateTimeUntil,
            DateTimeIssued and User Unique Id. If this is not returned, the decryption
            MUST be considered to fail.</t>
            <t>If all token formats and keys fail to decrypt, this MUST cause an
            invalidCredentials error.</t>
            <t>The DateTimeUntil field is checked against the servers current
            time. If the current time exceeds or is equal to DateTimeUntil,
            invalidCredentials MUST be returned.</t>
            <t>The User Unique Id is validated to exist on the server. If the User Unique Id
            does not exist, invalidCredentials MUST be returned.</t>
            <t>The authid provided by the SASL client is verified with the User Unique Id. For example
            if the authid is william@EXAMPLE.COM, the server maps this to an identity. Once this
            identity is validated, the identity is check to match the User Unique Id. If they do not
            match, the authentication MUST fail.</t>
            <t>The DateTimeIssued field is validated against the User Unique Id object's
            attribute or related attribute that contains "Valid Not Before". If the value of
            "Valid Not Before" exceeds or is equal to DateTimeIssued,
            invalidCredentials MUST be returned.</t>
            <t>Only if all of these steps have succeeded, then the authentication is considered successful. </t>
        </section>

        <section title="Valid Not Before Attribute">
            <t>The management and details of the "Valid Not Before" attribute
            are left to the implementation to decide how to implement and
            manage. The implementation should consider how an administrator
            or responsible party could revoke tokens for users other than their
            own. The Valid Not Before SHOULD be replicated between LDAP servers
            to allow correct revocation across many LDAP servers. For example,
            Valid Not Before MAY be an attribute on the User Unique Id object, or MAY be on another
            object with a unique relation to the User Unique Id.</t>
        </section>
    </section>

    <section title="LDAP Component">

        <section title="Token Generation">
            <t>An ldap extended operation is issued as per Section 4.12 of
            <xref target="RFC4511">RFC 4511</xref>.</t>
            <t>The LDAP OID to be used for the LDAPSSOTokenRequest is 2.16.840.1.113730.3.5.14.</t>
            <t>The LDAP OID to be used for the LDAPSSOTokenResponse is 2.16.840.1.113730.3.5.15.</t>
            <t>A User Unique Id is selected. This may be the Bind DN, UUID or other
            utf8 identifier that uniquely determines an object.</t>
            <t>The extended operation must fail if the LDAP connection security stregth factors is 0.</t>
            <t>Tokens must not be generated for Anonymous binds. This means,
            tokens may only be generated for connections with a valid bind dn set.</t>
            <t>Token requests MUST contain a requested lifetime in seconds.
            The server MAY choose to ignore this lifetime and set it's own
            value.</t>
            <t>A token request of a negative or zero value SHOULD default to
            a server definied minimum lifetime.</t>
            <t>The token is created as per an example token format in 4.1. This value
            is then encrypted with an encryption algorithm of the servers
            choosing. The client does not need to be aware of the encryption
            algorithm.</t>
            <t>The DateTimeIssued, DateTimeUntil and User Unique Id are collected in
            the format required by the token format we are choosing to use in
            the server. The token is then generated by the chosen
            algorithm.</t>
            <t>The encrypted token is sent to the client in the
            LDAPSSOTokenResponse structure, along with the servers chosen valid
            life time as a guide for the client to approximate the expiry of the
            token. This valid life time value is in seconds.</t>
            <t>If the token cannot be generated due to a server error, LDAP_OPERATION_ERROR MUST be returned.</t>

            <section title="Token Generation Extended Operation">
                <figure align="left" anchor="token_generation_ext_op">
                    <artwork align="left"><![CDATA[
LDAPSSOTokenRequest ::= SEQUENCE {
    ValidLifeTime INTEGER }

LDAPSSOTokenResponse ::= SEQUENCE {
    ValidLifeTime INTEGER,
    EncryptedToken         OCTET STRING
}
                    ]]></artwork>
                </figure>
            </section>
        </section>

        <section title="Token Revocation">
            <t>An ldap extended operation is issued as per Section 4.12
            <xref target="RFC4511">RFC 4511</xref>. </t>
            <t>The LDAP OID to be used for LDAPSSOTOKENRevokeRequest is 2.16.840.1.113730.3.5.16.</t>
            <t>The extended operation MUST fail if the connection is
            anonymous.</t>
            <t>The extended operation MUST fail if the LDAP connection security strength factors is 0.</t>
            <t>The extended operation MUST only act upon the "Valid Not Before"
            attribute related to the bind DN of the connection.</t>
            <t>Upon recieving the extended operation to revoke tokens, the
            directory server MUST set the current BindDN's related "Valid Not Before" attribute timestamp to the current datetime. This will
            have the effect, that all previously issued tokens are invalidated.</t>
            <t>This revocation option must work regardless of directory server
            access controls on the attribute containing "Valid Not Before".</t>
            <section title="Token Revocation Extended Operation">
                <t>The extended operation requestValue MUST not be set for
                LDAP SSO Token revocation.</t>
                <t>The extended operation does not provide a response OID. The result is set in the LDAPResult.</t>
            </section>
        </section>

        <section title="Binding">
            <t>The SASL bind attempt MUST fail if the LDAP connection security strength factors is 0.</t>
            <t>The SASL Authentication is attempted as per Section 4.3. If this does not succeed, the bind attempt MUST fail.</t>
            <t>The LDAP Object is retrived from the User Unique Id, and a Bind DN Determined. If no Bind DN can be determined, the bind attempt MUST fail.</t>
            <t>The current Bind DN MUST be set to the Bind DN of the LDAP object that is determined, and the result ldap success is returned to the LDAP client.</t>
        </section>

    </section>

    <section title="Security Considerations">
        <t>Due to the design of this token, it is possible to use it in a replay
        attack. Notable threats are storage on the client and man in the middle attacks.
        To minimise the man in the middle attack thread, LDAP security strength factor of greater than 0 is a requirement.
        Client security is not covered by this document.</t>
    </section>

    <section title="Requirements">
        <t>The SASL mechanism, LDAPSSOTOKEN, MUST be registered to IANA as per
        <xref target="RFC2222">RFC 2222</xref> Section 6.4</t>
    </section>


</middle>

<back>

   <references title="Normative References">
     &RFC2119;

   </references>

   <references title="Informative References">
     &RFC2078;

     &RFC2222;

     &RFC4511;
    <!-- Add the fernet reference  -->

    <reference anchor="FERNETSPEC"
    target="https://github.com/fernet/spec/blob/master/Spec.md">
        <front>
            <title>Fernet Specification</title>

            <author fullname="Tom Maher" initials="T.M." surname="Maher">
            </author>

            <author fullname="Keith Rarick" initials="K.R." surname="Rarick">
            </author>

            <date year="2013" />
        </front>
    </reference>

    </references>

</back>

</rfc>
