001/**
002 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
003 *
004 * Copyright (c) 2006 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: SecurityTokenProvider.java,v 1.3 2008/06/25 05:47:21 qcheng Exp $
026 *
027 */
028
029
030package com.sun.identity.liberty.ws.security;
031
032import com.sun.identity.liberty.ws.common.wsse.BinarySecurityToken;
033import com.sun.identity.liberty.ws.disco.EncryptedResourceID;
034
035import com.sun.identity.saml.assertion.Assertion;
036import com.sun.identity.saml.assertion.NameIdentifier;
037import com.sun.identity.saml.common.SAMLException;
038
039import java.security.cert.X509Certificate;
040
041/**
042 * The class <code>SecurityTokenProvider</code> is a provider interface 
043 * for managing <code>WSS</code> security tokens.
044 *
045 * @supported.all.api
046 */
047
048public interface SecurityTokenProvider {
049
050    /**
051     * Initializes the <code>SecurityTokenProvider</code>.
052     *
053     * @param credential The credential of the caller used
054     *        to see if access to this security token provider is allowed.
055     * @param sigManager instance of XML digital
056     *        signature manager class, used for accessing the certificate
057     *        data store and digital signing of the assertion.
058     * @throws SecurityTokenException if the caller does not have
059     *         privilege to access the security authority manager.
060     */
061    public void initialize(java.lang.Object credential,
062        com.sun.identity.saml.xmlsig.XMLSignatureManager sigManager)
063        throws SecurityTokenException;
064
065    /**
066     * Sets the alias of the certificate used for issuing <code>WSS</code>
067     * token, i.e. <code>WSS</code>  <code>X509</code> Token, <code>WSS</code>
068     * SAML Token. If the <code>certAlias</code> is never set, a default
069     * certificate will be used for issuing <code>WSS</code> tokens.
070     *
071     * @param certAlias String alias name for the certificate
072     * @throws SecurityTokenException if certificate for the
073     *            <code>certAlias</code> could not be found in key store.
074     */
075    public void setCertAlias(java.lang.String certAlias) 
076        throws SecurityTokenException;
077
078    /**
079     * Sets the  certificate used for issuing <code>WSS</code> token, i.e.
080     * <code>WSS X509</code> Token, <code>WSS</code> SAML Token.
081     * If the certificate is never set, a default certificate will
082     * be used for issuing <code>WSS</code> tokens.
083     *
084     * @param cert <code>X509Certificate</code> object.
085     * @throws SecurityTokenException if the certificate could not be set.
086     */
087    public void setCertificate(X509Certificate cert)
088        throws SecurityTokenException;
089
090    /**
091     * Gets the <code>X509</code> certificate Token.
092     *
093     * @return <code>X509</code> certificate Token.
094     * @throws SecurityTokenException if the token could not be 
095     *        obtained.
096     */
097    public BinarySecurityToken getX509CertificateToken() 
098        throws SecurityTokenException;
099
100    /**
101     * Creates a SAML Assertion for message authentication.
102     *
103     * @param senderIdentity name identifier of the sender.
104     * @return Assertion which contains an <code>AuthenticationStatement</code>.
105     * @throws SecurityTokenException if the assertion could not be
106     *        obtained.
107     * @throws SAMLException
108     */
109    public SecurityAssertion getSAMLAuthenticationToken(
110                                NameIdentifier senderIdentity)
111        throws SecurityTokenException, SAMLException;
112
113    /**
114     * Creates a SAML Assertion for message authorization, the assertion could
115     * optionally contain an <code>AuthenticationStatement</code> which will be
116     * used for message authentication.
117     *
118     * @param senderIdentity name identifier of the sender.
119     * @param invocatorSession <code>SessionContext</code> of  the invocation
120     *        identity, it is normally obtained by the credential reference in
121     *        the SAML <code>AttributeDesignator<code> for discovery resource
122     *        offering which is part of the liberty <code>ID-FF</code>
123     *        <code>AuthenResponse</code>.
124     * @param resourceID id for the resource to be accessed.
125     * @param includeAuthN if true, include an
126     *        <code>AutheticationStatement</code> in
127     *        the Assertion which will be used for message
128     *        authentication. if false, no <code>AuthenticationStatement</code>
129     *        will be included.
130     * @param includeResourceAccessStatement if true, a
131     *        <code>ResourceAccessStatement</code> will be included in the
132     *        Assertion (for <code>AuthorizeRequester</code> directive). If
133     *        false, a <code>SessionContextStatement</code> will be included in
134     *        the Assertion (for <code>AuthenticationSessionContext</code>
135     *        directive). In the case when both <code>AuthorizeRequester</code>
136     *        and <code>AuthenticationSessionContext</code> directive need to be
137     *        handled, use "true" as parameter here since the
138     *        <code>SessionContext</code> will always be included in the
139     *        <code>ResourceAccessStatement</code>.
140     * @param recipientProviderID recipient's provider ID.
141     * @return <code>SecurityAssertion</code> object.
142     * @throws SecurityTokenException if the assertion could not be obtained
143     * @throws SAMLException
144     */
145    public SecurityAssertion getSAMLAuthorizationToken(
146                                NameIdentifier senderIdentity,
147                                SessionContext invocatorSession,
148                                String resourceID,
149                                boolean includeAuthN,
150                                boolean includeResourceAccessStatement,
151                                String recipientProviderID)
152        throws SecurityTokenException, SAMLException;
153
154    /**
155     * Creates a SAML Assertion for message authorization, the assertion could
156     * optionally contain an <code>AuthenticationStatement</code> which will be
157     * used for message authentication.
158     *
159     * @param senderIdentity name identifier of the sender.
160     * @param invocatorSession <code>SessionContext</code> of the invocation
161     *        identity, it is normally obtained by the credential reference in
162     *        the SAML <code>AttributeDesignator</code> for discovery resource
163     *        offering which is part of the liberty <code>ID-FF</code>
164     *        <code>AuthenResponse</code>.
165     * @param encResourceID Encrypted ID for the resource to be accessed.
166     * @param includeAuthN if true, include an
167     *        <code>AutheticationStatement</code> in the Assertion which will be
168     *        used for message authentication. if false, no
169     *        <code>AuthenticationStatement</code> will be included.
170     * @param includeResourceAccessStatement if true, a
171     *        <code>ResourceAccessStatement</code> will be included in the
172     *        Assertion (for <code>AuthorizeRequester</code> directive). If
173     *        false, a <code>SessionContextStatement</code> will be included i
174     *        the Assertion (for <code>AuthenticationSessionContext</code>
175     *        directive). In the case when both <code>AuthorizeRequester</code
176     *        and <code>AuthenticationSessionContext</code> directive need to be
177     *        handled, use "true" as parameter here since the
178     *        <code>SessionContext</code> will always be included in the
179     *        <code>ResourceAccessStatement</code>.
180     * @param recipientProviderID recipient's provider ID.
181     * @return <code>SecurityAssertion</code> object.
182     * @throws SecurityTokenException if the assertion could not be obtained
183     */
184    public SecurityAssertion getSAMLAuthorizationToken(
185                                NameIdentifier senderIdentity,
186                                SessionContext invocatorSession,
187                                EncryptedResourceID encResourceID,
188                                boolean includeAuthN,
189                                boolean includeResourceAccessStatement,
190                                String recipientProviderID)
191        throws SecurityTokenException;
192
193
194    /**
195     * Creates a SAML assertion. The <code>confirmationMethod</code> will be
196     * set to <code>urn:oasis:names:tc:SAML:1.0:cm:bearer</code>.
197     *
198     * @param senderIdentity name identifier of the sender.
199     * @param invocatorSession <code>SessionContext</code> of the invocation
200     *        identity, it is normally obtained by the credential reference in
201     *        the SAML <code>AttributeDesignator</code> for discovery resource
202     *        offering which is part of the liberty <code>ID-FF</code>
203     *        <code>AuthenResponse</code>.
204     * @param resourceID id for the resource to be accessed.
205     * @param includeAuthN if true, include an
206     *        <code>AutheticationStatement</code> in the Assertion which will
207     *        be used for message authentication. if false, no
208     *        <code>AuthenticationStatement</code> will be included.
209     * @param includeResourceAccessStatement if true, a
210     *        <code>ResourceAccessStatement</code> will be included in the
211     *        Assertion (for <code>AuthorizeRequester</code> directive). If
212     *        false, a <code>SessionContextStatement</code> will be included in
213     *        the Assertion (for <code>AuthenticationSessionContext</code>
214     *        directive). In the case when both <code>AuthorizeRequester</code>
215     *        and <code>AuthenticationSessionContext</code> directive need to be
216     *        handled, use "true" as parameter here since the
217     *        <code>SessionContext</code> will always be included in the
218     *        <code>ResourceAccessStatement</code>.
219     * @param recipientProviderID recipient's provider ID.
220     * @return <code>SecurityAssertion</code> object.
221     * @throws SecurityTokenException if the assertion could not be obtained
222     * @throws SAMLException if the assertion could not be obtained
223     */
224    public SecurityAssertion getSAMLBearerToken(
225                                NameIdentifier senderIdentity,
226                                SessionContext invocatorSession,
227                                String resourceID,
228                                boolean includeAuthN,
229                                boolean includeResourceAccessStatement,
230                                String recipientProviderID)
231        throws SecurityTokenException, SAMLException;
232
233
234    /**
235     * Creates a SAML assertion. The <code>confirmationMethod</code> will be
236     * set to <code>urn:oasis:names:tc:SAML:1.0:cm:bearer</code>.
237     *
238     * @param senderIdentity name identifier of the sender.
239     * @param invocatorSession <code>SessionContext</code> of the invocation
240     *        identity, it is normally obtained by the credential reference in
241     *        the SAML <code>AttributeDesignator</code> for discovery resource
242     *        offering which is part of the liberty <code>ID-FF</code>
243     *        <code>AuthenResponse</code>.
244     * @param encResourceID Encrypted ID for the resource to be accessed.
245     * @param includeAuthN if true, include an
246     *        <code>AutheticationStatement</code> in the Assertion which will
247     *        be used for message authentication. if false, no
248     *        <code>AuthenticationStatement</code> will be included.
249     * @param includeResourceAccessStatement if true, a
250     *        <code>ResourceAccessStatement</code> will be included in the
251     *        Assertion (for <code>AuthorizeRequester</code> directive). If
252     *        false, a <code>SessionContextStatement</code> will be included
253     *        in the Assertion (for <code>AuthenticationSessionContext</code>
254     *        directive). In the case when both <code>AuthorizeRequester</code>
255     *        and <code>AuthenticationSessionContext/code> directive need to be
256     *        handled, use "true" as parameter here since the
257     *        <code>SessionContext</code> will always be included in the
258     *        <code>ResourceAccessStatement</code>.
259     * @param recipientProviderID recipient's provider ID.
260     * @return <code>SecurityAssertion</code> object.
261     * @throws SecurityTokenException if the assertion could not be obtained
262     */
263    public SecurityAssertion getSAMLBearerToken(
264                                NameIdentifier senderIdentity,
265                                SessionContext invocatorSession,
266                                EncryptedResourceID encResourceID,
267                                boolean includeAuthN,
268                                boolean includeResourceAccessStatement,
269                                String recipientProviderID)
270        throws SecurityTokenException;
271
272}