¶ GenAuth - Java SDK OAuth2.0

OAuth is an open web standard for authorization, and the current version is 2.0.

¶ Initialization

When initializing AuthenticationClient, you need to pass the AuthenticationClientOptions parameter, some of its properties are listed below:

• appId <String> App ID, required.
• secret <String> Application Key, required.
• host <String> Full application address, such as https://sample-app.genauth.ai, without the final slash '/'.
• redirectUri <String> Business callback URL, required. For details, please refer to Authorization Code Mode (opens new window).
• protocol <ProtocolEnum> Protocol type, optional values ​​are OIDC, OAUTH, SAML, CAS, default is OIDC.
• tokenEndPointAuthMethod <AuthMethodEnum> Get token endpoint verification method, optional values ​​are CLIENT_SECRET_POST, CLIENT_SECRET_BASIC, NONE, default is CLIENT_SECRET_POST.
• introspectionEndPointAuthMethod <AuthMethodEnum> Verify token endpoint verification method, optional values ​​are CLIENT_SECRET_POST, CLIENT_SECRET_BASIC, NONE, default is CLIENT_SECRET_POST.
• revocationEndPointAuthMethod <AuthMethodEnum> Token revocation endpoint authentication method, optional values ​​are CLIENT_SECRET_POST, CLIENT_SECRET_BASIC, NONE, the default is CLIENT_SECRET_POST.

¶ Example

// Initialize with AppId and AppHost
AuthenticationClientOptions options = new AuthenticationClientOptions();
options.setAppId("AUTHING_APP_ID");
options.setAppHost("AUTHING_APP_HOST");
// protocol
options.setProtocol(ProtocolEnum.OAUTH.getValue());
AuthenticationClient authenticationClient = null;
try {
    authenticationClient = new AuthenticationClient(options);
} catch (IOException | ParseException e) {
    e.printStackTrace();
}

¶ Generate a user login link for the OAuth 2.0 protocol

authenticationClient.buildAuthorizeUrl(IOauthParams options)

Generate a user login link for the OAuth 2.0 protocol

¶ Parameters

• options <IOauthParams> Parameters to be filled in when initiating authorization login. For details, see Using OAuth2.0 Authorization Code Mode (opens new window).
• options.scope <String> Requested permission items, optional, the default value for the OAuth 2.0 protocol is user.
• options.state <String> Random string, optional, automatically generated by default.
• options.responseType <String> Response type, optional, optional values ​​are code, code id_token token, code id_token, code id_token, code token, id_token token, id_token, none; the default is code, authorization code mode.
• options.redirectUri <String> Callback address, required, default is the redirectUri parameter when the SDK is initialized.
• options.tenantId <String> Tenant ID, optional.

¶ Example

//options.setProtocol(ProtocolEnum.OAUTH.getValue());

IOauthParams iOauthParams = new IOauthParams();
iOauthParams.setRedirectUri("AUTHING_REDIRECTURI");
String respDto = authenticationClient.buildAuthorizeUrl(iOauthParams);

¶ Sample data

https://oidc1.genauth.ai/oauth/auth?state=7400704296715694&scope=user&client_id=5f17a529f64fb009b794a2ff&redirect_uri=https%3A%2F%2Fbaidu.com&response_type=code

¶ Code to Token

authenticationClient.getAccessTokenByCode(code)

Use the authorization code Code to obtain the user's Token information.

¶ Parameters

• code <String> Authorization code Code. After the user successfully authenticates, GenAuth will send the authorization code Code to the callback address. For details, please see Using OAuth 2.0 Authorization Code Mode (opens new window). Each Code can only be used once.

¶ Example

OIDCTokenResponse respDto = authenticationClient.getAccessTokenByCode("code");

¶ Sample Data

{
  "access_token": "fa9d2bdd914ea01aa4e434c12d4f919d749fc75c",
  "token_type": "Bearer",
  "expires_in": 1209599,
  "refresh_token": "b5e0e1afe793c6634495434afc262b88ddee9af3",
  "scope": "user"
}

¶ Token exchange user information

authenticationClient.getUserInfoByAccessToken(access_token)

Use Access token to obtain user information.

¶ Parameters

• access_token <String> Access token, the content of the Access token obtained by using the authorization code Code. For details, see Using OAuth 2.0 Authorization Code Mode (opens new window).

¶ Example

UserInfo userInfo = authenticationClient.getUserInfoByAccessToken("Access Token");

¶ Sample Data

{
  "address": {
    "country": null,
    "postal_code": null,
    "region": null,
    "formatted": null
  },
  "birthdate": null,
  "family_name": null,
  "gender": "U",
  "given_name": null,
  "locale": null,
  "middle_name": null,
  "name": null,
  "nickname": null,
  "picture": "https://files.authing.co/authing-console/default-user-avatar.png",
  "preferred_username": null,
  "profile": null,
  "updated_at": "2021-03-03T06:17:14.485Z",
  "website": null,
  "zoneinfo": null,
  "email": "test1@genauth.ai",
  "email_verified": false,
  "sub": "603f184cec4505e2868431fc", // Abbreviation of subject, which is the user ID
  "phone_number": null,
  "phone_number_verified": false
}

Field explanation:

¶ Refresh Access Token

authenticationClient.getNewAccessTokenByRefreshToken(refreshToken)

Use refresh token to get a new access token.

¶ Parameters

• refreshToken <String> Refresh token, which can be obtained from refresh_token in the return value of the authenticationClient.getAccessTokenByCode method.

¶ Example

GetNewAccessTokenByRefreshTokenRespDto respDto = authenticationClient.getNewAccessTokenByRefreshToken("Refresh Token");

¶ Sample Data

{
  "access_token": "fa9d2bdd914ea01aa4e434c12d4f919d749fc75c",
  "token_type": "Bearer",
  "expires_in": 1209599,
  "refresh_token": "b5e0e1afe793c6634495434afc262b88ddee9af3",
  "scope": "user"
}

¶ Check Access Token

authenticationClient.introspectToken(token)

Check the status of the Access token or Refresh token.

¶ Parameters

• token <String> Access token or Refresh token, which can be obtained from the access_token, refresh_token in the return value of the authenticationClient.getAccessTokenByCode method.

¶ Example

IntrospectTokenWithClientSecretPostRespDto respDto = authenticationClient.introspectToken("Access/Refresh token");

¶ Sample Data

Token is returned when it is valid:

{
  "active": true,
  "sub": "5f719946524ee1099229496b", // abbreviation of subject, which is user ID
  "client_id": "5f17a529f64fb009b794a2ff",
  "exp": 1619083024,
  "iat": 1617873424,
  "iss": "https://core.genauth.ai/oauth",
  "jti": "qbovGK-HZL0O_20wY7uXj",
  "scope": "user",
  "token_type": "Bearer"
}

When the token is invalid, it returns:

{
  "active": false
}

An error will be thrown if the verification process fails.