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&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}