|
1 | 1 | # EdgeGrid Client for Java |
2 | 2 |
|
3 | | -This library implements [EdgeGrid authentication](https://techdocs.akamai.com/developer/docs/authenticate-with-edgegrid) for Java. |
| 3 | +This library implements an Authentication handler for the [Akamai EdgeGrid Authentication](https://techdocs.akamai.com/developer/docs/authenticate-with-edgegrid) scheme in Java. |
4 | 4 |
|
5 | | -Before you begin, you need to [Create authentication credentials](https://techdocs.akamai.com/developer/docs/set-up-authentication-credentials). |
| 5 | +## Install |
6 | 6 |
|
7 | | -## Install required software |
8 | | - |
9 | | -In order to use EdgeGrid Client for Java, you need [Java version 11+](https://www.java.com/en/download/help/download_options.xml). |
| 7 | +To use AkamaiOPEN EdgeGrid for Java, you need Java version 11+. |
10 | 8 |
|
11 | 9 | [](https://maven-badges.herokuapp.com/maven-central/com.akamai.edgegrid/edgegrid-signer-parent) |
12 | 10 | [](https://www.javadoc.io/doc/com.akamai.edgegrid) |
13 | 11 |
|
14 | | -## Make an API call |
15 | | -You'll need the values for the tokens from your [.edgerc](https://techdocs.akamai.com/developer/docs/set-up-authentication-credentials#add-credential-to-edgerc-file) file. |
| 12 | +## Modules |
16 | 13 |
|
17 | | -``` |
18 | | -ClientCredential credential = ClientCredential.builder() |
19 | | - .accessToken("akaa-xxxxxxxxxxxxxxxx-xxxxxxxxxxxxxxxx") |
20 | | - .clientToken("akaa-xxxxxxxxxxxxxxxx-xxxxxxxxxxxxxxxx") |
21 | | - .clientSecret("SOMESECRET") |
22 | | - .host("akaa-baseurl-xxxxxxxxxxx-xxxxxxxxxxxxx.luna.akamaiapis.net") |
23 | | - .build(); |
24 | | -``` |
| 14 | +This project contains core implementation modules and binding modules to specific HTTP client libraries. |
25 | 15 |
|
26 | | -Example API call: |
27 | | -``` |
28 | | -Request request = Request.builder() |
29 | | - .method("POST") |
30 | | - .uri("https://akaa-baseurl-xxxxxxxxxxx-xxxxxxxxxxxxx.luna.akamaiapis.net/diagnostic-tools/v2/ghost-locations/available") |
31 | | - .body("{ \"field\": \"field value\" }".getBytes()) |
32 | | - .header("X-Some-Signed-Header", "header value") |
33 | | - .header("X-Some-Other-Signed-Header", "header value 2") |
34 | | - .build(); |
35 | | -``` |
| 16 | +### Core |
36 | 17 |
|
37 | | -This is an example of an API call to [List available edge server locations](https://techdocs.akamai.com/diagnostic-tools/reference/ghost-locationsavailable). Change the `uri` element to reference an endpoint in any of the [Akamai APIs](https://developer.akamai.com/api). |
| 18 | +| Module | Description | |
| 19 | +| ---------- | ------------ | |
| 20 | +| [edgegrid-signer-core](edgegrid-signer-core) | The core signing implementation and base classes used by an individual library. | |
| 21 | +| [edgegrid-reader](edgegrid-reader) | A configuration file reader that reads credentials from an `.edgerc` file. This file is an INI file with credential sections and properties. | |
38 | 22 |
|
39 | | -## Modules |
| 23 | +See the [Authentication](#authentication) section for details on using the classes from these modules. |
| 24 | + |
| 25 | +### Bindings |
| 26 | + |
| 27 | +| Module | Description | |
| 28 | +| ---------- | ------------ | |
| 29 | +| [edgegrid-signer-apache-http-client](edgegrid-signer-apache-http-client) | A binding for [Apache HTTP Client before version 5.0.0](https://hc.apache.org/httpcomponents-client-4.5.x/). | |
| 30 | +| [edgegrid-signer-apache-http-client5](edgegrid-signer-apache-http-client5) | A binding for [Apache HTTP Client version 5.x](https://hc.apache.org/httpcomponents-client-5.4.x/). | |
| 31 | +| [edgegrid-signer-async-http-client](edgegrid-signer-async-http-client) | A binding for [Async HTTP Client](https://github.com/AsyncHttpClient/async-http-client). | |
| 32 | +| [edgegrid-signer-google-http-client](edgegrid-signer-google-http-client) | A binding for [Google HTTP Client](https://github.com/google/google-http-java-client). | |
| 33 | +| [edgegrid-signer-rest-assured](edgegrid-signer-rest-assured) | A binding for [REST-assured](https://github.com/rest-assured/rest-assured). | |
| 34 | + |
| 35 | + |
| 36 | +> __Note__: Several similar libraries for signing requests exist for popular |
| 37 | +programming languages, and you can find them at [https://github.com/akamai?q=edgegrid](https://github.com/akamai?q=edgegrid). |
40 | 38 |
|
41 | | -This project contains a core implementation module and five bindings to specific HTTP client libraries. |
| 39 | +## Authentication |
42 | 40 |
|
43 | | -* [edgegrid-signer-core](edgegrid-signer-core) is the core signing implementation and base classes used by the individual library implementations. |
44 | | -* [edgerc-reader](edgerc-reader) is a configuration file reader that supports `.edgerc` files. These files are basically INI files with certain sections and properties. |
45 | | -* [edgegrid-signer-apache-http-client](edgegrid-signer-apache-http-client) is a binding for [Apache HTTP Client][2]. |
46 | | -* [edgegrid-signer-google-http-client](edgegrid-signer-google-http-client) is a binding for [Google HTTP Client Library for Java][3]. |
47 | | -* [edgegrid-signer-rest-assured](edgegrid-signer-rest-assured) is a binding for [REST-assured][4]. |
48 | | -* [edgegrid-signer-async-http-client](edgegrid-signer-async-http-client) is a binding for [Async HTTP Client][13]. |
| 41 | +You can get the authentication credentials through an API client. Requests to the API are marked with a timestamp and a signature and are executed immediately. |
49 | 42 |
|
| 43 | +1. [Create authentication credentials](https://techdocs.akamai.com/developer/docs/set-up-authentication-credentials). |
50 | 44 |
|
51 | | -> Note: A number of similar libraries for signing requests exist for popular |
52 | | -programming languages, and you can find them at [https://github.com/akamai?q=edgegrid](https://github.com/akamai?q=edgegrid) |
| 45 | +2. Place your credentials in an EdgeGrid resource file `~/.edgerc`, in the `[default]` section. |
53 | 46 |
|
| 47 | + ``` |
| 48 | + [default] |
| 49 | + client_secret = C113nt53KR3TN6N90yVuAgICxIRwsObLi0E67/N8eRN= |
| 50 | + host = akab-h05tnam3wl42son7nktnlnnx-kbob3i3v.luna.akamaiapis.net |
| 51 | + access_token = akab-acc35t0k3nodujqunph3w7hzp7-gtm6ij |
| 52 | + client_token = akab-c113ntt0k3n4qtari252bfxxbsl-yvsdj |
| 53 | + ``` |
54 | 54 |
|
55 | | -[1]: https://techdocs.akamai.com/developer/docs/authenticate-with-edgegrid |
56 | | -[2]: https://hc.apache.org/ |
57 | | -[3]: https://github.com/google/google-http-java-client |
58 | | -[4]: https://github.com/rest-assured/rest-assured |
59 | | -[5]: https://github.com/akamai-open/edgegrid-curl |
60 | | -[6]: https://github.com/akamai-open/AkamaiOPEN-edgegrid-python |
61 | | -[7]: https://github.com/akamai-open/AkamaiOPEN-edgegrid-ruby |
62 | | -[8]: https://github.com/akamai-open/AkamaiOPEN-edgegrid-perl |
63 | | -[9]: https://github.com/akamai-open/AkamaiOPEN-powershell |
64 | | -[10]: https://github.com/akamai-open/AkamaiOPEN-edgegrid-node |
65 | | -[11]: https://github.com/akamai-open/AkamaiOPEN-edgegrid-C-Sharp |
66 | | -[12]: https://github.com/akamai-open/AkamaiOPEN-edgegrid-golang |
67 | | -[13]: https://github.com/AsyncHttpClient/async-http-client |
| 55 | + In addition to the required properties, an `.edgerc` file can optionally contain a `max-body` property. If absent, the implied default is 131072. |
68 | 56 |
|
69 | | -## Authors |
| 57 | + If you've inherited a `max-body` value of 8192 in your `.edgerc` file, that value is incorrect. If you encounter signature mismatch errors with POST requests, try removing that value from the file before trying anything else. |
70 | 58 |
|
71 | | -### Active |
| 59 | +3. Use your local `.edgerc` by providing the path to your resource file and credentials' section header in the `EdgeRcClientCredentialProvider` class from the `edgerc-reader` module. |
72 | 60 |
|
73 | | -Michał Wójcik <miwojci@akamai.com> |
| 61 | + ```java |
| 62 | + ClientCredential credential = EdgeRcClientCredentialProvider |
| 63 | + .fromEdgeRc("path/to/.edgerc", "your-section-header") |
| 64 | + .getClientCredential(null); |
| 65 | + ``` |
74 | 66 |
|
75 | | -Tatiana Slonimskaia <tslonims@akamai.com> |
| 67 | + Or hard code your credentials and pass the values to the `ClientCredential` class from the `edgegrid-signer-core` module. |
| 68 | +
|
| 69 | + ```java |
| 70 | + ClientCredential credential = ClientCredential.builder() |
| 71 | + .clientSecret("C113nt53KR3TN6N90yVuAgICxIRwsObLi0E67/N8eRN=") |
| 72 | + .host("akab-h05tnam3wl42son7nktnlnnx-kbob3i3v.luna.akamaiapis.net") |
| 73 | + .accessToken("akab-acc35t0k3nodujqunph3w7hzp7-gtm6ij") |
| 74 | + .clientToken("akab-c113ntt0k3n4qtari252bfxxbsl-yvsdj") |
| 75 | + .build(); |
| 76 | + ``` |
| 77 | +
|
| 78 | +## Use |
| 79 | +
|
| 80 | +Using one of the bindings to the HTTP client libraries, provide the path to your `.edgerc`, your credentials' section header, and the appropriate endpoint information. |
| 81 | +
|
| 82 | +The following is an example of making an HTTP call with Apache HTTP Client 5, one of the HTTP client libraries for Java that our EdgeGrid plug-in supports. |
| 83 | +
|
| 84 | +```java |
| 85 | +import java.io.IOException; |
| 86 | +
|
| 87 | +import org.apache.commons.configuration2.ex.ConfigurationException; |
| 88 | +import org.apache.hc.client5.http.classic.methods.HttpGet; |
| 89 | +import org.apache.hc.client5.http.impl.classic.BasicHttpClientResponseHandler; |
| 90 | +import org.apache.hc.client5.http.impl.classic.CloseableHttpClient; |
| 91 | +import org.apache.hc.client5.http.impl.classic.HttpClientBuilder; |
| 92 | +
|
| 93 | +import com.akamai.edgegrid.signer.ClientCredential; |
| 94 | +import com.akamai.edgegrid.signer.EdgeRcClientCredentialProvider; |
| 95 | +import com.akamai.edgegrid.signer.apachehttpclient5.ApacheHttpClient5EdgeGridInterceptor; |
| 96 | +import com.akamai.edgegrid.signer.apachehttpclient5.ApacheHttpClient5EdgeGridRoutePlanner; |
| 97 | +
|
| 98 | +public class GetUserProfile { |
| 99 | + public static void main(String[] args) throws ConfigurationException, IOException { |
| 100 | + ClientCredential credential = EdgeRcClientCredentialProvider |
| 101 | + .fromEdgeRc("~/.edgerc", "default") |
| 102 | + .getClientCredential(null); |
| 103 | +
|
| 104 | + try (CloseableHttpClient client = HttpClientBuilder.create() |
| 105 | + .addRequestInterceptorFirst(new ApacheHttpClient5EdgeGridInterceptor(credential)) |
| 106 | + .setRoutePlanner(new ApacheHttpClient5EdgeGridRoutePlanner(credential)) |
| 107 | + .build()) { |
| 108 | +
|
| 109 | + String uri = "https://" + credential.getHost() + "/identity-management/v3/user-profile"; |
| 110 | + System.out.println(client.execute(new HttpGet(uri), new BasicHttpClientResponseHandler())); |
| 111 | + } |
| 112 | + } |
| 113 | +} |
| 114 | +``` |
76 | 115 |
|
77 | | -### Inactive |
| 116 | +For details on how to make a call using this and other bindings to the HTTP client libraries, see each binding module's `README.md` file. |
78 | 117 |
|
79 | | -Martin Meyer <mmeyer@akamai.com> |
| 118 | +## Reporting issues |
80 | 119 |
|
81 | | -Maciej Gawinecki |
| 120 | +To report an issue or make a suggestion, create a new [GitHub issue](https://github.com/akamai/AkamaiOPEN-edgegrid-java/issues). |
82 | 121 |
|
83 | | -Roberto López López |
| 122 | +## License |
84 | 123 |
|
85 | | -## Contribute |
| 124 | +Copyright 2025 Akamai Technologies, Inc. All rights reserved. |
86 | 125 |
|
87 | | -This is an open-source library, and contributions are welcome. You're welcome |
88 | | -to fork this project and send us a pull request. |
| 126 | +Licensed under the Apache License, Version 2.0 (the "License"); |
| 127 | +you may not use these files except in compliance with the License. |
| 128 | +You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0. |
89 | 129 |
|
90 | | -Find valuable resources on the [Akamai Developer](https://developer.akamai.com/) website. |
| 130 | +Unless required by applicable law or agreed to in writing, software |
| 131 | +distributed under the License is distributed on an "AS IS" BASIS, |
| 132 | +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 133 | +See the License for the specific language governing permissions and |
| 134 | +limitations under the License. |
0 commit comments