<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "../../Reference_Guide.ent">
%BOOK_ENTITIES;
]>
<section id="sect-Reference_Guide-Authentication_Token_Configuration">
	<title>Authentication Token Configuration</title>
  <para xml:id="sect-Reference_Guide-Authentication_Token_Configuration-What_is_token_service">
    <citetitle>
      <emphasis role="bold">What is Token Service?</emphasis>
    </citetitle>
  </para>
		<para>
			<emphasis>Token Service</emphasis> is used in authentication.
		</para>
		<para>
			The token system prevents user account information being sent in the clear text mode within inbound requests. This increases authentication security.
		</para>
		<para>
			The token service allows administrators to create, delete, retrieve and clean tokens as required.
         The service also defines a validity period of any given token. The token becomes invalid once this period expires.
		</para>

	
   <para xml:id="sect-Reference_Guide-Authentication_Token_Configuration-Implement_token_services_API">
    <citetitle>
      <emphasis role="bold">Implement the Token Service API</emphasis>
    </citetitle>
  </para>

		<para>
			All token services used in the &PRODUCT; authentication must be implemented by subclassing an <emphasis >AbstractTokenService</emphasis> abstract class.
         The following <emphasis >AbstractTokenService</emphasis> methods represent the contract between authentication runtime, and a token service implementation.
		</para>
		
<programlisting language="java">public Token getToken(String id) throws PathNotFoundException, RepositoryException;
public Token deleteToken(String id) throws PathNotFoundException, RepositoryException;
public long getNumberTokens() throws Exception;
public String createToken(Credentials credentials) throws IllegalArgumentException,NullPointerException;
public Credentials validateToken(String tokenKey, boolean remove) throws NullPointerException;</programlisting>
		<para>
		</para>

	<para xml:id="sect-Reference_Guide-Authentication_Token_Configuration-Configure_token_services">
    <citetitle>
      <emphasis role="bold">Configure token services</emphasis>
    </citetitle>
  </para>

		<para>
			The token services configuration includes specifying the token validity period. The token service is configured as a portal component (in the portal scope, as opposed to the root scope - more about that in Foundations chapter).
		</para>
		<para>
			In the example below, CookieTokenService is a subclass of AbstractTokenService, so it has a property which specifies the validity period of the token.
		</para>
		<para>
			The token service will initialize this validity property by looking for an <parameter>init-param</parameter> named <emphasis >service.configuration</emphasis>.
		</para>
		<para>
			This property must have three values.
		</para>
		<programlistingco>
			<areaspec>
				<area coords="7" id="area-Reference_Guide-Authentication_Token_Configuration-Configure_token_services-name" />
				<area coords="8" id="area-Reference_Guide-Authentication_Token_Configuration-Configure_token_services-time" />
				<area coords="9" id="area-Reference_Guide-Authentication_Token_Configuration-Configure_token_services-unit" />
			</areaspec>
<programlisting language="xml">&#60;component&#62;
  &#60;key&#62;org.exoplatform.web.security.security.CookieTokenService&#60;/key&#62;
  &#60;type&#62;org.exoplatform.web.security.security.CookieTokenService&#60;/type&#62;
  &#60;init-params&#62;
  	&#60;values-param&#62;
      &#60;name&#62;service.configuration&#60;/name&#62;
      &#60;value&#62;jcr-token&#60;/value&#62;
      &#60;value&#62;7&#60;/value&#62;
      &#60;value&#62;DAY&#60;/value&#62;
    &#60;/values-param&#62;    	
  &#60;/init-params&#62;
&#60;/component&#62;
</programlisting>
			<calloutlist>
				<callout arearefs="area-Reference_Guide-Authentication_Token_Configuration-Configure_token_services-name">
					<para>
						Service name
					</para>
				</callout>
				<callout arearefs="area-Reference_Guide-Authentication_Token_Configuration-Configure_token_services-time">
					<para>
						Amount of time
					</para>
				</callout>
				<callout arearefs="area-Reference_Guide-Authentication_Token_Configuration-Configure_token_services-unit">
					<para>
						Unit of time
					</para>
				</callout>
			</calloutlist>
		</programlistingco>
		
		<para>
			In this case, the service name is <emphasis >jcr-token</emphasis> and the token expiration time is one week.
		</para>
		<para>
			&PRODUCT; supports <emphasis>four</emphasis> time units:
		</para>
		<orderedlist numeration="arabic">
			<listitem>
				<para>
					<parameter>SECOND</parameter>
				</para>
			</listitem>
			<listitem>
				<para>
					<parameter>MINUTE</parameter>
				</para>
			</listitem>
			<listitem>
				<para>
					<parameter>HOUR</parameter>
				</para>
			</listitem>
			<listitem>
				<para>
					<parameter>DAY</parameter>
				</para>
			</listitem>
		</orderedlist>
     <para>
	<prompt>
		<emphasis role="bold">See also</emphasis>
	</prompt>
</para>

		<itemizedlist>
           <listitem>
               <para><link linkend="sect-Reference_Guide-Password-encryption">Password Encryption</link></para>
           </listitem>
           <listitem>
               <para><link linkend="sect-Reference_Guide-Predefined_User_Configuration">Predefined User Configuration</link></para>
           </listitem>
           <listitem>
               <para><link linkend="sect-Reference_Guide-PicketLink_IDM_integration">PicketLink IDM integration</link></para>
           </listitem>
           <listitem>
               <para><link linkend="sect-Reference_Guide-APIs-Organization_API">Organization API</link></para>
           </listitem>
           <listitem>
               <para><link linkend="sect-Reference_Guide-Accessing_User_Profile">Access User Profile</link></para>
           </listitem>
		    <listitem>
               <para><link linkend="chap-Reference_Guide-SSO_Single_Sign_On">Single-Sign-On (SSO)</link></para>
           </listitem>
       </itemizedlist>
</section>


