Add new SignatureProvider constructor for instance principal delegation tokens.

Author: gmfeinberg

CHANGELOG.md

@@ -17,6 +17,9 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/).
   - For successful operations, retry stats can be retrieved using Result.getRetryStats().
   - Otherwise, the original Request may have retry stats available via Request.getRetryStats() (for example, after an exception was thrown).
 - Cloud only: New regions: ap-chiyoda-1, me-dubai-1, uk-cardiff-1 and sa-santiago-1
+- Cloud only: Added new SignatureProvider constructors to allow use of an instance
+principal with a delegation token for authorization and authentication:
+ - SignatureProvider.createInstancePrincipalForDelegation()
 
 ### Fixed
 - Ensure that TableLimits is always null in TableResult on-premise.

driver/src/main/java/oracle/nosql/driver/iam/SignatureProvider.java

@@ -99,6 +99,9 @@ public class SignatureProvider
     implements AuthorizationProvider, RegionProvider {
 
     private static final String SIGNING_HEADERS = "(request-target) host date";
+    private static final String SIGNING_HEADERS_WITH_OBO =
+        "(request-target) host date opc-obo-token";
+    private static final String OBO_TOKEN_HEADER = "opc-obo-token";
 
     /* Cache key name */
     private static final String CACHE_KEY = "signature";
@@ -113,6 +116,9 @@ public class SignatureProvider
     private final AuthenticationProfileProvider provider;
     private final PrivateKeyProvider privateKeyProvider;
 
+    /* Delegation token specified for signing */
+    private String delegationToken;
+
     private final LruCache<String, SignatureDetails> signatureCache;
 
     /* Refresh timer */
@@ -377,6 +383,79 @@ public static SignatureProvider createWithInstancePrincipal(Region region) {
         return provider;
     }
 
+    /**
+     * Creates a SignatureProvider using an instance principal with a
+     * delegation token. This constructor may be used when calling the
+     * Oracle NoSQL Database Cloud Service from an Oracle Cloud compute
+     * instance. It authenticates with the instance principal and uses a
+     * security token issued by IAM to do the actual request signing.
+     * The delegation token allows the instance to assume the privileges
+     * of the user for which the token was created.
+     * <p>
+     * When using an instance principal the compartment id (OCID) must be
+     * specified on each request or defaulted by using
+     * {@link NoSQLHandleConfig#setDefaultCompartment}. If the compartment id
+     * is not specified for an operation an exception will be thrown.
+     * <p>
+     * See <a href="https://docs.cloud.oracle.com/iaas/Content/Identity/Tasks/callingservicesfrominstances.htm">Calling Services from Instances</a>.
+     *
+     * @param delegationToken this token allows an instance to assume the
+     * privileges of a specific user and act on-behalf-of that user
+     *
+     * @return SignatureProvider
+     */
+    public static SignatureProvider
+        createWithInstancePrincipalForDelegation(String delegationToken) {
+
+        SignatureProvider provider = new SignatureProvider(
+            InstancePrincipalsProvider.builder().build());
+        provider.setDelegationToken(delegationToken);
+        return provider;
+    }
+
+    /**
+     * Creates a SignatureProvider using an instance principal with a
+     * delegation token. This constructor may be used when calling the
+     * Oracle NoSQL Database Cloud Service from an Oracle Cloud compute
+     * instance. It authenticates with the instance principal and uses a
+     * security token issued by IAM to do the actual request signing.
+     * The delegation token allows the instance to assume the privileges
+     * of the user for which the token was created.
+     * <p>
+     * When using an instance principal the compartment id (OCID) must be
+     * specified on each request or defaulted by using
+     * {@link NoSQLHandleConfig#setDefaultCompartment}. If the compartment id
+     * is not specified for an operation an exception will be thrown.
+     * <p>
+     * See <a href="https://docs.cloud.oracle.com/iaas/Content/Identity/Tasks/callingservicesfrominstances.htm">Calling Services from Instances</a>.
+     *
+     * @param iamAuthUri The URI is usually detected automatically, specify
+     * the URI if you need to overwrite the default, or encounter the
+     * <code>Invalid IAM URI</code> error.
+     * @param region the region to use, it may be null
+     * @param delegationToken this token allows an instance to assume the
+     * privileges of a specific user and act on-behalf-of that user
+     * @param logger the logger used by the SignatureProvider.
+     *
+     * @return SignatureProvider
+     */
+    public static SignatureProvider
+        createWithInstancePrincipalForDelegation(String iamAuthUri,
+                                                 Region region,
+                                                 String delegationToken,
+                                                 Logger logger) {
+
+        SignatureProvider provider = new SignatureProvider(
+            InstancePrincipalsProvider.builder()
+            .setFederationEndpoint(iamAuthUri)
+            .setLogger(logger)
+            .setRegion(region)
+            .build());
+        provider.setLogger(logger);
+        provider.setDelegationToken(delegationToken);
+        return provider;
+    }
+
     /**
      * Creates a SignatureProvider using a resource principal. This
      * constructor may be used when calling the Oracle NoSQL Database
@@ -486,6 +565,9 @@ public void setRequiredHeaders(String authString,
         headers.add(AUTHORIZATION, sigDetails.getSignatureHeader());
         headers.add(DATE, sigDetails.getDate());
 
+        if (delegationToken != null) {
+            headers.add(OBO_TOKEN_HEADER, delegationToken);
+        }
         String compartment = request.getCompartment();
         if (compartment == null) {
             /*
@@ -579,6 +661,11 @@ public String getResourcePrincipalClaim(String key) {
         return rpp.getClaim(key);
     }
 
+    /* visible for testing */
+    void setDelegationToken(String token) {
+        this.delegationToken = token;
+    }
+
     private void logMessage(Level level, String msg) {
         if (logger != null) {
             logger.log(level, msg);
@@ -611,8 +698,10 @@ synchronized SignatureDetails getSignatureDetailsInternal() {
             return null;
         }
 
+        String signingHeader = (delegationToken == null)
+            ? SIGNING_HEADERS : SIGNING_HEADERS_WITH_OBO;
         String sigHeader = String.format(SIGNATURE_HEADER_FORMAT,
-                                         SIGNING_HEADERS,
+                                         signingHeader,
                                          keyId,
                                          RSA,
                                          signature,
@@ -631,6 +720,11 @@ String signingContent(String date) {
         .append(HOST).append(HEADER_DELIMITER)
         .append(serviceHost).append("\n")
         .append(DATE).append(HEADER_DELIMITER).append(date);
+
+        if (delegationToken != null) {
+            sb.append("\n").append(OBO_TOKEN_HEADER)
+              .append(HEADER_DELIMITER).append(delegationToken);
+        }
         return sb.toString();
     }
 

driver/src/test/java/oracle/nosql/driver/iam/InstancePrincipalsProviderTest.java

@@ -8,6 +8,7 @@
 package oracle.nosql.driver.iam;
 
 import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertTrue;
 import static org.junit.Assert.fail;
 
 import java.io.ByteArrayInputStream;
@@ -22,9 +23,12 @@
 
 import oracle.nosql.driver.DriverTestBase;
 import oracle.nosql.driver.FreePortLocator;
+import oracle.nosql.driver.NoSQLHandleConfig;
 import oracle.nosql.driver.Region;
 import oracle.nosql.driver.iam.CertificateSupplier.DefaultCertificateSupplier;
 import oracle.nosql.driver.iam.CertificateSupplier.URLResourceDetails;
+import oracle.nosql.driver.ops.Request;
+import oracle.nosql.driver.ops.TableRequest;
 
 import org.junit.AfterClass;
 import org.junit.Before;
@@ -35,6 +39,9 @@
 import com.sun.net.httpserver.HttpHandler;
 import com.sun.net.httpserver.HttpServer;
 
+import io.netty.handler.codec.http.DefaultHttpHeaders;
+import io.netty.handler.codec.http.HttpHeaders;
+
 public class InstancePrincipalsProviderTest extends DriverTestBase {
     private static final FreePortLocator portLocator =
         new FreePortLocator("localhost", 4242, 14000);
@@ -168,6 +175,43 @@ public void testBasic()
         assertEquals("ST$" + securityToken(), provider.getKeyId());
     }
 
+    @Test
+    public void testDelegationToken()
+        throws Exception {
+
+        CertificateSupplier leaf = new DefaultCertificateSupplier(
+            getURLDetails(base + "/instance?cert.pem"),
+            getURLDetails(base + "/instance?key.pem"),
+            (char[]) null);
+
+        CertificateSupplier inter = new DefaultCertificateSupplier(
+            getURLDetails(base + "/instance?intermediate.pem"),
+            null,
+            (char[]) null);
+
+        InstancePrincipalsProvider provider =
+            InstancePrincipalsProvider.builder()
+            .setFederationEndpoint(base)
+            .setLeafCertificateSupplier(leaf)
+            .setIntermediateCertificateSuppliers(Collections.singleton(inter))
+            .setTenantId(tenantId)
+            .build();
+
+        SignatureProvider sp = new SignatureProvider(provider);
+        String delegationToken = "fake-token";
+        sp.setServiceHost(new NoSQLHandleConfig("http://test"));
+        sp.setDelegationToken(delegationToken);
+
+        Request request = new TableRequest();
+        request.setCompartmentInternal("compartment");
+        String authzString = sp.getAuthorizationString(request);
+        assertTrue(authzString.contains("opc-obo-token"));
+
+        HttpHeaders headers = new DefaultHttpHeaders();
+        sp.setRequiredHeaders(authzString, request, headers);
+        assertEquals(headers.get("opc-obo-token"), delegationToken);
+    }
+
     @Test
     public void testDefaultCertificateSupplier()
         throws Exception {