|
|
| (36 intermediate revisions by 2 users not shown) |
| Line 1: |
Line 1: |
| − | {{#eclipseproject:technology.higgins|eclipse_custom_style.css}}
| + | #REDIRECT [[CardSync Web App]] |
| − | | + | |
| − | [[Image:Higgins_logo_76Wx100H.jpg|right]] | + | |
| − | | + | |
| − | This page describes the design of the CardSync protocol. This is a sub-project within the overall [[Selector Architecture Harmonization]] project.
| + | |
| − | | + | |
| − | It has already been decided that this protocol will be RESTful and not use SOAP.
| + | |
| − | | + | |
| − | == Data Transfer objects ==
| + | |
| − | | + | |
| − | ===UML class diagram===
| + | |
| − | [[Image:Org.eclipse.higgins.rpps.sync.ClassDiagram.jpg|800x400px]]
| + | |
| − | | + | |
| − | ===Xsd schema===
| + | |
| − | [[Image:Cardsync.xsd.zip]]<br>
| + | |
| − | | + | |
| − | ===AccessTokenTO===
| + | |
| − | public class AccessTokenTO<br>
| + | |
| − | extends java.lang.Object<br>
| + | |
| − | implements java.io.Serializable<br>
| + | |
| − | <br>
| + | |
| − | | + | |
| − | AccessToken transfer object. See [[#Authentication]]<br>
| + | |
| − | <br>
| + | |
| − | private java.lang.String id Represents token identifier.<br>
| + | |
| − | private java.util.Date issuedTime Represents issued date time.<br>
| + | |
| − | private java.lang.Integer maxIdleTime Represents max idle time in seconds.<br>
| + | |
| − | | + | |
| − | ===BaseTO===
| + | |
| − | | + | |
| − | public class BaseTO<br>
| + | |
| − | extends java.lang.Object<br>
| + | |
| − | implements java.io.Serializable<br>
| + | |
| − | <br>
| + | |
| − | Base transfer object. All resources should extend it. <br><br>
| + | |
| − | | + | |
| − | private java.lang.String id Represents unique resource server identifier.<br>
| + | |
| − | private RevisionTO revision Represents revision information.<br>
| + | |
| − | | + | |
| − | === RevisionTO ===
| + | |
| − | public class RevisionTO<br>
| + | |
| − | extends java.lang.Object<br>
| + | |
| − | implements java.io.Serializable<br><br>
| + | |
| − | | + | |
| − | Resource revision transfer object. <br>
| + | |
| − | | + | |
| − | private java.util.Date modifiedTime Represents last modified date.<br>
| + | |
| − | private java.lang.Long number Represents revision number.<br>
| + | |
| − | | + | |
| − | === CardTO ===
| + | |
| − | public class CardTO
| + | |
| − | extends BaseTO
| + | |
| − | implements java.io.Serializable
| + | |
| − | | + | |
| − | Card transfer object. <br>
| + | |
| − | | + | |
| − | private java.lang.String cardId Represents card identifier.<br>
| + | |
| − | private ClaimTO[] claims Card claims.<br>
| + | |
| − | private java.util.Date expiredTime Card expired date.<br>
| + | |
| − | private CardExtensionTO[] extensions Card extensions.<br>
| + | |
| − | private byte[] hashSalt Card hash salt.<br>
| + | |
| − | private byte[] image Card image.<br>
| + | |
| − | private java.lang.String imageType Card image mime type.<br>
| + | |
| − | private java.util.Date issuedTime Issued(created) time.
| + | |
| − | private java.lang.String issuer Card issuer name.<br>
| + | |
| − | private byte[] issuerID Card issuer identifier.<br>
| + | |
| − | private java.lang.String issuerName Human friendly card issuer name.<br>
| + | |
| − | private java.util.Date lastUpdatedTime Last card updated date.<br>
| + | |
| − | private byte[] masterKey Card master key.<br>
| + | |
| − | private java.lang.String name Human friendly card name.<br>
| + | |
| − | private java.lang.Boolean selfIssued Is card self issued.<br>
| + | |
| − | private ClaimTypeTO[] supportedClaimTypes Represents array of all possible types of claim that are supported.<br>
| + | |
| − | private java.lang.String[] supportedTokenTypes Represents arrays of token types which can be provided for this card.<br>
| + | |
| − | private java.lang.String version Card version.<br>
| + | |
| − |
| + | |
| − | === MCardTO ===
| + | |
| − | public class MCardTO<br>v
| + | |
| − | extends CardTO<br>
| + | |
| − | implements java.io.Serializable<br><br>
| + | |
| − | | + | |
| − | Managed card transfer object. <br>
| + | |
| − | | + | |
| − | private java.lang.String ic07IssuerInformation Represents /ic07:IssuerInformation extension element<br>
| + | |
| − | private java.lang.Boolean requireAppliesTo Represents requireAppliesTo card element.<br>
| + | |
| − | private java.lang.Boolean strongRecipientIdentityRequired Represents /ic07:RequireStrongRecipientIdentity extension element If true than Selector MUST only allow the card to be used at a Relying Party that presents a cryptographically protected identity X.509v3 certificate.<br>
| + | |
| − | private StsPrivacyPolicyTO stsPrivacyPolicyTO STS/IdP privacy policy<br>
| + | |
| − | private TokenServiceTO[] tokenServices Represents array of security token services.<br>
| + | |
| − |
| + | |
| − | === PCardTO ===
| + | |
| − | public class PCardTO<br>
| + | |
| − | extends CardTO<br>
| + | |
| − | implements java.io.Serializable<br><br>
| + | |
| − | | + | |
| − | Personal card transfer object. <br>
| + | |
| − | | + | |
| − | private byte[] pinDigest Contains the base64 encoded bytes of the SHA1 hash of the pin code<br>
| + | |
| − | | + | |
| − | === ClaimTO ===
| + | |
| − | public class ClaimTO<br>
| + | |
| − | extends java.lang.Object<br>
| + | |
| − | implements java.io.Serializable<br><br>
| + | |
| − | | + | |
| − | Card claim transfer object. <br>
| + | |
| − | | + | |
| − | private ClaimTO[] claims Contains sub-claims if claim is complex claim.<br>
| + | |
| − | private ClaimTypeTO claimType Represents claim type<br>
| + | |
| − | private ClaimUiDescriptor claimUiDescriptor Represents meta information for building user friendly claim editor.<br>
| + | |
| − | private java.lang.String[] values Represents claim values.<br>
| + | |
| − | | + | |
| − | === ClaimUiDescriptor ===
| + | |
| − | public class ClaimUiDescriptor<br>
| + | |
| − | extends java.lang.Object<br>
| + | |
| − | implements java.io.Serializable<br><br>
| + | |
| − | | + | |
| − | Claim user interface descriptor transfer object. Has meta information for building user friendly claim editor. <br>
| + | |
| − | | + | |
| − | private java.lang.String inputMask Might contain input mask for formating claim value on client side.<br>
| + | |
| − | private java.lang.String[] optionalValues Should contain possible optional values If type equal 4 (TYPE_COMBOBOX ).<br>
| + | |
| − | private java.lang.String pattern Might contain regular express for validating user input on client side.<br>
| + | |
| − | private java.lang.String type Defines claim editor type.
| + | |
| − | <ul>
| + | |
| − | <li>TextField GUI component type TYPE_TEXTFILED = 0;</li>
| + | |
| − | <li>TextArea GUI component type TYPE_TEXTAREA = 1;</li>
| + | |
| − | <li>FileChooser GUI component type TYPE_FILE = 2;</li>
| + | |
| − | <li>CheckField GUI component type TYPE_CHECKBOX = 3;</li>
| + | |
| − | <li>ComboBox GUI component type TYPE_COMBOBOX = 4;</li>
| + | |
| − | <li>Date(time) GUI component type TYPE_DATETIME = 5.</li>
| + | |
| − | </ul>
| + | |
| − | <br>
| + | |
| − | | + | |
| − | === ClaimTypeTO===
| + | |
| − | public class ClaimTypeTO<br>
| + | |
| − | extends java.lang.Object<br>
| + | |
| − | implements java.io.Serializable<br><br>
| + | |
| − | | + | |
| − | ClaimType transfer object. <br>
| + | |
| − | | + | |
| − | private java.lang.String description Represents description.<br>
| + | |
| − | private java.lang.String displayName Represents the human friendly name.<br>
| + | |
| − | private java.lang.Boolean isSimple Determines whether corresponding IClaim is simple or complex.<br>
| + | |
| − | private java.lang.String type Represents type URI.<br>
| + | |
| − | | + | |
| − | === CardExtensionTO ===
| + | |
| − | public class CardExtensionTO<br>
| + | |
| − | extends java.lang.Object<br>
| + | |
| − | implements java.io.Serializable<br><br>
| + | |
| − | | + | |
| − | CardExtension transfer object. <br>
| + | |
| − | | + | |
| − | private java.lang.Boolean enabled Is extension enabled.<br>
| + | |
| − | private java.lang.String extensionXmlElement Represents extension element data.<br>
| + | |
| − | | + | |
| − | === StsPrivacyPolicyTO ===
| + | |
| − | public class StsPrivacyPolicyTO<br>
| + | |
| − | extends java.lang.Object<br>
| + | |
| − | implements java.io.Serializable<br><br>
| + | |
| − | | + | |
| − | STS/IdP privacy policy transfer object.<br>
| + | |
| − | | + | |
| − | private java.lang.String url STS/IdP privacy policy url.<br>
| + | |
| − | private java.lang.String version STS/IdP privacy policy version.<br>
| + | |
| − | | + | |
| − | === TokenServiceTO ===
| + | |
| − | public class TokenServiceTO<br>
| + | |
| − | extends java.lang.Object<br>
| + | |
| − | implements java.io.Serializable<br><br>
| + | |
| − | | + | |
| − | Token service transfer object. <br>
| + | |
| − | | + | |
| − | private EndpointReferenceTO endpointReference Represents Token Service endpoint.<br>
| + | |
| − | private CredentialDescriptorTO userCredential Represents Token Service credential.<br>
| + | |
| − | | + | |
| − | === CredentialDescriptorTO ===
| + | |
| − | public class CredentialDescriptorTO<br>
| + | |
| − | extends java.lang.Object<br>
| + | |
| − | implements java.io.Serializable<br><br>
| + | |
| − | | + | |
| − | Token service credential descriptor transfer object. <br>
| + | |
| − | | + | |
| − | private java.lang.String credentialXmlElement Represent xml element.<br>
| + | |
| − | private java.lang.String displayCredentialHint Represent user friendly credential hint.<br>
| + | |
| − | private java.lang.String type Represent credential type.
| + | |
| − | <ul>
| + | |
| − | <li>SelfIssuedCredential;</li>
| + | |
| − | <li>X509V3Credential</li>
| + | |
| − | <li>KerberosV5Credential</li>
| + | |
| − | <li>UsernamePasswordCredential</li>
| + | |
| − | </ul><br>
| + | |
| − |
| + | |
| − | === EndpointReferenceTO ===
| + | |
| − | public class EndpointReferenceTO<br>
| + | |
| − | extends java.lang.Object<br>
| + | |
| − | implements java.io.Serializable<br><br>
| + | |
| − | | + | |
| − | Token service Endpoint reference transfer object. <br>
| + | |
| − | | + | |
| − | private java.net.URI address Represents address.<br>
| + | |
| − | private java.lang.String identityXml Represents Identity element of TokenService.<br>
| + | |
| − | private java.net.URI metadataAddress Represents Metadata Address URI if Metadata contains it.<br>
| + | |
| − | private java.lang.String metadataXml Represents Metadata element of TokenService.<br>
| + | |
| − | | + | |
| − | === CardHistoryTO ===
| + | |
| − | public class CardHistoryTO<br>
| + | |
| − | extends BaseTO<br>
| + | |
| − | implements java.io.Serializable<br><br>
| + | |
| − | | + | |
| − | Card history transfer object. <br>
| + | |
| − | | + | |
| − | private java.util.Date date Represents date time of card usage.<br>
| + | |
| − | private WebFormTO form Represents html web form elements.<br>
| + | |
| − | | + | |
| − | === WebFormTO ===
| + | |
| − | public class WebFormTO<br>
| + | |
| − | extends java.lang.Object<br>
| + | |
| − | implements java.io.Serializable<br><br>
| + | |
| − | | + | |
| − | Web form transfer object. <br>
| + | |
| − | | + | |
| − | private java.lang.String formAction Represents html form action element.<br>
| + | |
| − | private java.lang.String formId Represents html form id element.<br>
| + | |
| − | private java.lang.String formName Represents html form name element.<br>
| + | |
| − | private java.net.URI url Represents web page URL.<br>
| + | |
| − | | + | |
| − | === CardCategoryTO ===
| + | |
| − | public class CardCategoryTO<br>
| + | |
| − | extends BaseTO<br>
| + | |
| − | implements java.io.Serializable<br><br>
| + | |
| − | | + | |
| − | Card category transfer object. <br>
| + | |
| − | | + | |
| − | private java.lang.String[] cuids Represents associated card id array.<br>
| + | |
| − | private int idx Represents category index.<br>
| + | |
| − | private java.lang.String name Represents category name.<br>
| + | |
| − | private java.lang.String parentId Represents parent category identifier.<br>
| + | |
| − | private java.lang.String type Represents category type.<br>
| + | |
| − | | + | |
| − | === UserProfileTO ===
| + | |
| − | public class UserProfileTO<br>
| + | |
| − | extends BaseTO<br>
| + | |
| − | implements java.io.Serializable<br><br>
| + | |
| − | | + | |
| − | User profile transfer object. <br>
| + | |
| − | | + | |
| − | private java.util.Date createdTime Represents user account created date.<br>
| + | |
| − | private java.lang.String email Represents user email address.<br>
| + | |
| − | private java.lang.String firstName Represents user first name.<br>
| + | |
| − | private java.lang.String lastName Represents user last name.<br>
| + | |
| − | private java.lang.String loginName Represents user login name.<br>
| + | |
| − | private java.lang.String mobile Represents user mobile number.<br>
| + | |
| − | private java.util.Date modifiedTime Represents last updated date.<br>
| + | |
| − | | + | |
| − | === CardCredentialTO ===
| + | |
| − | public class CardCredentialTO<br>
| + | |
| − | extends BaseTO<br>
| + | |
| − | implements java.io.Serializable<br><br>
| + | |
| − | | + | |
| − | Card credential transfer object. <br>
| + | |
| − | private java.lang.String credentialType Represent credential type.<br>
| + | |
| − | | + | |
| − | === UsernamePasswordCredentialTO ===
| + | |
| − | public class UsernamePasswordCredentialTO<br>
| + | |
| − | extends CardCredentialTO<br>
| + | |
| − | implements java.io.Serializable<br><br>
| + | |
| − | | + | |
| − | UsernamePasswordCredential credential transfer object. It needs for supporting auto-login. <br>
| + | |
| − | | + | |
| − | private java.net.URI tsAddress Represents STS/IdP addres.<br>
| + | |
| − | private java.net.URI tsMetadataAddress Represents STS/IdP meta address<br>
| + | |
| − | private java.lang.String username Represents username.<br>
| + | |
| − | | + | |
| − | === PinCredentialTO ===
| + | |
| − | public class PinCredentialTO<br>
| + | |
| − | extends CardCredentialTO<br>
| + | |
| − | implements java.io.Serializable<br><br>
| + | |
| − | | + | |
| − | PinCredential transfer object. <br>
| + | |
| − | | + | |
| − | private byte[] pinCode Represents pinCode.<br>
| + | |
| − | | + | |
| − | === UseAlwaysTO ===
| + | |
| − | public class UseAlwaysTO<br>
| + | |
| − | extends BaseTO<br>
| + | |
| − | implements java.io.Serializable<br><br>
| + | |
| − | | + | |
| − | UseAlways transfer object. It needs for supporting auto-login. <br>
| + | |
| − | | + | |
| − | private WebFormTO form Represents html web form elements.<br>
| + | |
| − | | + | |
| − | === CaptchaTO ===
| + | |
| − | public class CaptchaTO<br>
| + | |
| − | extends BaseTO<br>
| + | |
| − | implements java.io.Serializable<br><br>
| + | |
| − | | + | |
| − | Captcha transfer object. It needs for password-reset workflow.
| + | |
| − | | + | |
| − | private byte[] image Captcha image.<br>
| + | |
| − | | + | |
| − | === OperationTO ===
| + | |
| − | public class OperationTO<br>
| + | |
| − | extends java.lang.Object<br>
| + | |
| − | implements java.io.Serializable<br><br>
| + | |
| − | | + | |
| − | Log operation transfer object. <br>
| + | |
| − | | + | |
| − | private java.lang.String name Represents operation/command name. It will be one of the following constants:<ul>
| + | |
| − | <li>Persist</li>
| + | |
| − | <li>Delete</li>
| + | |
| − | <li>DeleteAll</li></ul>
| + | |
| − | private BaseTO resource Represents resource. It might be null for "Delete".<br>
| + | |
| − | private java.lang.String resourceId Represents server resource identifier. It might be null for "DeleteAll".<br>
| + | |
| − | private java.lang.String resourceType Represents resource type.<br>
| + | |
| − | <br>
| + | |
| − | | + | |
| − | == Exceptions ==
| + | |
| − | Coming soon.
| + | |
| − | | + | |
| − | == Authentication ==
| + | |
| − | Almost all Card Sync Web App methods requres user authentication (excepts addUserProfile, getPasswordResetCode etc).
| + | |
| − | These diagrams illustrate the sequence of interactions between Local ICard Selector and Card Sync Web App.
| + | |
| − | [[Image:AuthenticationUSD.jpg|790x400px]]
| + | |
| − | [[Image:AuthenticationULD.jpg|790x400px]]
| + | |
| − | | + | |
| − | ===Authentication Process===
| + | |
| − | 1. Get Access Token (Sign on). See [[#AccessTokenTO]]<br>
| + | |
| − | 1.1 Local ICard Selector contacts the Card Sync Web App, asking for AccessTokenTO by using username/password credential getAccessToken(userIdentifier,password).<br>
| + | |
| − | 1.2 Card Sync Web App invokes authenticate(userIdentifier, password) Card Sync Service method. <br>
| + | |
| − | 1.3 Card Sync Service delegate authentication to ILoginService (JAAS).<br>
| + | |
| − | 1.4 if ILoginService may authenticate user it return UserAccout instance (it needs for accessing protected data).<br>
| + | |
| − | 1.5 Card Sync Web App invokes buildAccessToken(userAccount) Card Sync Service method for generating AccessToken.<br>
| + | |
| − | 1.6 Card Sync Service builds and stores AccessToken.<br>
| + | |
| − | 1.7 Card Sync Web App return AccessTokenTO to Local ICard Selector.<br>
| + | |
| − | <br><br>
| + | |
| − | 2. Get user protected data.<br>
| + | |
| − | 2.1 Local ICard Selector asking Card Sync Web App for protected data by using Access Token Identifier (AccessTokenTO.id).<br>
| + | |
| − | 2.2 Card Sync Web App delegate validation of Access Token Identifier to Card Sync Service checkAccessToken(AccessTokenTO.id).<br>
| + | |
| − | 2.3 if Access Token Identifier is valid Card Sync Service return AccessToken.<br>
| + | |
| − | 2.4 Card Sync Web App retrieve protected data by using AccessToken.<br>
| + | |
| − | 2.5 Card Sync Web App return protected data to Local ICard Selector.<br>
| + | |
| − | <br>
| + | |
| − | 3. Delete Access Token (Sign out).<br>
| + | |
| − | 3.1 Local ICard Selector has to invoke deleteAccessToken(AccessTokenTO.id) Card Sync Web App method.<br>
| + | |
| − | 3.2 Card Sync Web App delegates it to Card Sync Service by using deleteAccessToken(id) method.<br>
| + | |
| − | | + | |
| − | ----
| + | |
| − | | + | |
| − | ===Pass Access Token Identifier with HTTP header "access_token"===
| + | |
| − | We're going to support Rest API for synchronizing user cards. It assumes to use http GET requests for retrieving protectedn data, so it has to include Access Token Identifier to request url. if we pass Access Token Identifier by using http header, it may be more protected way (of course only with https).
| + | |
| − | | + | |
| − | Both Rest and Soap web services would read access token from http headers.
| + | |
| − | | + | |
| − | ===Encrypt/Decrypt Access Token Identifier===
| + | |
| − | For prevent unauthorized access, we would encrypt Access Token Identifier by using public user key (on server side) and public server key (on client side).
| + | |
| − | | + | |
| − | ===Access Token idle timeout===
| + | |
| − | if Access Token wasn't used more than idle timeout, it will be deleted automatically.
| + | |
| − | | + | |
| − | ===Single sign on ===
| + | |
| − | We would support single sign-on/sign-out workflow. it makes sense by secure reason ( and it may be useful for r-card solution).
| + | |
| − | | + | |
| − | === Authentication with OpenId, X509Certificate, ...===
| + | |
| − | For supporting new authentication type we have to add just one method getAccessToken(new credential data ).
| + | |
| − | | + | |
| − | == JAX-RS API ==
| + | |
| − | Coming soon.
| + | |
| − | | + | |
| − | === Resources ===
| + | |
| − | Coming soon.
| + | |
| − | | + | |
| − | ==== MCard ====
| + | |
| − | ==== PCard ====
| + | |
| − | ==== CardHistory ====
| + | |
| − | ==== CardCategory ====
| + | |
| − | ==== CardCredential ====
| + | |
| − | ==== UseAlways ====
| + | |
| − | ==== UserProfile ====
| + | |
| − | | + | |
| − | === WADL ===
| + | |
| − | === Serializable formats ===
| + | |
| − | | + | |
| − | ==== XML(application/xml) ====
| + | |
| − | ==== JSON(application/json) ====
| + | |
| − | | + | |
| − | ==== Google protobuf (application/x-protobuf) ====
| + | |
| − | http://code.google.com/p/protobuf/
| + | |
| − | ==== X3 (application/x3) ====
| + | |
| − | | + | |
| − | == JAX-WS API ==
| + | |
| − | Coming soon.
| + | |
| − | | + | |
| − | === WSDL ===
| + | |
| − | === Serializable formats ===
| + | |
| − | === SOAP (application/soap+xml) ====
| + | |
| − | | + | |
| − | == Sequences ==
| + | |
| − | === Synchronize card ===
| + | |
| − | === Synchronize card history ===
| + | |
| − | === Synchronize card category ===
| + | |
| − | === Synchronize user profile ===
| + | |
