¶ GenAuth - Java SDK OIDC module

Update time: 2025-07-23 07:34:21

OpenID Connect, also known as OIDC, is an extension of OAuth 2.0, which mainly adds semantic user information fields.

¶ Initialization

When initializing AuthenticationClient, you need to pass the AuthenticationClientOptions parameter, some of which 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 last 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> Inspection token endpoint authentication method, optional values are CLIENT_SECRET_POST, CLIENT_SECRET_BASIC, NONE, default is CLIENT_SECRET_POST.
revocationEndPointAuthMethod <AuthMethodEnum> Revocation token endpoint authentication method, optional values are CLIENT_SECRET_POST, CLIENT_SECRET_BASIC, NONE, 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");
AuthenticationClient authenticationClient = null;
try {
  authenticationClient = new AuthenticationClient(options);
} catch (IOException | ParseException e) {
  e.printStackTrace();
}

authenticationClient.buildAuthorizeUrl(IOidcParams options)

Generate user login link for OIDC protocol

¶ Parameters

options <IOidcParams> Parameters to be filled in when initiating authorized login. For details, please see Using OIDC Authorization Code Mode (opens new window).
options.scope <String> Requested permission items, optional, OIDC protocol defaults to openid profile email phone address.
options.nonce <String> Random string, optional, automatically generated by default.
options.state <String> Random string, optional, automatically generated by default.
options.responseMode <String> Response type, optional, optional values are query, fragment, form_post; the default is query, that is, the code is sent to the callback address through browser redirection.
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

// Concatenate OIDC authorization link
IOidcParams iOidcParams = new IOidcParams();
iOidcParams.setRedirectUri("AUTHING_REDIRECTURI");
iOidcParams.setNonce("nonce test");
String respDto = authenticationClient.buildAuthorizeUrl(iOidcParams);

¶ Sample Data

https://oidc1.genauth.ai/oidc/auth?nonce=5485323897342262&state=7400704296715694&scope=openid+profile+offline_access&client_id=5f17a529f64fb009b794a2ff&response_mode=query&redirect_uri=https%3A%2F%2Fbaidu.com&response_type=code&prompt=consent

¶ 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 OIDC Authorization Code Mode (opens new window). Each Code can only be used once.

¶ Example

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

¶ Sample Data

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IlRmTE90M0xibjhfYThwUk11ZXNzYW1xai1vM0RCQ3MxLW93SExRLVZNcVEifQ.eyJqdGkiOiJsdzg0NW5zdGcwS3EtMTlodVpQOHYiLCJzdWIiOiI1ZmY3MDFkODQ2YjkyMDNlMmY2YWM2ZjMiLCJpYXQiOjE2MTU4ODM1ODYsImV4cCI6MTYxNTg4NzE4Niwic2NvcGUiOiJlbWFpbCBvcGVuaWQgcHJvZmlsZSBwaG9uZSIsImlzcyI6Imh0dHBzOi8vb2lkYzEuYXV0aGluZy5jbi9vaWRjIiwiYXVkIjoiNWYxN2E1MjlmNjRmYjAwOWI3OTRhMmZmIn0.VvYKBcWcr8iIi1b37ugWQ9hsvog4_7EqDQyFqwhIuvM0NHlHH3Bhw83EQIKSNfbWV4nv3ihfeNGPLMzslbQr-wwjnWZTLMYl1bcn7IdVtD_kTN3Zz10MwF5td-VQ7UndU28wJ0HE1mo6E8QH93kYGckS5FSZXmCBa0M5H59Jec_a1MHI1MZrr_V9cZ9EfeF97V-PcqU8JVAwDZclCJ3mWY_Mb65RnMR9yEVqUZzJStmaXGMuRIzjkm2pklqt0CtQQJfzECXq_4USpwRXDiYLWILYPUCcO6hGxDjhMEd8IcxdG51TQP-w1UM6LyIRn61uSJvDsz8zg5dStDKyocypiA",
  "expires_in": 3600,
  "id_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJlbWFpbCI6InRlc3QzQDEyMy5jb20iLCJlbWFpbF92ZXJpZmllZCI6ZmFsc2UsInN1YiI6IjVmZjcwMWQ4NDZiOTIwM2UyZjZhYzZmMyIsImJpcnRoZGF0ZSI6bnVsbCwiZmFtaWx5X25hbWUiOm51bGwsImdlbmRlciI6IlUiLCJnaXZlbl9uYW1lIjpudWxsLCJsb2NhbGUiOm51bGwsIm1pZGRsZV9uYW1lIjpudWxsLCJuYW1lIjpudWxsLCJuaWNrbmFtZSI6bnVsbCwicGljdHVyZSI6Imh0dHBzOi8vZmlsZXMuYXV0aGluZy5jby9hdXRoaW5nLWNvbnNvbGUvZGVmYXVsdC11c2VyLWF2YXRhci5wbmciLCJwcmVmZXJyZWRfdXNlcm5hbWUiOm51bGwsInByb2ZpbGUiOm51bGwsInVwZGF0ZWRfYXQiOiIyMDIxLTAzLTE1VDA1OjU0OjU0LjY4NVoiLCJ3ZWJzaXRlIjpudWxsLCJ6b25laW5mbyI6bnVsbCwicGhvbmVfbnVtYmVyIjpudWxsLCJwaG9uZV9udW1iZXJfdmVyaWZpZWQiOmZhbHNlLCJub25jZSI6IjcwVEU3eW9NVFEiLCJhdF9oYXNoIjoiUFNnOGw5eDRldGxmLXA4UDdjYnVoQSIsImlzcyI6Imh0dHBzOi8vb2lkYzEuYXV0aGluZy5jbi9vaWRjIiwiaXNzMiI6Imh0dHBzOi8vYmFpZHUuY29tIiwiYXVkIjoiNWYxN2E1MjlmNjRmYjAwOWI3OTRhMmZmIiwiZXhwIjoxNjE1ODg3MTg3LCJpYXQiOjE2MTU4ODM1ODh9.OlX-FP7znIEqx0YpnOQ8kxadMe1toHDj1KPVm0dbEVc",
  "scope": "email openid profile phone",
  "token_type": "Bearer"
}

Field explanation:

Field name	Meaning
token_type	Token type, fixed value Bearer
scope	Authorization scope, authorized user permission items
id_token	Id token, Id token issued by GenAuth
expires_in	Access token expiration time
access_token	Access token, Access token issued by GenAuth

¶ Token exchange for 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 exchanged with the authorization code Code. For details, see Using OIDC Authorization Code Mode (opens new window).

¶ Example

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

¶ Sample Data

{
  "sub": "603f184cec4505e2868431fc", // Abbreviation of subject, which is the user ID
  "name": "example",
  "nickname": "example",
  "given_name": "example",
  "family_name": "example",
  "birthdate": "2022-02-22",
  "gender": "M",
  "picture": "https://files.authing.co/authing-console/default-user-avatar.png",
  "updatedAt": "2021-03-03T06:17:14.485Z",
  "zoneinfo": null,
  "preferred_username": null,
  "locale": null
}

Field explanation:

Field name	Translation
sub	Abbreviation of subject, unique identifier, usually user ID
name	full name
nickname	nickname
given_name	full name
family_name	full name
birthdate	birthday
gender	gender
picture	avatar
updated_at	information update time
zoneinfo	time zone
preferred_username	name you want to be called
locale	region

¶ Refresh Access Token

authenticationClient.getNewAccessTokenByRefreshToken(refreshToken)

Get a new Access token using Refresh token.

¶ Parameters

refreshToken <String> Refresh token, which can be obtained from refresh_token in the return value of authenticationClient.getAccessTokenByCode method. For details, see Refresh Access token (opens new window).

¶ Example

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

¶ Sample Data

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IlRmTE90M0xibjhfYThwUk11ZXNzYW1xai1vM0RCQ3MxLW93SExRLVZNcVEifQ.eyJqdGkiOiJZUHB4NUVEWGlQWVJvNUFQWXAzci0iLCJzdWIiOiI1ZmY3MDFkODQ2YjkyMDNlMmY2YWM2ZjMiLCJpYXQiOjE2MTQwOTE0OTksImV4cCI6MTYxNDA5NTA5OSwic2NvcGUiOiJvZmZsaW5lX2FjY2VzcyBwcm9maWxlIG9wZW5pZCIsImlzcyI6Imh0dHBzOi8vb2lkYzEuYXV0aGluZy5jbi9vaWRjIiwiYXVkIjoiNWYxN2E1MjlmNjRmYjAwOWI3OTRhMmZmIn0.ZN_SlfVg1oNMz7uAK-5K84dqqqmlZehmAPOLytOR9HnLHImKJ9VO5u1hRsAjGCob0kMUV5wVxQhX3EFks7FtMamiX2Jvn-NYh4V_5T6l3LFf4uoKF6AykAg483nG3EEENuGgQo15bBszsoCGqFnNmUd0T4Cgxx0zbxXPxMdp_dcE14KzmNz1w-Qg3yVeYmSTZFdcLtZA2BYnVEa7LYA2yA3DgawwAcRmrlyEfnvCO3uY2TcsTKEAfQ-QgVIGRWOfyUE5f-_X3TolliO1fXnwZBdxEKMXLGW5E2bPVcePyiV0upYbUnQ079UxBlEiWlgeW_rpkTPXDxHAgiE488gtlg",
  "expires_in": 3600,
  "id_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI1ZmY3MDFkODQ2YjkyMDNlMmY2YWM2ZjMiLCJiaXJ0aGRhdGUiOm51bGwsImZhbWlseV9uYW1lIjpudWxsLCJnZW5kZXIiOiJVIiwiZ2l2ZW5fbmFtZSI6bnVsbCwibG9jYWxlIjpudWxsLCJtaWRkbGVfbmFtZSI6bnVsbCwibmFtZSI6bnVsbCwibmlja25hbWUiOm51bGwsInBpY3R1cmUiOiJodHRwczovL2ZpbGVzLmF1dGhpbmcuY28vYXV0aGluZy1jb25zb2xlL2RlZmF1bHQtdXNlci1hdmF0YXIucG5nIiwicHJlZmVycmVkX3VzZXJuYW1lIjpudWxsLCJwcm9maWxlIjpudWxsLCJ1cGRhdGVkX2F0IjoiMjAyMS0wMi0yM1QxNDo0NDoxOC4wODVaIiwid2Vic2l0ZSI6bnVsbCwiem9uZWluZm8iOm51bGwsImF0X2hhc2giOiIxaWRJSUxaWExpZkRscXJMY3ZNeV9BIiwiS0VZIjoiVkFMVUUiLCJhdWQiOiI1ZjE3YTUyOWY2NGZiMDA5Yjc5NGEyZmYiLCJleHAiOjE2MTQwOTUwOTgsImlhdCI6MTYxNDA5MTQ5OSwiaXNzIjoiaHR0cHM6Ly9vaWRjMS5hdXRoaW5nLmNuL29pZGMifQ._H59237sqpsY0OgyY_RM7CvuG6cFo1x03y-DBhd5hik",
  "refresh_token": "3T49f4Y48szoMmwBXragjqLwQZC4QhgnsM5Oy2WfmU-",
  "scope": "openid offline_access profile",
  "token_type": "Bearer"
}

¶ Check Access Token

authenticationClient.introspectToken(token)

Check the status of Access token or Refresh token.

¶ Parameters

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

¶ Example

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

¶ Sample Data

Returns when the token is valid:

{
  "active": true,
  "sub": "60097f4d5bc08f75da104d18", // Abbreviation of subject, which is the user ID
  "client_id": "60097391b1358c17c5fb0f4e",
  "exp": 1612445888,
  "iat": 1611236288,
  "iss": "https://core.littleimp.cn/oidc",
  "jti": "TV4J0gAbe4KR4-8CtYcOa",
  "scope": "openid profile email phone offline_access",
  "token_type": "Bearer"
}

Returns when the token is invalid:

{
  "active": false
}

An error will be thrown if the verification process fails.

¶ Verify the validity of the ID Token

authenticationClient.validateToken(param)

Verify the ID token or Access token through the online interface provided by GenAuth, which will generate a network request.

¶ Parameters

param <ValidateTokenParams>
param.idToken <String> Access token or Refresh token, which can be obtained from the id_token in the return value of the authenticationClient.getAccessTokenByCode method.
param.accessToken <String> Access token, which can be obtained from the access_token in the return value of the authenticationClient.getAccessTokenByCode method.

¶ Example

ValidateTokenParams params = new ValidateTokenParams();
// params.setIdToken("Id Token");
params.setAccessToken("Access Token");
ValidateTokenRespDto respDto = authenticationClient.validateToken(params);

¶ Sample Data

When id_token is verified to be legal, it returns:

{
  "sub": "5f64afd1ad501364e3b43c1e", // Abbreviation of subject, which is the user ID
  "birthdate": null,
  "family_name": null,
  "gender": "U",
  "given_name": null,
  "locale": null,
  "middle_name": null,
  "name": null,
  "nickname": null,
  "picture": "https://usercontents.genauth.ai/authing-avatar.png",
  "preferred_username": "test1",
  "profile": null,
  "updated_at": "2020-09-27T06:06:29.853Z",
  "website": null,
  "zoneinfo": null,
  "email": "test1@123.com",
  "email_verified": false,
  "phone_number": null,
  "phone_number_verified": false,
  "nonce": "CQsguqUdl7",
  "at_hash": "10iOtwuTNtyQLzlNYXAHeg",
  "aud": "5f17a529f64fb009b794a2ff",
  "exp": 1601460494,
  "iat": 1601456894,
  "iss": "https://oidc1.genauth.ai/oidc"
}

When the ID token is invalid, the following is returned:

{ "code": 400, "message": "id_token format is incorrect" }

{ "code": 400, "message": "id_token is illegal" }

When the Access token is valid, the following is returned:

{
  "jti": "K5TYewNhvdGBdHiRifMyW",
  "sub": "5f64afd1ad501364e3b43c1e", // Abbreviation of subject, which is the user ID
  "iat": 1601456894,
  "exp": 1601460494,
  "scope": "openid profile email phone",
  "iss": "https://oidc1.genauth.ai/oidc",
  "aud": "5f17a529f64fb009b794a2ff"
}

Access token verification is invalid and returns:

{ "code": 400, "message": "access_token format is incorrect" }

{ "code": 400, "message": "access_token is illegal" }

¶ Concatenate the logout URL

authenticationClient.buildLogoutUrl(params)

Concatenate the logout URL.

¶ Parameters

params <ILogoutParams> Logout configuration items
params.state <String> Random string, optional, automatically generated by default
params.redirectUri <String> Redirect address after logout
params.idToken <String> User's idToken

¶ Example

Log out using the front-end universal logout link:

// Concatenate the front-end universal logout link
BuildLogoutUrlParams params = new BuildLogoutUrlParams();
String logoutUrl = authenticationClient.buildLogoutUrl(params);

To log out using the OIDC protocol standard link, you need to setProtocol in authenticationClientOptions (default OIDC), you need to pass in the current user's Id token, and the logout callback address must be consistent with the console configuration:

// Splice the logout link that complies with the OIDC protocol standard
BuildLogoutUrlParams params = new BuildLogoutUrlParams();
params.setPostLogoutRedirectUri("AUTHING_LOGOUG_REDIRECT_URI");
params.setIdTokenHint("AUTHING_ID_TOKEN");
params.setState("random string");
String logoutUrl = authenticationClient.buildLogoutUrl(params);

¶ Get Access Token in Client Credentials mode

authenticationClient.getAccessTokenByClientCredentials(scope, options)

Use Programmatic Access Account (opens new window) to get an Access Token with permissions.

¶ Parameters

scope <String> Permission items, space-delimited strings, each representing a permission. For details, see Machine-to-machine (M2M) authorization (opens new window).
options <ClientCredentialInput> AK and SK information of programmatic access account
options.accessKey <String> Programmatic access account AccessKey
options.secretKey <String> Programmatic access account SecretKey

¶ Example

ClientCredentialInput input = new ClientCredentialInput();
input.setAccessKey("AUTHING_ACCESS_KEY");
input.setAccessSecret("AUTHING_ACCESS_SECRET");
GetAccessTokenByClientCredentialsRespDto respDto = authenticationClient.getAccessTokenByClientCredentials("scope", input);

¶ Sample Data

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IlRmTE90M0xibjhfYThwUk11ZXNzYW1xai1vM0RCQ3MxLW93SExRLVZNcVEifQ.eyJqdGkiOiJsdzg0NW5zdGcwS3EtMTlodVpQOHYiLCJzdWIiOiI1ZmY3MDFkODQ2YjkyMDNlMmY2YWM2ZjMiLCJpYXQiOjE2MTU4ODM1ODYsImV4cCI6MTYxNTg4NzE4Niwic2NvcGUiOiJlbWFpbCBvcGVuaWQgcHJvZmlsZSBwaG9uZSIsImlzcyI6Imh0dHBzOi8vb2lkYzEuYXV0aGluZy5jbi9vaWRjIiwiYXVkIjoiNWYxN2E1MjlmNjRmYjAwOWI3OTRhMmZmIn0.VvYKBcWcr8iIi1b37ugWQ9hsvog4_7EqDQyFqwhIuvM0NHlHH3Bhw83EQIKSNfbWV4nv3ihfeNGPLMzslbQr-wwjnWZTLMYl1bcn7IdVtD_kTN3Zz10MwF5td-VQ7UndU28wJ0HE1mo6E8QH93kYGckS5FSZXmCBa0M5H59Jec_a1MHI1MZrr_V9cZ9EfeF97V-PcqU8JVAwDZclCJ3mWY_Mb65RnMR9yEVqUZzJStmaXGMuRIzjkm2pklqt0CtQQJfzECXq_4USpwRXDiYLWILYPUCcO6hGxDjhMEd8IcxdG51TQP-w1UM6LyIRn61uSJvDsz8zg5dStDKyocypiA",
  "expires_in": 3600,
  "scope": "email openid profile phone",
  "token_type": "Bearer"
}

Previous article: Get country list Next article: OAuth module

¶ GenAuth - Java SDK OIDC module

¶ Initialization

¶ Example

¶ Generate user login link for OIDC protocol

¶ Parameters

¶ Example

¶ Sample Data

¶ Code to Token

¶ Parameters

¶ Example

¶ Sample Data

¶ Token exchange for user information

¶ Parameters

¶ Example

¶ Sample Data

¶ Refresh Access Token

¶ Parameters

¶ Example

¶ Sample Data

¶ Check Access Token

¶ Parameters

¶ Example

¶ Sample Data

¶ Verify the validity of the ID Token

¶ Parameters

¶ Example

¶ Sample Data

¶ Concatenate the logout URL

¶ Parameters

¶ Example

¶ Get Access Token in Client Credentials mode

¶ Parameters

¶ Example

¶ Sample Data