ebay / ebay-oauth-java-client

eBay OAuth APIs client for Java

eBay OAuth Client Library (Java)

Table of Contents

• What is OAuth 2.0
• Supported Languages
• Installation
• Getting Started
• Library Setup and getting started
• Types of Tokens
  • Application Token
  • User Token
• Supported Grant Types for OAuth
  • Grant Type: Client Credentials
  • Grant Type: Authorization Code
  • Grant Type: Refresh Token
• Contribution
• Additional Note: Using SnakeYaml in a safe manner
• Libraries used
• Developers and Contributors
• References
• License

eBay OAuth client library is a simple and easy-to-use library for integrating with eBay OAuth and designed to be used for OAuth 2.0 specification supported by eBay. There are multiple standard clients that can be used with eBay OAuth, such as Spring OAuth client. However, this library in addition to functioning as a simple eBay OAuth client, helps with additional features such as cached App tokens. There are also future enhancements planned to add id_token support, 'login with eBay' support etc.,

What is OAuth 2.0

OAuth 2.0 is the most widely used standard for authentication and authorization for API based access. The complete end to end documentation on how eBay OAuth functions is available at developer.ebay.com.

Supported Languages

This is created as a Maven based Java project and can be used as a dependency in a Java based application or other JVM based languages such as Groovy, Scala etc.,

Installation

Check the releases tab for the latest version. Add following to <dependencies/> section of your pom.xml as given below

<dependency>
    <groupId>com.ebay.auth</groupId>
    <artifactId>ebay-oauth-java-client</artifactId>
  <version>${latest.version}</version>
</dependency>

Getting Started

All interactions with this library can be performed using OAuth2Api oauth2Api = new OAuth2Api();

Library Setup and getting started

1. Ensure you have a config file in your source code of type YAML. Refer to ebay-config-sample.yaml.

2. This file would hold all your application credentials such as AppId, DevId, and CertId. Refer to Creating eBay Developer Account for details on how to get these credentials.

3. Once the file is created, call CredentialUtil.load(new FileInputStream(<your-config-location>)); to load the credentials.

4. It is recommended to load the credentials during startup time (initialization) to prevent runtime delays.

5. Once the credentials are loaded, call any operation on OAuth2Api

Types of Tokens

There are mainly two types of tokens in usage.

Application Token

An application token contains an application identity which is generated using client_credentials grant type. These application tokens are useful for interaction with application specific APIs such as usage statistics etc.,

User Token

A user token (access token or refresh token) contains a user identity and the application’s identity. This is usually generated using the authorization_code grant type or the refresh_token grant type.

Supported Grant Types for OAuth

All of the regular OAuth 2.0 specifications such as client_credentials, authorization_code, and refresh_token are all supported. Refer to eBay Developer Portal

Grant Type: Client Credentials

This grant type can be performed by simply using OAuth2Api.getApplicationToken(). Read more about this grant type at oauth-client-credentials-grant

Grant Type: Authorization Code

This grant type can be performed by a two step process. Call OAuth2Api.generateUserAuthorizationUrl() to get the Authorization URL to redirect the user to. Once the user authenticates and approves the consent, the callback need to be captured by the redirect URL setup by the app and then call OAuth2Api.exchangeCodeForAccessToken() to get the refresh and access tokens.

Read more about this grant type at oauth-authorization-code-grant and Quick Reference

Grant Type: Refresh Token

This grant type can be performed by simply using OAuth2Api.getAccessToken(). Usually access tokens are short lived and if the access token is expired, the caller can use the refresh token to generate a new access token. Read more about it at Using a refresh token to update a user access token

Contribution

Contributions in terms of patches, features, or comments are always welcome. Refer to CONTRIBUTING for guidelines. Submit Github issues for any feature enhancements, bugs, or documentation problems as well as questions and comments.

Additional Note: Using SnakeYaml in a safe manner

With the latest release (1.16 and above), SafeConstructor is used for Yaml object creation for SnakeYaml. This ensures that only default Java objects would be supported via config. Please ensure there are no tagging of custom classes or any other class in the YAML config files. Refer to SafeConstructor for further details.

Libraries used

1. okhttp

2. gson

3. SnakeYAML

4. joda-time

5. slf4j

6. commons-lang

7. json

8. jackson-databind

Developers and Contributors

1. @sengopal

2. @tanjav

3. @sonamrks

References

1. https://developer.ebay.com/api-docs/static/oauth-tokens.html

2. https://developer.ebay.com/api-docs/static/oauth-quick-ref-user-tokens.html

3. https://developer.ebay.com/api-docs/static/oauth-gen-app-token.html

4. https://developer.ebay.com/my/keys

License

Copyright (c) 2023 eBay Inc.

Use of this source code is governed by a Apache-2.0 license that can be found in the LICENSE file or at https://opensource.org/licenses/Apache-2.0.

ebay-oauth-java-client's Issues

Add the commonly used get-user-information as part of the Auth API

Add the commonly used get-user-information as part of the Auth API

Introduce dependency injection for testing using Guice

Introduce dependency injection for testing using Guice

Support Id token generation and validation to extract User Information

Support Id token generation and validation to extract User Information

Responses not being closed when using okhttp to send requests

From the okhttp documentation ( https://square.github.io/okhttp/4.x/okhttp/okhttp3/-response-body/ )

"Each response body is backed by a limited resource like a socket (live network responses) or an open file (for cached responses). Failing to close the response body will leak resources and may ultimately cause the application to slow down or crash."

This should be a simple enough change to apply in OAuth2Api.java and OAuth2Util.java

example on how to make a request

Hello,

Please could you show us how to get the token and an example of a request with token in the readme ?

Thanks for help

Cannot fetch new refresh token

Hi,

I haven't updated any of the dependencies and been using the same one. But all of a sudden the code keeps blowing up when running executing:
OAuth2Api.getAccessToken(Environment.PRODUCTION, refreshToken, scopes);

With this error:
{"error":"invalid_grant","error_description":"the provided authorization refresh token is invalid or was issued to another client"}

The refresh token I have supplied is URL encoded e.g.
<redacted>

Generating the refresh token from the authentication code works fine:
OAuth2Api.exchangeCodeForAccessToken(Environment.PRODUCTION, authCode);

Where is ebay-config-sample.yaml?

Use Sqllite or in-memory DB to persist and help maintain a DB system for refresh and access tokens

Use Sqllite or in-memory DB to persist and help maintain a DB system for refresh and access tokens. This will help demonstrate the capability of refresh and access tokens and on how to maintain their lifecycle.

Library does not cache client credential grant token for individual environment

The library has the capability to cache the client credential grant type access token but it does not cache token for the individual environment (production/sandbox).

ebay-oauth-java-client/src/main/java/com/ebay/api/client/auth/oauth2/OAuth2Api.java

Line 44 in 217b309

private OAuthResponse value;

Make token getters return empty optional, instead of null

Hi'

I've made a pull request: #14

The reasoning is that the methods:

• OAuthResponse.getAccessToken()
• OAuthResponse.getRefreshToken()

Returns both null and an optional containing the token.
(Depending on the success of the underlying call)

This is kind of fuzzy, and in my opinion beats the purpose of an optional.

And makes it necessary to do both a null check, and an isPresent() check

My change makes it so the two methods either returns:

• An empty Optional or an Optional containing the token.

I've also updated the test:

• ClientCredentialsTest. testInvalidOAuthScope

To expect this empty optional instead of a null value.

In addition i've removed a test from:

• EbayIdTokenValidatorTest. generateIdTokenAndVerify

The reasoning is that this test is not generally valid. As you can log in with both your preferred username, and email. And you never know which one was used. So if you log in with the email and compare with the preferred username then it's going to fail. But this is a feature, so tests should not fail in this instance (My opinion.)

Okay I hope this pull request is good.

Thanks
Steffen Otto Jensen