Skip to main content
Version: 0.5.0

Security

Authentication

Gravitino supports two kinds of authentication mechanisms: simple and OAuth.

Simple mode

Simple mode is the default authentication option.

Simple mode allows the client to use the environment variable GRAVITINO_USER as the user.

If the environment variable GRAVITINO_USER isn't set, the client uses the user of the machine that sends requests.

For the client side, users can enable simple mode by the following code:

GravitinoClient client = GravitinoClient.builder(uri)
.withMetalake("metalake")
.withSimpleAuth()
.build();

OAuth mode

Gravitino only supports external OAuth 2.0 servers.

First, users need to guarantee that the external correctly configured OAuth 2.0 server supports Bearer JWT.

Then, on the server side, users should set gravitino.authenticator as oauth and give gravitino.authenticator.oauth.defaultSignKey, gravitino.authenticator.oauth.serverUri and gravitino.authenticator.oauth.tokenPath a proper value.

Next, for the client side, users can enable OAuth mode by the following code:

DefaultOAuth2TokenProvider authDataProvider = DefaultOAuth2TokenProvider.builder()
.withUri("oauth server uri")
.withCredential("yy:xx")
.withPath("oauth/token")
.withScope("test")
.build();

GravitinoClient client = GravitinoClient.builder(uri)
.withMetalake("metalake")
.withOAuth(authDataProvider)
.build();

Kerberos mode

Gravitino supports Kerberos mode.

For the server side, users should set gravitino.authenticator as kerberos and give gravitino.authenticator.kerberos.principal and gravitino.authenticator.kerberos.keytab a proper value.

For the client side, users can enable kerberos mode by the following code:

// Use keytab to create KerberosTokenProvider
KerberosTokenProvider provider = KerberosTokenProvider.builder()
.withClientPrincipal(clientPrincipal)
.withKeyTabFile(new File(keytabFile))
.build();

// Use ticketCache to create KerberosTokenProvider
KerberosTokenProvider provider = KerberosTokenProvider.builder()
.withClientPrincipal(clientPrincipal)
.build();

GravitinoClient client = GravitinoClient.builder(uri)
.withMetalake("metalake")
.withKerberosAuth(provider)
.build();
info

Now Iceberg REST service doesn't support Kerberos authentication. The URI must use the hostname of server instead of IP.

Server configuration

Configuration itemDescriptionDefault valueRequiredSince version
gravitino.authenticatorThe authenticator which Gravitino uses, setting as simple,oauth or kerberos.simpleNo0.3.0
gravitino.authenticator.oauth.serviceAudienceThe audience name when Gravitino uses OAuth as the authenticator.GravitinoServerNo0.3.0
gravitino.authenticator.oauth.allowSkewSecsThe JWT allows skew seconds when Gravitino uses OAuth as the authenticator.0No0.3.0
gravitino.authenticator.oauth.defaultSignKeyThe signing key of JWT when Gravitino uses OAuth as the authenticator.(none)Yes if use oauth as the authenticator0.3.0
gravitino.authenticator.oauth.signAlgorithmTypeThe signature algorithm when Gravitino uses OAuth as the authenticator.RS256No0.3.0
gravitino.authenticator.oauth.serverUriThe URI of the default OAuth server.(none)Yes if use oauth as the authenticator0.3.0
gravitino.authenticator.oauth.tokenPathThe path for token of the default OAuth server.(none)Yes if use oauth as the authenticator0.3.0
gravitino.authenticator.kerberos.principalIndicates the Kerberos principal to be used for HTTP endpoint. Principal should start with HTTP/.(none)Yes if use kerberos as the authenticator0.4.0
gravitino.authenticator.kerberos.keytabLocation of the keytab file with the credentials for the principal.(none)Yes if use kerberos as the authenticator0.4.0

The signature algorithms that Gravitino supports follows:

NameDescription
HS256HMAC using SHA-25A
HS384HMAC using SHA-384
HS512HMAC using SHA-51
RS256RSASSA-PKCS-v1_5 using SHA-256
RS384RSASSA-PKCS-v1_5 using SHA-384
RS512RSASSA-PKCS-v1_5 using SHA-512
ES256ECDSA using P-256 and SHA-256
ES384ECDSA using P-384 and SHA-384
ES512ECDSA using P-521 and SHA-512
PS256RSASSA-PSS using SHA-256 and MGF1 with SHA-256
PS384RSASSA-PSS using SHA-384 and MGF1 with SHA-384
PS512RSASSA-PSS using SHA-512 and MGF1 with SHA-512

Example

You can follow the steps to set up an OAuth mode Gravitino server.

  1. Prerequisite

    You need to install the JDK8 and Docker.

  2. Set up an external OAuth 2.0 server

    There is a sample-authorization-server based on spring-authorization-server.

    The image has registered client information in the external OAuth 2.0 server.

    Its clientId is test. Its secret is test. Its scope is test.

 docker run -p 8177:8177 --name sample-auth-server -d datastrato/sample-authorization-server:0.3.0
  1. Open the JWK URL of the Authorization server in the browser and you can get the JWK.

    jks_response_image

  2. Convert the JWK to PEM. You can use the online tool or other tools.

    pem_convert_result_image

  3. Copy the public key and remove the character \n and you can get the default signing key of Gravitino server.

  4. You can refer to the Configurations and append the configurations to the conf/gravitino.conf.

gravitino.authenticator = oauth
gravitino.authenticator.oauth.serviceAudience = test
gravitino.authenticator.oauth.defaultSignKey = <the default signing key>
gravitino.authenticator.oauth.tokenPath = /oauth2/token
gravitino.authenticator.oauth.serverUri = http://localhost:8177
  1. Open the URL of Gravitino server and login in with clientId test, clientSecret test, and scope test.

    oauth_login_image

  2. You can also use the curl command to access Gravitino.

Get access token

curl --location --request POST 'http://127.0.0.1:8177/oauth2/token?grant_type=client_credentials&client_id=test&client_secret=test&scope=test'

Use the access token to request the Gravitino

curl -v -X GET -H "Accept: application/vnd.gravitino.v1+json" -H "Content-Type: application/json" -H "Authorization: Bearer <access_token>" http://localhost:8090/api/version

HTTPS

Users would better use HTTPS instead of HTTP if users choose OAuth 2.0 as the authenticator.

HTTPS protects the header of the request from smuggling, making it safer.

If users choose to enable HTTPS, Gravitino won't provide the ability of HTTP service.

Both the Gravitino server and Iceberg REST service can configure HTTPS.

Gravitino server's configuration

Configuration itemDescriptionDefault valueRequiredSince version
gravitino.server.webserver.enableHttpsEnables HTTPS.falseNo0.3.0
gravitino.server.webserver.httpsPortThe HTTPS port number of the Jetty web server.8433No0.3.0
gravitino.server.webserver.keyStorePathPath to the key store file.(none)Yes if use HTTPS0.3.0
gravitino.server.webserver.keyStorePasswordPassword to the key store.(none)Yes if use HTTPS0.3.0
gravitino.server.webserver.keyStoreTypeThe type to the key store.JKSNo0.3.0
gravitino.server.webserver.managerPasswordManager password to the key store.(none)Yes if use HTTPS0.3.0
gravitino.server.webserver.tlsProtocolTLS protocol to use. The JVM must support the TLS protocol to use.(none)No0.3.0
gravitino.server.webserver.enableCipherAlgorithmsThe collection of enabled cipher algorithms.``No0.3.0
gravitino.server.webserver.enableClientAuthEnables the authentication of the client.falseNo0.3.0
gravitino.server.webserver.trustStorePathPath to the trust store file.(none)Yes if use HTTPS and the authentication of client0.3.0
gravitino.server.webserver.trustStorePasswordPassword to the trust store.(none)Yes if use HTTPS and the authentication of client0.3.0
gravitino.server.webserver.trustStoreTypeThe type to the trust store.JKSNo0.3.0

Iceberg REST service's configuration

Configuration itemDescriptionDefault valueRequiredSince version
gravitino.auxService.iceberg-rest.enableHttpsEnables HTTPS.falseNo0.3.0
gravitino.auxService.iceberg-rest.httpsPortThe HTTPS port number of the Jetty web server.9433No0.3.0
gravitino.auxService.iceberg-rest.keyStorePathPath to the key store file.(none)Yes if use HTTPS0.3.0
gravitino.auxService.iceberg-rest.keyStorePasswordPassword to the key store.(none)Yes if use HTTPS0.3.0
gravitino.auxService.iceberg-rest.keyStoreTypeThe type to the key store.JKSNo0.3.0
gravitino.auxService.iceberg-rest.managerPasswordManager password to the key store.(none)Yes if use HTTPS0.3.0
gravitino.auxService.iceberg-rest.tlsProtocolTLS protocol to use. The JVM must support the TLS protocol to use.(none)No0.3.0
gravitino.auxService.iceberg-rest.enableCipherAlgorithmsThe collection of enabled cipher algorithms.``No0.3.0
gravitino.auxService.iceberg-rest.enableClientAuthEnables the authentication of the client.falseNo0.3.0
gravitino.auxService.iceberg-rest.trustStorePathPath to the trust store file.(none)Yes if use HTTPS and the authentication of client0.3.0
gravitino.auxService.iceberg-rest.trustStorePasswordPassword to the trust store.(none)Yes if use HTTPS and the authentication of client0.3.0
gravitino.auxService.iceberg-rest.trustStoreTypeThe type to the trust store.JKSNo0.3.0

Refer to the "Additional JSSE Standard Names" section of the Java security guide for the list of protocols related to tlsProtocol. You can find the list of tlsProtocol values for Java 8 in this document.

Refer to the "Additional JSSE Standard Names" section of the Java security guide for the list of protocols related to tlsProtocol. You can find the list of enableCipherAlgorithms values for Java 8 in this document.

Example

You can follow the steps to set up a HTTPS server.

  1. Prerequisite

    You need to install the JDK8, wget, and set the environment JAVA_HOME.

    If you want to use the command curl to request the Gravitino server, you should install openSSL.

  2. Generate the key store

cd $JAVA_HOME
bin/keytool -genkeypair -alias localhost \
-keyalg RSA -keysize 4096 -keypass localhost \
-sigalg SHA256withRSA \
-keystore localhost.jks -storetype JKS -storepass localhost \
-dname "cn=localhost,ou=localhost,o=localhost,l=beijing,st=beijing,c=cn" \
-validity 36500
  1. Generate the certificate
bin/keytool -export -alias localhost -keystore localhost.jks -file  localhost.crt -storepass localhost
  1. Import the certificate
bin/keytool -import -alias localhost -keystore jre/lib/security/cacerts -file localhost.crt -storepass changeit -noprompt
  1. You can refer to the Configurations and append the configuration to the conf/gravitino.conf. Configuration doesn't support resolving environment variables, so you should replace ${JAVA_HOME} with the actual value. Then, You can start the Gravitino server.
gravitino.server.webserver.host = localhost
gravitino.server.webserver.enableHttps = true
gravitino.server.webserver.keyStorePath = ${JAVA_HOME}/localhost.jks
gravitino.server.webserver.keyStorePassword = localhost
gravitino.server.webserver.managerPassword = localhost
  1. Request the Gravitino server

    If you use Java, you can follow the steps

    Copy the code to a file named Main.java

import com.datastrato.gravitino.client.GravitinoClient;
import com.datastrato.gravitino.client.GravitinoVersion;

public class Main {
public static void main(String[] args) {
String uri = "https://localhost:8433";
GravitinoClient client = GravitinoClient.builder(uri).withMetalake("metalake").build();
GravitinoVersion gravitinoVersion = client.getVersion();
System.out.println(gravitinoVersion);
}
}

If you want to use the command curl, you can follow the commands:

openssl x509 -inform der -in $JAVA_HOME/localhost.crt -out certificate.pem
curl -v -X GET --cacert ./certificate.pem -H "Accept: application/vnd.gravitino.v1+json" -H "Content-Type: application/json" https://localhost:8433/api/version

Cross-origin resource filter

Server configuration

Configuration itemDescriptionDefault valueRequiredSince version
gravitino.server.webserver.enableCorsFilterEnable cross-origin resource share filter.falseNo0.4.0
gravitino.server.webserver.allowedOriginsA comma separated list of allowed origins to access the resources. The default value is *, which means all origins.*No0.4.0
gravitino.server.webserver.allowedTimingOriginsA comma separated list of allowed origins to time the resource. The default value is the empty string, which means no origins.``No0.4.0
gravitino.server.webserver.allowedMethodsA comma separated list of allowed HTTP methods used when accessing the resources. The default values are GET, POST, HEAD, and DELETE.GET,POST,HEAD,DELETE,PUTNo0.4.0
gravitino.server.webserver.allowedHeadersA comma separated list of allowed HTTP headers specified when accessing the resources. The default value is X-Requested-With,Content-Type,Accept,Origin. If the value is a single *, it accepts all headers.X-Requested-With,Content-Type,Accept,OriginNo0.4.0
gravitino.server.webserver.preflightMaxAgeInSecsThe number of seconds to cache preflight requests by the client. The default value is 1800 seconds or 30 minutes.1800No0.4.0
gravitino.server.webserver.allowCredentialsA boolean indicating if the resource allows requests with credentials. The default value is true.trueNo0.4.0
gravitino.server.webserver.exposedHeadersA comma separated list of allowed HTTP headers exposed on the client. The default value is the empty list.``No0.4.0
gravitino.server.webserver.chainPreflightIf true chained preflight requests for normal handling (as an OPTION request). Otherwise, the filter responds to the preflight. The default is true.trueNo0.4.0

Iceberg REST service's configuration

Configuration itemDescriptionDefault valueRequiredSince version
gravitino.auxService.iceberg-rest.enableCorsFilterEnable cross-origin resource share filter.falseNo0.4.0
gravitino.auxService.iceberg-rest.allowedOriginsA comma separated list of allowed origins that access the resources. The default value is *, which means all origins.*No0.4.0
gravitino.auxService.iceberg-rest.allowedTimingOriginsA comma separated list of allowed origins that time the resource. The default value is the empty string, which means no origins.``No0.4.0
gravitino.auxService.iceberg-rest.allowedMethodsA comma separated list of allowed HTTP methods used when accessing the resources. The default values are GET, POST, HEAD, and DELETE.GET,POST,HEAD,DELETE,PUTNo0.4.0
gravitino.auxService.iceberg-rest.allowedHeadersA comma separated list of HTTP allowed headers specified when accessing the resources. The default value is X-Requested-With,Content-Type,Accept,Origin. If the value is a single *, it accepts all headers.X-Requested-With,Content-Type,Accept,OriginNo0.4.0
gravitino.auxService.iceberg-rest.preflightMaxAgeInSecsThe number of seconds to cache preflight requests by the client. The default value is 1800 seconds or 30 minutes.1800No0.4.0
gravitino.auxService.iceberg-rest.allowCredentialsA boolean indicating if the resource allows requests with credentials. The default value is true.trueNo0.4.0
gravitino.auxService.iceberg-rest.exposedHeadersA comma separated list of allowed HTTP headers exposed on the client. The default value is the empty list.``No0.4.0
gravitino.auxService.iceberg-rest.chainPreflightIf true chained preflight requests for normal handling (as an OPTION request). Otherwise, the filter responds to the preflight. The default is true.trueNo0.4.0