<?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>
	<section id="sect-Reference_Guide-Authentication_Token_Configuration-What_is_token_service">
		<title>What is Token Service?</title>
		<para>
			<emphasis>Token Service</emphasis> is used in authentication.
		</para>
		<para>
			The token system prevents user account information being sent in clear text mode within inbound requests. This increases authentication security.
		</para>
		<para>
			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>
	</section>
	
	<section id="sect-Reference_Guide-Authentication_Token_Configuration-Implement_token_services_API">
		<title>Implementing the Token Service API</title>
		<para>
			All token services used in &PRODUCT; authentication must be implemented by subclassing an <emphasis role="bold">AbstractTokenService</emphasis> abstract class.
         The following <emphasis role="bold">AbstractTokenService</emphasis> methods represent the contract between authentication runtime, and a token service implementation.
		</para>
		
<programlisting role="JAVA">
		public Token getToken(String id) throws PathNotFoundException, RepositoryException;
		public Token deleteToken(String id) throws PathNotFoundException, RepositoryException;
		public String[] getAllTokens();
		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>
	</section>
	
	<section id="sect-Reference_Guide-Authentication_Token_Configuration-Configure_token_services">
		<title>Configuring token services</title>
		<para>
			Token services configuration includes specifying the token validity period. The token service is configured as a portal component (in portal scope, as opposed to root scope - more about that in Foundations chapter).
		</para>
		<para>
			In the example below, <emphasis>CookieTokenService</emphasis> is a subclass of <emphasis role="bold">AbstractTokenService</emphasis> 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 role="bold">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>&#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 role="bold">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>
	</section>

</section>


