tessl/maven-io-rest-assured--rest-assured
Java DSL for easy testing of REST services
—
Pending
authentication.mddocs/
Authentication
Comprehensive authentication support including basic, digest, OAuth 1.0/2.0, certificate-based, form authentication, and preemptive authentication schemes for REST API testing.
Capabilities
Basic Authentication
HTTP Basic authentication using username and password credentials.
/**
* Create HTTP basic authentication scheme
* @param userName The username
* @param password The password
* @return Authentication scheme for basic auth
*/
static AuthenticationScheme basic(String userName, String password);
// Via authentication specification
interface AuthenticationSpecification {
/**
* Use HTTP basic authentication for this request
* @param userName The username
* @param password The password
* @return Updated request specification
*/
RequestSpecification basic(String userName, String password);
}Usage Examples:
// Global basic authentication
RestAssured.authentication = basic("admin", "password123");
// Per-request basic authentication
given()
.auth().basic("user", "pass")
.when()
.get("/protected")
.then()
.statusCode(200);
// Preemptive basic authentication (sends credentials without challenge)
given()
.auth().preemptive().basic("user", "pass")
.when()
.get("/protected");Digest Authentication
HTTP Digest authentication for enhanced security over basic authentication.
/**
* Create HTTP digest authentication scheme
* @param userName The username
* @param password The password (should be properly encoded)
* @return Authentication scheme for digest auth
*/
static AuthenticationScheme digest(String userName, String password);
interface AuthenticationSpecification {
/**
* Use HTTP digest authentication for this request
* @param userName The username
* @param password The password
* @return Updated request specification
*/
RequestSpecification digest(String userName, String password);
}Usage Examples:
// Digest authentication
given()
.auth().digest("user", "password")
.when()
.get("/protected")
.then()
.statusCode(200);OAuth 1.0 Authentication
OAuth 1.0 authentication with consumer key, consumer secret, access token, and secret token.
/**
* Create OAuth 1.0 authentication scheme
* @param consumerKey OAuth consumer key
* @param consumerSecret OAuth consumer secret
* @param accessToken OAuth access token
* @param secretToken OAuth secret token
* @return Authentication scheme for OAuth 1.0
*/
static AuthenticationScheme oauth(String consumerKey, String consumerSecret, String accessToken, String secretToken);
/**
* Create OAuth 1.0 authentication scheme with custom signature
* @param consumerKey OAuth consumer key
* @param consumerSecret OAuth consumer secret
* @param accessToken OAuth access token
* @param secretToken OAuth secret token
* @param signature OAuth signature method
* @return Authentication scheme for OAuth 1.0
*/
static AuthenticationScheme oauth(String consumerKey, String consumerSecret, String accessToken, String secretToken, OAuthSignature signature);
interface AuthenticationSpecification {
/**
* Use OAuth 1.0 authentication for this request
* @param consumerKey OAuth consumer key
* @param consumerSecret OAuth consumer secret
* @param accessToken OAuth access token
* @param secretToken OAuth secret token
* @return Updated request specification
*/
RequestSpecification oauth(String consumerKey, String consumerSecret, String accessToken, String secretToken);
/**
* Use OAuth 1.0 authentication with custom signature for this request
* @param consumerKey OAuth consumer key
* @param consumerSecret OAuth consumer secret
* @param accessToken OAuth access token
* @param secretToken OAuth secret token
* @param signature OAuth signature method
* @return Updated request specification
*/
RequestSpecification oauth(String consumerKey, String consumerSecret, String accessToken, String secretToken, OAuthSignature signature);
}Usage Examples:
// OAuth 1.0 authentication
given()
.auth().oauth("consumerKey", "consumerSecret", "accessToken", "tokenSecret")
.when()
.get("/api/protected")
.then()
.statusCode(200);
// OAuth 1.0 with custom signature method
given()
.auth().oauth("consumerKey", "consumerSecret", "accessToken", "tokenSecret", OAuthSignature.HMAC_SHA256)
.when()
.post("/api/data");OAuth 2.0 Authentication
OAuth 2.0 authentication using Bearer tokens.
/**
* Create OAuth 2.0 authentication scheme
* @param accessToken OAuth 2.0 access token
* @return Authentication scheme for OAuth 2.0
*/
static AuthenticationScheme oauth2(String accessToken);
/**
* Create OAuth 2.0 authentication scheme with custom signature
* @param accessToken OAuth 2.0 access token
* @param signature OAuth signature method
* @return Authentication scheme for OAuth 2.0
*/
static AuthenticationScheme oauth2(String accessToken, OAuthSignature signature);
interface AuthenticationSpecification {
/**
* Use OAuth 2.0 authentication for this request
* @param accessToken OAuth 2.0 access token
* @return Updated request specification
*/
RequestSpecification oauth2(String accessToken);
/**
* Use OAuth 2.0 authentication with custom signature for this request
* @param accessToken OAuth 2.0 access token
* @param signature OAuth signature method
* @return Updated request specification
*/
RequestSpecification oauth2(String accessToken, OAuthSignature signature);
}Usage Examples:
// OAuth 2.0 Bearer token authentication
given()
.auth().oauth2("eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...")
.when()
.get("/api/user")
.then()
.statusCode(200);
// OAuth 2.0 with custom signature
given()
.auth().oauth2("accessToken", OAuthSignature.HMAC_SHA1)
.when()
.get("/api/protected");Certificate Authentication
Certificate-based authentication using SSL/TLS client certificates.
/**
* Create certificate authentication scheme with default SSL settings
* @param certURL Path to JKS keystore containing the certificate
* @param password Password for the keystore
* @return Authentication scheme for certificate auth
*/
static AuthenticationScheme certificate(String certURL, String password);
/**
* Create certificate authentication scheme with custom settings
* @param certURL Path to JKS keystore containing the certificate
* @param password Password for the keystore
* @param certificateAuthSettings Advanced certificate authentication settings
* @return Authentication scheme for certificate auth
*/
static AuthenticationScheme certificate(String certURL, String password, CertificateAuthSettings certificateAuthSettings);
/**
* Create certificate authentication scheme with separate trust and key stores
* @param trustStorePath Path to JKS trust store
* @param trustStorePassword Password for the trust store
* @param keyStorePath Path to JKS keystore
* @param keyStorePassword Password for the keystore
* @param certificateAuthSettings Advanced certificate authentication settings
* @return Authentication scheme for certificate auth
*/
static AuthenticationScheme certificate(String trustStorePath, String trustStorePassword, String keyStorePath, String keyStorePassword, CertificateAuthSettings certificateAuthSettings);
interface AuthenticationSpecification {
/**
* Use certificate authentication for this request
* @param certURL Path to certificate
* @param password Certificate password
* @return Updated request specification
*/
RequestSpecification certificate(String certURL, String password);
/**
* Use certificate authentication with custom settings for this request
* @param certURL Path to certificate
* @param password Certificate password
* @param certificateAuthSettings Advanced certificate settings
* @return Updated request specification
*/
RequestSpecification certificate(String certURL, String password, CertificateAuthSettings certificateAuthSettings);
}Usage Examples:
// Basic certificate authentication
given()
.auth().certificate("/path/to/client-cert.jks", "keystorePassword")
.when()
.get("/secure-api")
.then()
.statusCode(200);
// Certificate authentication with custom settings
CertificateAuthSettings settings = CertificateAuthSettings.certAuthSettings()
.trustStore("/path/to/truststore.jks")
.keyStoreType("PKCS12")
.port(8443);
given()
.auth().certificate("/path/to/client.p12", "password", settings)
.when()
.get("/mutual-tls-endpoint");Form Authentication
Form-based authentication that automatically handles login forms.
/**
* Create form authentication scheme with auto-detection
* @param userName The username
* @param password The password
* @return Authentication scheme for form auth
*/
static AuthenticationScheme form(String userName, String password);
/**
* Create form authentication scheme with custom configuration
* @param userName The username
* @param password The password
* @param config Form authentication configuration
* @return Authentication scheme for form auth
*/
static AuthenticationScheme form(String userName, String password, FormAuthConfig config);
interface AuthenticationSpecification {
/**
* Use form authentication for this request
* @param userName The username
* @param password The password
* @return Updated request specification
*/
RequestSpecification form(String userName, String password);
/**
* Use form authentication with custom configuration for this request
* @param userName The username
* @param password The password
* @param config Form authentication configuration
* @return Updated request specification
*/
RequestSpecification form(String userName, String password, FormAuthConfig config);
}Usage Examples:
// Basic form authentication (auto-detects form fields)
given()
.auth().form("user", "password")
.when()
.get("/dashboard")
.then()
.statusCode(200);
// Form authentication with custom configuration
FormAuthConfig config = FormAuthConfig.formAuthConfig()
.withFormAction("/custom-login")
.withUsernameField("email")
.withPasswordField("pwd")
.withAutoDetection(false);
given()
.auth().form("user@example.com", "password", config)
.when()
.get("/protected-page");NTLM Authentication
Windows NTLM authentication for corporate environments.
/**
* Create NTLM authentication scheme
* @param userName The username
* @param password The password
* @param workstation The NTLM workstation
* @param domain The NTLM domain
* @return Authentication scheme for NTLM auth
*/
static AuthenticationScheme ntlm(String userName, String password, String workstation, String domain);
interface AuthenticationSpecification {
/**
* Use NTLM authentication for this request
* @param userName The username
* @param password The password
* @param workstation The workstation name
* @param domain The domain name
* @return Updated request specification
*/
RequestSpecification ntlm(String userName, String password, String workstation, String domain);
}Usage Examples:
// NTLM authentication
given()
.auth().ntlm("domain\\user", "password", "WORKSTATION", "DOMAIN")
.when()
.get("/corporate-api")
.then()
.statusCode(200);Preemptive Authentication
Preemptive authentication that sends credentials without waiting for authentication challenge.
/**
* Create preemptive authentication provider
* @return Preemptive authentication provider
*/
static PreemptiveAuthProvider preemptive();
interface AuthenticationSpecification {
/**
* Enable preemptive authentication
* @return Preemptive authentication specification
*/
PreemptiveAuthSpec preemptive();
}
interface PreemptiveAuthSpec {
/**
* Use preemptive basic authentication
* @param userName The username
* @param password The password
* @return Updated request specification
*/
RequestSpecification basic(String userName, String password);
}Usage Examples:
// Preemptive basic authentication (sends credentials immediately)
given()
.auth().preemptive().basic("user", "password")
.when()
.get("/api")
.then()
.statusCode(200);No Authentication
Disable authentication for specific requests when global authentication is configured.
interface AuthenticationSpecification {
/**
* Disable authentication for this request
* @return Updated request specification
*/
RequestSpecification none();
}Usage Examples:
// Disable global authentication for this request
RestAssured.authentication = basic("user", "password");
given()
.auth().none() // This request won't use the global auth
.when()
.get("/public-endpoint")
.then()
.statusCode(200);Types
// Base authentication scheme interface
interface AuthenticationScheme {
// Implementation details handled internally
}
// Authentication specification interface
interface AuthenticationSpecification {
RequestSpecification basic(String userName, String password);
RequestSpecification digest(String userName, String password);
RequestSpecification oauth(String consumerKey, String consumerSecret, String accessToken, String secretToken);
RequestSpecification oauth(String consumerKey, String consumerSecret, String accessToken, String secretToken, OAuthSignature signature);
RequestSpecification oauth2(String accessToken);
RequestSpecification oauth2(String accessToken, OAuthSignature signature);
RequestSpecification certificate(String certURL, String password);
RequestSpecification certificate(String certURL, String password, CertificateAuthSettings certificateAuthSettings);
RequestSpecification form(String userName, String password);
RequestSpecification form(String userName, String password, FormAuthConfig config);
RequestSpecification ntlm(String userName, String password, String workstation, String domain);
PreemptiveAuthSpec preemptive();
RequestSpecification none();
}
// Preemptive authentication specification
interface PreemptiveAuthSpec {
RequestSpecification basic(String userName, String password);
}
// Preemptive authentication provider
class PreemptiveAuthProvider {
PreemptiveAuthSpec basic(String userName, String password);
}
// OAuth signature methods
enum OAuthSignature {
HMAC_SHA1, HMAC_SHA256, RSA_SHA1, PLAINTEXT;
}
// Form authentication configuration
class FormAuthConfig {
static FormAuthConfig formAuthConfig();
FormAuthConfig withFormAction(String formAction);
FormAuthConfig withUsernameField(String usernameFieldName);
FormAuthConfig withPasswordField(String passwordFieldName);
FormAuthConfig withAutoDetection(boolean shouldAutoDetect);
FormAuthConfig withAdditionalFields(Map<String, String> additionalFields);
FormAuthConfig withCsrfFieldName(String csrfFieldName);
FormAuthConfig withCsrfTokenPath(String csrfTokenPath);
FormAuthConfig withLoggingEnabled(boolean isLoggingEnabled);
}
// Certificate authentication settings
class CertificateAuthSettings {
static CertificateAuthSettings certAuthSettings();
CertificateAuthSettings keyStore(String pathToKeyStore);
CertificateAuthSettings keyStore(KeyStore keyStore);
CertificateAuthSettings keyStoreType(String keyStoreType);
CertificateAuthSettings keyStorePassword(String password);
CertificateAuthSettings trustStore(String pathToTrustStore);
CertificateAuthSettings trustStore(KeyStore trustStore);
CertificateAuthSettings trustStoreType(String trustStoreType);
CertificateAuthSettings trustStorePassword(String password);
CertificateAuthSettings x509HostnameVerifier(X509HostnameVerifier hostnameVerifier);
CertificateAuthSettings sslSocketFactory(SSLSocketFactory sslSocketFactory);
CertificateAuthSettings port(int port);
}Install with Tessl CLI
npx tessl i tessl/maven-io-rest-assured--rest-assured