Add authentication and authorization using OIDC protocol

📘

Prerequisite

1. Setup OpenID Connect (OIDC) custom application in CyberArk Identity tenant
2. Install the CyberArk Identity Java SDK

OpenID Connect is a simple identity layer built on top of the OAuth 2.0 protocol, which allows clients to verify the identity of an end user based on the authentication performed by an authorization server and obtain basic profile information about the end user. This SDK provides an integration with CyberArk Identity OpenID Connect web app based on OAuth 2.0 standards in 10 minutes which brings the ease of managing users.

This guide provides methods for instantiating OIDC clients and making authorization and token calls to CyberArk Identity. The guide also provides claims, refresh, revoke, and user info SDK methods.

Configure OIDC client instance

Configure the OIDCClient object by providing the OpenID Connect application details that will allow the client application to make authorized API requests.

The OIDCClient object can be created either with/without the client's secret.

• With tenantURL, applicationId and clientId parameters that behind the scenes act as meta-data. In this case client_secret is not passed to the object.

OIDCClient identityOIDCClient;
identityOIDCClient = new OIDCClient(tenantURL, appId, clientId);

Or clientSecret parameter can be passed to the object as below:

OIDCClient identityOIDCClient;
identityOIDCClient = new OIDCClient(tenantURL, appId, clientId, clientSecret);

Note: Client secret is required to refresh or revoke the access token.

Constructor parameter definition

Authorization request

The client application should send an authorization request using AuthorizeUrlBuilder to authenticate the user with the CyberArk Identity provider as shown below:

AuthorizeUrlBuilder authorizeUrl(String redirectUri);

Required parameters

• redirectUri - The URL that a user will be redirected to after successful authentication.
  It is a required parameter and must be a valid URL. The redirectUri must be a part of the authorized redirect URIs that can be configured on the admin portal in the Trust tab

Parameters can be added to the authorize URL using the builder methods as shown below.

// Sets the scope value.
AuthorizeUrlBuilder setScope(String scope);

// Sets the response type value.
AuthorizeUrlBuilder setResponseType(String responseType);

// Sets the state value.
AuthorizeUrlBuilder setState(String state);

// Sets the code challenge value.
AuthorizeUrlBuilder setCodeChallenge(String codeChallenge);

// Sets the code challenge method value.
AuthorizeUrlBuilder setCodeChallengeMethod(String codeChallengeMethod);

// Adds an additional parameter to the authorize URL.
AuthorizeUrlBuilder addAdditionalParameter(String name, String value);

The build() method returns the authorization URL.

Token request

The client application should create a request to exchange the authorization code previously obtained by calling the /authorize endpoint as below:

TokenRequest requestToken(String code, String redirectUri);

Required parameters

• code - The code previously obtained by calling the /authorize endpoint.
• redirectUri - The URL that a user is directed to after successful authentication.

Parameters can be added to the token URL using the builder methods as shown below.

// Sets the client id.
TokenRequest setClientId(String clientId);

// Sets the client secret.
TokenRequest setClientSecret(String clientSecret);

// Sets the authorization code value.
TokenRequest setAuthorizationCode(String authorizationCode);

// Sets the redirectURI URL.
TokenRequest setRedirectURI(String redirectURI);

// Sets the code verifier value.
TokenRequest setCodeVerifier(String codeVerifier);

// Sets the grantType to authorization_code.
TokenRequest setGrantType(String grantType);

// Sets the scope value.
TokenRequest setScope(String scope);

// Adds an additional header to the Token Request.
TokenRequest addHeader(String name, String value);

Decode ID token

The client can use the below method to decode the ID token. The ID token contains claims about the authenticated user.

JsonNode claims = OIDCClient.claims(YOUR_ID_TOKEN);

Access userinfo endpoint

To get claims from the userinfo endpoint, the client application can use the below method by passing an access token as a bearer as below:

OIDCClient oidcClient = new OIDCClient("YOUR_TENANT_URL", "YOUR_OIDC_APP_ID", "YOUR_CLIENT_ID");
try
{
   UserInfo result = oidcClient.userInfo("YOUR_ACCESS_TOKEN").execute();
} 
catch (IdentityException e)
{
   logger.error("Exception occurred while executing revoke token request : ", ex);
   throw ex;
}

Revoke token

The revoke token can be used to revoke the access, ID, or refresh tokens. The client can implement the revoke token as below:

OIDCClient oidcClient = new OIDCClient("YOUR_TENANT_URL", "YOUR_OIDC_APP_ID", "YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET");
VoidRequest request = oidcClient.revokeToken(YOUR_TOKEN);
try 
{
    request.execute();
} 
catch (IdentityException ex)
{
   logger.error("Exception occurred while executing revoke token request : ", ex);
   throw ex;
}

Refresh tokens

The refresh tokens can be used to get new access tokens once the access token is expired. The client can use the below method to obtain new access tokens.

To get the refresh_token, make sure to enable Issue refresh tokens in the OIDC web application Tokens section.

OIDCClient oidcClient = new OIDCClient("YOUR_TENANT_URL", "YOUR_OIDC_APP_ID", "YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET");
TokenRequest tokenRequest = oidcClient.refreshToken(YOUR_REFRESH_TOKEN);
try 
{
    TokenHolder tokenHolder = tokenRequest.execute();
} 
catch (IdentityException ex)
{
    logger.error("Exception occurred while executing refresh token request : ", ex);
    throw ex;
}

Introspect tokens

The introspect URL can be used to validate the tokens. The client can use the below method to validate the tokens:

GenericTokenRequest introspect(String accessToken);

Required parameters

• accessToken - The access token that was previously obtained from the token request.