The support the following methods of authentication.
Authenticating user must be a valid user of the deployed instance of the .
API access tokens can be acquired and applied to your requests to obscure sensitive Personally Identifiable Information (PII) and are compliant with common privacy and security standards. These tokens last for a preconfigured time period and can be renewed as needed.
Tip: API access tokens are the preferred method of authentication.
NOTE: This feature may need to be enabled in your instance of the . For more information, see Enable API Access Tokens.
Tip: API access tokens work seamlessly with platform-native SAML and LDAP SSO authentication. They do not work with the reverse proxy method of SSO authentication. Details are below.
For more information on this process, see Manage API Access Tokens.
As request parameters, you can submit username/password under Basic Auth to any REST API endpoint.
NOTE: You must submit authentication credentials with each request to the platform.
NOTE: The user must have permissions to execute the endpoint action.
This example submits authentication requirements over HTTP, including the username and password (
$ curl -u email@example.com:me_pwd \ -b ~/cookies.txt -c ~/cookies.txt \ http://<platform_host>:<platform_port_number>/v4/<endpoint>
|Required username and password.|
|Required paths and filenames for storage of send and receive HTTP cookies.|
Fully qualified name of the host of the
Port number through which to access the . Default is
You can use the APIs in SSO environments. Below, you can review the best method of authenticating to the APIs based on your SSO environment:
|SSO Type||API Auth|
|Platform-native SAML||API access tokens work seamlessly. Basic auth does not work.|
|Platform-native LDAP-AD||API access tokens work seamlessly. Basic auth does not work.|
|Reverse proxy SAML||Use basic auth described below. Additional configuration may be required.|
|Reverse proxy LDAP-AD||Use basic auth described below. Additional configuration may be required.|
In a single sign-on environment, you can use basic authentication to interact with the APIs.
NOTE: Enabling SSO integration with the requires additional configuration. See Configure SSO for AD-LDAP.
However, some changes are required:
$ curl -u myUser@example.com:foobar -x http://<platform_host>:<platform_port_number> \ -b ~/cookies.txt -c ~/cookies.txt \ http://<platform_host>:<platform_port_number>/v4/<endpoint>
NOTE: For the protocol identifier, you can also use
|LDAP principal and password associated with that username.|
For more information, see Configure SSO for AD-LDAP.
In a Kerberos environment, credentials must be submitted with each request using the SPNEGO Auth method.
Credentials are authenticated by the KDC for each request.
NOTE: SPNEGO must be enabled and configured for your REST client or programming library.
Example 1 - Embedded in Java:
SPNEGO requires a custom client. The following SPNEGO client enables submission of URL-based authentication parameters from within Java: http://docs.oracle.com/javase/6/docs/technotes/guides/security/jgss/lab/part5.html
Example 2 - Using cURL:
To use cURL:
Verify that your version of cURL supports GSS:
$ curl -V curl 7.51.0 (x86_64-apple-darwin16.0) libcurl/7.51.0 SecureTransport zlib/1.2.8 Protocols: dict file ftp ftps gopher http https imap imaps ldap ldaps pop3 pop3s rtsp smb smbs smtp smtps telnet tftp Features: AsynchDNS IPv6 Largefile GSS-API Kerberos SPNEGO NTLM NTLM_WB SSL libz UnixSockets
SPNEGOare in the output.
kinit and authenticate using the Hadoop principal:
$ kinit Please enter the password for [hadoop.user.principal]@localhost: $
$ curl --negotiate -u anything \ -b ~/cookies.txt -c ~/cookies.txt \ http://<platform_host>:<platform_port_number>/v4/<endpoint>
|Enables SPNEGO use in cURL. This option requires a library built with GSS-API or SSPI support. If this option is used several times, only the first one is used. Use |
|Required username. However, this username is ignored. Instead, the principal used in |
For more information:
Since each request requires credentials, logging out is not required.