001/**
002 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
003 *
004 * Copyright (c) 2005 Sun Microsystems Inc. All Rights Reserved
005 *
006 * The contents of this file are subject to the terms
007 * of the Common Development and Distribution License
008 * (the License). You may not use this file except in
009 * compliance with the License.
010 *
011 * You can obtain a copy of the License at
012 * https://opensso.dev.java.net/public/CDDLv1.0.html or
013 * opensso/legal/CDDLv1.0.txt
014 * See the License for the specific language governing
015 * permission and limitations under the License.
016 *
017 * When distributing Covered Code, include this CDDL
018 * Header Notice in each file and include the License file
019 * at opensso/legal/CDDLv1.0.txt.
020 * If applicable, add the following below the CDDL Header,
021 * with the fields enclosed by brackets [] replaced by
022 * your own identifying information:
023 * "Portions Copyrighted [year] [name of copyright owner]"
024 *
025 * $Id: SSOToken.java,v 1.4 2009/01/16 10:43:14 manish_rustagi Exp $
026 *
027 */
028
029/*
030 * Portions Copyrighted [2010] [ForgeRock AS]
031 */
032
033package com.iplanet.sso;
034
035
036/**
037 * The <code>SSOToken</code> class represents a "single sign on"(SSO) token.
038 * It contains SSO token-related information such as authentication method used
039 * for authentication, authentication level of the authentication method, host
040 * name of the client that sent the request (browser). It also contains
041 * session-related information such as maximum session time, maximum session
042 * idle time and session idle time.
043 *
044 * @supported.all.api
045 */
046public interface SSOToken {
047
048    /**
049     * Returns the value of the property "Principal" set to the single sign on
050     * token.
051     * 
052     * @return The principal name
053     * @exception SSOException
054     *                if the single sign on token is not valid or if there are
055     *                errors in getting the principal
056     */
057    public java.security.Principal getPrincipal() throws SSOException;
058
059    /**
060     * Returns the authentication method used for authentication.
061     * 
062     * @return The authentication method
063     * @exception SSOException
064     *                if the single sign on token is not valid or if there are
065     *                errors in getting the authentication method
066     */
067    public java.lang.String getAuthType() throws SSOException;
068
069    /**
070     * Returns the authentication level of the authentication method used for
071     * authentication.
072     * 
073     * @return The authentication level
074     * @exception SSOException
075     *                if the single sign on token is not valid or if there are
076     *                errors in getting the authentication level
077     */
078    public int getAuthLevel() throws SSOException;
079
080    /**
081     * Returns the IP Address of the client (browser) that sent the request.
082     * 
083     * @return The IP Address of the client
084     * @exception SSOException
085     *                if the single sign on token is not valid or if there are
086     *                errors in getting the IP Address of the client
087     */
088    public java.net.InetAddress getIPAddress() throws SSOException;
089
090    /**
091     * Returns the host name of the client (browser) that sent the request.
092     * 
093     * @return The host name of the client
094     * @exception SSOException
095     *                if the single sign on token is not valid or if there are
096     *                errors in getting the host name of the client
097     */
098    public java.lang.String getHostName() throws SSOException;
099
100    /**
101     * Returns the time left in seconds on the session based on max session
102     * time.
103     * 
104     * @return The time left in seconds on the session.
105     * @exception SSOException
106     *                if the single sign on token is not valid or if there are
107     *                errors in getting the maximum session time.
108     */
109    public long getTimeLeft() throws SSOException;
110
111    /**
112     * Returns the maximum session time in minutes.
113     * 
114     * @return The maximum session time in minutes
115     * @exception SSOException
116     *                if the single sign on token is not valid or if there are
117     *                errors in getting the maximum session time
118     */
119    public long getMaxSessionTime() throws SSOException;
120
121    /**
122     * Returns the session idle time in seconds.
123     * 
124     * @return The session idle time in seconds
125     * @exception SSOException
126     *                if the single sign on token is not valid or if there are
127     *                errors in getting the session idle time
128     */
129    public long getIdleTime() throws SSOException;
130
131    /**
132     * Returns the maximum session idle time in minutes.
133     * 
134     * @return The maximum session idle time in minutes
135     * @exception SSOException
136     *                if the single sign on token is not valid or if there are
137     *                errors in getting the maximum idle time
138     */
139    public long getMaxIdleTime() throws SSOException;
140
141    /**
142     * Returns single sign on token ID object.
143     * 
144     * @return single sign on token ID.
145     */
146    public SSOTokenID getTokenID();
147
148    /**
149     * Sets a property for this token.
150     * 
151     * @param name
152     *            The property name.
153     * @param value
154     *            The property value.
155     * @exception SSOException
156     *                if the single sign on token is not valid or if there are
157     *                errors in setting the property name and value
158     */
159    public void setProperty(java.lang.String name, java.lang.String value)
160            throws SSOException;
161
162    /**
163     * Gets the property stored in this token.
164     * 
165     * @param name
166     *            The property name.
167     * @return The property value in string format.
168     * @exception SSOException
169     *                if the single sign on token is not valid or if there are
170     *                errors in getting the property value
171     */
172    public java.lang.String getProperty(java.lang.String name)
173            throws SSOException;
174
175    /**
176     * Gets the property stored in this token. When ignoreState is set to true,
177     * it will return the session property value without refreshing the session
178     * even if the session state is invalid but it should be running in the 
179     * server mode
180     * 
181     * @param name
182     *            The property name.
183     * @param ignoreState
184     *            The ignoreState flag.
185     * @return The property value in string format.
186     * @exception SSOException
187     *                if the SSOToken is not VALID and if
188     *                ignoreState is set to false.
189     */
190    public java.lang.String getProperty(java.lang.String name,
191                boolean ignoreState ) throws SSOException;
192
193    /**
194     * Adds an SSO token listener for the token change events.
195     * 
196     * @param listener
197     *            A reference to an <code>SSOTokenListener</code> object.
198     * @exception SSOException
199     *                if the token is not valid or if there are errors in
200     *                setting the SSO token listener.
201     */
202    public void addSSOTokenListener(com.iplanet.sso.SSOTokenListener listener)
203            throws SSOException;
204
205    /**
206     * Returns the encoded URL , rewritten to include the session id. The
207     * session id will be encoded in the URL as a query string with entity
208     * escaping of ampersand when appending the session id to the query string
209     * if the query string has other query parameters.
210     * <p>
211     * Encoded URL format if query string in the original URL passed is present
212     * will be :
213     * 
214     * <pre>
215     *   protocol://server:port/path?queryString&amp;cookieName=cookieValue
216     * </pre>
217     * 
218     * Encoded URL format if query string in the original URL passed is not
219     * present will be:
220     * 
221     * <pre>
222     *   protocol://server:port/path?cookieName=cookieValue
223     * </pre>
224     * 
225     * @param url
226     *            the URL to be encoded
227     * @return the encoded URL if cookies are not supported or the URL if
228     *         cookies are supported. Note: We should not use this method for
229     *         encoding the image URLs
230     * @exception SSOException
231     *                if URL cannot be encoded.
232     */
233    public String encodeURL(String url) throws SSOException;
234
235    /**
236     * Returns true if the SSOTokenID associated with this SSOToken is a
237     * restricted token, false otherwise.
238     *
239     * @return true if the token is restricted
240     * @throws SSOException If we are unable to determine if the session is
241     *              restricted
242     */
243    public boolean isTokenRestricted() throws SSOException;
244
245    /**
246     * Given a restricted token, returns the SSOTokenID of the master token
247     * can only be used if the requester is an app token
248     *
249     * @param requester Must be an app token
250     * @param restrictedId The SSOTokenID of the restricted token
251     * @return The SSOTokenID string of the master token
252     * @throws SSOException If the master token cannot be dereferenced
253     */
254    public String dereferenceRestrictedTokenID(SSOToken requester, String restrictedId)
255    throws SSOException;
256}