0
# Authentication and Security
1

2
Authentication callbacks and security mechanisms for various authentication methods including OpenID Connect, WebAuthn, and pluggable authentication.
3

4
## Capabilities
5

6
### Callback Interfaces
7

8
Core callback interfaces for authentication data exchange.
9

10
```java { .api }
11
package com.mysql.cj.callback;
12

13
public interface MysqlCallback {
14
    // Marker interface for all MySQL callbacks
15
}
16

17
public interface MysqlCallbackHandler {
18
    // Handle callback
19
    void handle(MysqlCallback callback);
20
}
21
```
22

23
### OpenID Connect Authentication
24

25
Callback and handler for OpenID Connect authentication.
26

27
```java { .api }
28
package com.mysql.cj.callback;
29

30
public class OpenidConnectAuthenticationCallback implements MysqlCallback {
31
    public OpenidConnectAuthenticationCallback();
32
    
33
    // Set Identity Token
34
    public void setIdToken(String idToken);
35
    
36
    // Get Identity Token
37
    public String getIdToken();
38
}
39

40
public class OpenidConnectIdTokenFromFileCallbackHandler implements MysqlCallbackHandler {
41
    // Constructor takes path to file containing ID token
42
    public OpenidConnectIdTokenFromFileCallbackHandler(String idTokenFile);
43
    
44
    // Handle callback by reading token from file
45
    public void handle(MysqlCallback callback);
46
}
47
```
48

49
Usage:
50

51
```java
52
// Configure OpenID Connect authentication
53
Properties props = new Properties();
54
props.setProperty("user", "myuser");
55
props.setProperty("defaultAuthenticationPlugin", "authentication_openid_connect_client");
56

57
// Set callback handler to read token from file
58
String idTokenFile = "/path/to/id_token.txt";
59
props.setProperty("authenticationOpenidConnectCallbackHandler",
60
    "com.mysql.cj.callback.OpenidConnectIdTokenFromFileCallbackHandler");
61
props.setProperty("authenticationOpenidConnectClientIdTokenFile", idTokenFile);
62

63
Connection conn = DriverManager.getConnection("jdbc:mysql://localhost:3306/mydb", props);
64

65
// Or use custom callback handler
66
MysqlCallbackHandler handler = new MysqlCallbackHandler() {
67
    public void handle(MysqlCallback callback) {
68
        if (callback instanceof OpenidConnectAuthenticationCallback) {
69
            OpenidConnectAuthenticationCallback oidcCallback =
70
                (OpenidConnectAuthenticationCallback) callback;
71
            // Get token from your identity provider
72
            String token = getTokenFromIdentityProvider();
73
            oidcCallback.setIdToken(token);
74
        }
75
    }
76
};
77
```
78

79
### WebAuthn Authentication
80

81
Callback for WebAuthn (FIDO2) authentication.
82

83
```java { .api }
84
package com.mysql.cj.callback;
85

86
public class WebAuthnAuthenticationCallback implements MysqlCallback {
87
    public WebAuthnAuthenticationCallback();
88
    
89
    // Set authenticator data
90
    public void setAuthenticatorData(byte[] authenticatorData);
91
    public byte[] getAuthenticatorData();
92
    
93
    // Set signature
94
    public void setSignature(byte[] signature);
95
    public byte[] getSignature();
96
    
97
    // Set relying party ID
98
    public void setRelyingPartyId(String relyingPartyId);
99
    public String getRelyingPartyId();
100
    
101
    // Set challenge
102
    public void setChallenge(byte[] challenge);
103
    public byte[] getChallenge();
104
}
105
```
106

107
Usage:
108

109
```java
110
// Implement WebAuthn callback handler
111
MysqlCallbackHandler webAuthnHandler = new MysqlCallbackHandler() {
112
    public void handle(MysqlCallback callback) {
113
        if (callback instanceof WebAuthnAuthenticationCallback) {
114
            WebAuthnAuthenticationCallback waCallback =
115
                (WebAuthnAuthenticationCallback) callback;
116
            
117
            // Get challenge from callback
118
            byte[] challenge = waCallback.getChallenge();
119
            String rpId = waCallback.getRelyingPartyId();
120
            
121
            // Interact with FIDO2 authenticator
122
            byte[] authenticatorData = getAuthenticatorData(challenge, rpId);
123
            byte[] signature = getSignature(challenge, rpId);
124
            
125
            // Set response
126
            waCallback.setAuthenticatorData(authenticatorData);
127
            waCallback.setSignature(signature);
128
        }
129
    }
130
};
131

132
Properties props = new Properties();
133
props.setProperty("defaultAuthenticationPlugin", "authentication_webauthn_client");
134
props.setProperty("authenticationWebAuthnCallbackHandler",
135
    "com.mycompany.MyWebAuthnCallbackHandler");
136

137
Connection conn = DriverManager.getConnection("jdbc:mysql://localhost:3306/mydb", props);
138
```
139

140
### Username Callback
141

142
Callback for username exchange.
143

144
```java { .api }
145
package com.mysql.cj.callback;
146

147
public class UsernameCallback implements MysqlCallback {
148
    // Constructor requires prompt message
149
    public UsernameCallback(String promptMessage);
150

151
    // Get username (no setter - username is provided via subclass or stored during construction)
152
    public String getUsername();
153
}
154
```
155

156
### Authentication Plugin Interface
157

158
Interface for implementing custom authentication plugins.
159

160
```java { .api }
161
package com.mysql.cj.protocol;
162

163
public interface AuthenticationPlugin<M extends Message> {
164
    // Initialize plugin
165
    void init(Protocol<M> prot, MysqlCallbackHandler cbh);
166
    
167
    // Reset plugin state
168
    void reset();
169
    
170
    // Destroy plugin
171
    void destroy();
172
    
173
    // Get protocol plugin name
174
    String getProtocolPluginName();
175
    
176
    // Check if plugin requires confidentiality (SSL)
177
    boolean requiresConfidentiality();
178
    
179
    // Check if plugin is reusable
180
    boolean isReusable();
181
    
182
    // Set authentication parameters
183
    void setAuthenticationParameters(String user, String password);
184
    
185
    // Perform next authentication step
186
    boolean nextAuthenticationStep(M fromServer, List<M> toServer);
187
}
188
```
189

190
### Authentication Provider
191

192
Interface for authentication providers.
193

194
```java { .api }
195
package com.mysql.cj.protocol;
196

197
public interface AuthenticationProvider<M extends Message> {
198
    // Initialize provider
199
    void init(Protocol<M> prot, PropertySet propertySet, ExceptionInterceptor exceptionInterceptor);
200
    
201
    // Connect with authentication
202
    void connect(String userName, String password, String database);
203
    
204
    // Change user (re-authenticate)
205
    void changeUser(String userName, String password, String database);
206
}
207
```
208

209
Usage:
210

211
```java
212
// Configure authentication plugins
213
String url = "jdbc:mysql://localhost:3306/mydb" +
214
             "?authenticationPlugins=com.mycompany.MyAuthPlugin" +
215
             "&defaultAuthenticationPlugin=com.mycompany.MyAuthPlugin";
216

217
// Disable specific authentication plugins
218
String url2 = "jdbc:mysql://localhost:3306/mydb" +
219
              "?disabledAuthenticationPlugins=mysql_native_password";
220

221
// Allow public key retrieval for caching_sha2_password
222
String url3 = "jdbc:mysql://localhost:3306/mydb" +
223
              "?allowPublicKeyRetrieval=true";
224

225
Connection conn = DriverManager.getConnection(url, "user", "pass");
226
```
227

228
### Built-in Authentication Plugins
229

230
MySQL Connector/J includes several built-in authentication plugins:
231

232
- **mysql_native_password**: Traditional MySQL authentication
233
- **caching_sha2_password**: Default in MySQL 8.0+
234
- **sha256_password**: SHA-256 password authentication
235
- **authentication_ldap_sasl_client**: LDAP SASL authentication
236
- **authentication_kerberos_client**: Kerberos authentication
237
- **authentication_openid_connect_client**: OpenID Connect authentication
238
- **authentication_webauthn_client**: WebAuthn (FIDO2) authentication
239
- **authentication_oci_client**: Oracle Cloud Infrastructure IAM authentication
240

241
Configuration examples:
242

243
```java
244
// Caching SHA-2 password (default in MySQL 8.0+)
245
String url = "jdbc:mysql://localhost:3306/mydb?allowPublicKeyRetrieval=true";
246

247
// LDAP SASL authentication
248
Properties props = new Properties();
249
props.setProperty("user", "ldapuser");
250
props.setProperty("defaultAuthenticationPlugin", "authentication_ldap_sasl_client");
251
props.setProperty("authenticationLdapSaslClientServerType", "openldap");
252

253
// Kerberos authentication
254
props.setProperty("defaultAuthenticationPlugin", "authentication_kerberos_client");
255

256
// OCI IAM authentication
257
props.setProperty("defaultAuthenticationPlugin", "authentication_oci_client");
258
props.setProperty("ociConfigFile", "/path/to/oci_config");
259

260
Connection conn = DriverManager.getConnection(url, props);
261
```
262