java/src/main/com/google/appengine/api/appidentity/AppIdentityService.java

   1 // Copyright 2011 Google Inc. All rights reserved.
   2 package com.google.appengine.api.appidentity;
   3
   4 import java.io.Serializable;
   5 import java.util.Collection;
   6 import java.util.Date;
   7
   8 /**
   9  * The {@code AppIdentityService} allows you to sign arbitrary byte
  10  * array using per app private key maintained by App Egnine, and also
  11  * you can retrieve a list of public certificates which can be used to
  12  * verify the signature.
  13  *
  14  * <p>App Engine is responsible for maintaining per application
  15  * private key.  AppEngine will keep rotating private keys
  16  * periodically. App Engine never gives these private keys to outside.
  17  *
  18  * <p>Since private keys are rotated periodically,
  19  * {@link #getPublicCertificatesForApp} could return a list of public
  20  * certificates, it's caller's responsibility to try these
  21  * certificates one by one when doing signature verification.
  22  *
  23  */
  24 public interface AppIdentityService {
  25
  26   /**
  27    * {@code SigningResult} is returned by signForApp, which contains
  28    * signing key name and signature.
  29    */
  30   public static class SigningResult {
  31     private final String keyName;
  32     private byte[] signature;
  33
  34     public SigningResult(String keyName, byte[] signature) {
  35       this.keyName = keyName;
  36       this.signature = signature;
  37     }
  38
  39     public String getKeyName() {
  40       return keyName;
  41     }
  42
  43     public byte[] getSignature() {
  44       return signature;
  45     }
  46   }
  47
  48   /**
  49    * {@code GetAccessTokenResult} is returned by getAccessToken. It
  50    * contains the access token and the expiration time for the token.
  51    */
  52   public static class GetAccessTokenResult implements Serializable {
  53     private static final long serialVersionUID = 1311635361L;
  54     private final String accessToken;
  55     private final Date expirationTime;
  56
  57     public GetAccessTokenResult(String accessToken, Date expirationTime) {
  58       this.accessToken = accessToken;
  59       this.expirationTime = expirationTime;
  60     }
  61
  62     public String getAccessToken() {
  63       return accessToken;
  64     }
  65
  66      public Date getExpirationTime() {
  67       return expirationTime;
  68     }
  69   }
  70
  71   /**
  72    * Class holding the results of parsing a full application id into its constituent parts.
  73    * @see #parseFullAppId
  74    */
  75   public static final class ParsedAppId {
  76     private final String partition;
  77     private final String domain;
  78     private final String id;
  79
  80     ParsedAppId(String partition, String domain, String id) {
  81       this.partition = partition;
  82       this.domain = domain;
  83       this.id = id;
  84     }
  85
  86     /** Returns the partition the application runs in. */
  87     public String getPartition() {
  88       return partition;
  89     }
  90
  91     /** Returns the application's domain or the empty string if no domain. */
  92     public String getDomain() {
  93       return domain;
  94     }
  95
  96     /** Returns the display application id. */
  97     public String getId() {
  98       return id;
  99     }
 100   }
 101
 102   /**
 103    * Requests to sign arbitrary byte array using per app private key.
 104    *
 105    * @param signBlob string blob.
 106    * @return a SigningResult object which contains signing key name and
 107    * signature.
 108    * @throws AppIdentityServiceFailureException
 109    */
 110   SigningResult signForApp(byte[] signBlob);
 111
 112   /**
 113    * Retrieves a list of public certificates.
 114    *
 115    * @return a list of public certificates.
 116    * @throws AppIdentityServiceFailureException
 117    */
 118   Collection<PublicCertificate> getPublicCertificatesForApp();
 119
 120   /**
 121    * Gets service account name of the app.
 122    *
 123    * @return service account name of the app.
 124    */
 125   String getServiceAccountName();
 126
 127   /**
 128    * Gets the default GS bucket name for the app.
 129    *
 130    * @return default GS bucket name for the app.
 131    */
 132   String getDefaultGcsBucketName();
 133
 134   /**
 135    * OAuth2 access token to act on behalf of the application, uncached.
 136    *
 137    * Most developers should use getAccessToken instead.
 138    *
 139    * @param scopes iterable of scopes to request.
 140    * @return a GetAccessTokenResult object with the access token and expiration
 141    * time.
 142    * @throws AppIdentityServiceFailureException
 143    */
 144   GetAccessTokenResult getAccessTokenUncached(Iterable<String> scopes);
 145
 146   /**
 147    * OAuth2 access token to act on behalf of the application.
 148    *
 149    * Generates and caches an OAuth2 access token for the service account for the
 150    * appengine application.
 151    *
 152    * Each application has an associated Google account. This function returns
 153    * OAuth2 access token corresponding to the running app. Access tokens are
 154    * safe to cache and reuse until their expiry time as returned. This method
 155    * will do that using memcache.
 156    *
 157    * @param scopes iterable of scopes to request.
 158    * @return a GetAccessTokenResult object with the access token and expiration
 159    * time.
 160    * @throws AppIdentityServiceFailureException
 161    */
 162   GetAccessTokenResult getAccessToken(Iterable<String> scopes);
 163
 164   /**
 165    * Parse a full app id into partition, domain name and display app_id.
 166    *
 167    * @param fullAppId The full partitioned app id.
 168    * @return An {@link ParsedAppId} instance with the parsing results.
 169    */
 170   ParsedAppId parseFullAppId(String fullAppId);
 171 }