1 | // License: GPL. For details, see LICENSE file.
|
---|
2 | package org.openstreetmap.josm.io.auth;
|
---|
3 |
|
---|
4 | import java.awt.Component;
|
---|
5 | import java.net.Authenticator.RequestorType;
|
---|
6 | import java.net.PasswordAuthentication;
|
---|
7 |
|
---|
8 | import org.openstreetmap.josm.data.oauth.IOAuthToken;
|
---|
9 |
|
---|
10 | import jakarta.annotation.Nullable;
|
---|
11 |
|
---|
12 | /**
|
---|
13 | * A CredentialsAgent manages two credentials:
|
---|
14 | * <ul>
|
---|
15 | * <li>the credential for {@link RequestorType#SERVER} which is equal to the OSM API credentials
|
---|
16 | * in JOSM</li>
|
---|
17 | * <li>the credential for {@link RequestorType#PROXY} which is equal to the credentials for an
|
---|
18 | * optional HTTP proxy server a user may use</li>
|
---|
19 | * </ul>
|
---|
20 | *
|
---|
21 | * In addition, it manages an OAuth Access Token for accessing the OSM server.
|
---|
22 | */
|
---|
23 | public interface CredentialsAgent {
|
---|
24 |
|
---|
25 | /**
|
---|
26 | * Looks up the credentials for a given type.
|
---|
27 | *
|
---|
28 | * @param requestorType the type of service. {@link RequestorType#SERVER} for the OSM API server, {@link RequestorType#PROXY}
|
---|
29 | * for a proxy server
|
---|
30 | * @param host the hostname for these credentials
|
---|
31 | * @return the credentials
|
---|
32 | * @throws CredentialsAgentException if a problem occurs in a implementation of this interface
|
---|
33 | */
|
---|
34 | PasswordAuthentication lookup(RequestorType requestorType, String host) throws CredentialsAgentException;
|
---|
35 |
|
---|
36 | /**
|
---|
37 | * Saves the credentials in <code>credentials</code> for the given service type.
|
---|
38 | *
|
---|
39 | * @param requestorType the type of service. {@link RequestorType#SERVER} for the OSM API server, {@link RequestorType#PROXY}
|
---|
40 | * for a proxy server
|
---|
41 | * @param host the hostname for these credentials
|
---|
42 | * @param credentials the credentials
|
---|
43 | * @throws CredentialsAgentException if a problem occurs in a implementation of this interface
|
---|
44 | */
|
---|
45 | void store(RequestorType requestorType, String host, PasswordAuthentication credentials) throws CredentialsAgentException;
|
---|
46 |
|
---|
47 | /**
|
---|
48 | * Returns the credentials needed to to access host.
|
---|
49 | * @param requestorType the type of service. {@link RequestorType#SERVER} for the OSM API server, {@link RequestorType#PROXY}
|
---|
50 | * for a proxy server
|
---|
51 | * @param host the hostname for these credentials
|
---|
52 | * @param noSuccessWithLastResponse true, if the last request with the supplied credentials failed; false otherwise.
|
---|
53 | * If true, implementations of this interface are advised to prompt the user for new credentials.
|
---|
54 | * @return the credentials
|
---|
55 | * @throws CredentialsAgentException if a problem occurs in a implementation of this interface
|
---|
56 | */
|
---|
57 | CredentialsAgentResponse getCredentials(RequestorType requestorType, String host, boolean noSuccessWithLastResponse)
|
---|
58 | throws CredentialsAgentException;
|
---|
59 |
|
---|
60 | /**
|
---|
61 | * Lookup the current OAuth Access Token to access the OSM server. Replies null, if no
|
---|
62 | * Access Token is currently managed by this CredentialAgent.
|
---|
63 | *
|
---|
64 | * @return the current OAuth Access Token to access the OSM server.
|
---|
65 | * @throws CredentialsAgentException if something goes wrong
|
---|
66 | * @deprecated since 18991 -- OAuth 1.0 is being removed from the OSM API
|
---|
67 | */
|
---|
68 | @Deprecated
|
---|
69 | default IOAuthToken lookupOAuthAccessToken() throws CredentialsAgentException {
|
---|
70 | throw new CredentialsAgentException("Call to deprecated method");
|
---|
71 | }
|
---|
72 |
|
---|
73 | /**
|
---|
74 | * Lookup the current OAuth Access Token to access the specified server. Replies null, if no
|
---|
75 | * Access Token is currently managed by this CredentialAgent.
|
---|
76 | *
|
---|
77 | * @param host The host to get OAuth credentials for
|
---|
78 | * @return the current OAuth Access Token to access the specified server.
|
---|
79 | * @throws CredentialsAgentException if something goes wrong
|
---|
80 | * @since 18650
|
---|
81 | */
|
---|
82 | @Nullable
|
---|
83 | IOAuthToken lookupOAuthAccessToken(String host) throws CredentialsAgentException;
|
---|
84 |
|
---|
85 | /**
|
---|
86 | * Stores the OAuth Access Token <code>accessToken</code>.
|
---|
87 | *
|
---|
88 | * @param accessToken the access Token. null, to remove the Access Token.
|
---|
89 | * @throws CredentialsAgentException if something goes wrong
|
---|
90 | * @deprecated since 18991 -- OAuth 1.0 is being removed from the OSM API
|
---|
91 | */
|
---|
92 | @Deprecated
|
---|
93 | default void storeOAuthAccessToken(IOAuthToken accessToken) throws CredentialsAgentException {
|
---|
94 | throw new CredentialsAgentException("Call to deprecated method");
|
---|
95 | }
|
---|
96 |
|
---|
97 | /**
|
---|
98 | * Stores the OAuth Access Token <code>accessToken</code>.
|
---|
99 | *
|
---|
100 | * @param host The host the access token is for
|
---|
101 | * @param accessToken the access Token. null, to remove the Access Token. This will remove all IOAuthTokens <i>not</i> managed by
|
---|
102 | * {@link #storeOAuthAccessToken(IOAuthToken)}.
|
---|
103 | * @throws CredentialsAgentException if something goes wrong
|
---|
104 | * @since 18650
|
---|
105 | */
|
---|
106 | void storeOAuthAccessToken(String host, IOAuthToken accessToken) throws CredentialsAgentException;
|
---|
107 |
|
---|
108 | /**
|
---|
109 | * Purges the internal credentials cache for the given requestor type.
|
---|
110 | * @param requestorType the type of service.
|
---|
111 | * {@link RequestorType#SERVER} for the OSM API server, {@link RequestorType#PROXY} for a proxy server
|
---|
112 | * @since 12992
|
---|
113 | */
|
---|
114 | void purgeCredentialsCache(RequestorType requestorType);
|
---|
115 |
|
---|
116 | /**
|
---|
117 | * Provide a Panel that is shown below the API password / username fields
|
---|
118 | * in the JOSM Preferences. (E.g. a warning that password is saved unencrypted.)
|
---|
119 | * @return Panel
|
---|
120 | */
|
---|
121 | Component getPreferencesDecorationPanel();
|
---|
122 | }
|
---|