Using Custom OAuth Providers with Billing Care REST API

44 Using Custom OAuth Providers with Billing Care REST API

Learn how to customize the Billing Care REST API to authenticate your client applications with an OAuth token management tool other than Oracle Access Manager.

Topics in this document:

About OAuth Token Management Tools

The Billing Care REST API authenticates requests from your client applications by using OAuth 2.0. By default, it uses Oracle Access Manager to generate, manage, and validate OAuth tokens. However, you can customize the Billing Care REST API to use a different OAuth token management tool by using the Billing Care SDK.

For more information about the Billing Care REST API, see REST API Reference for Billing Care.

The Billing Care SDK includes samples that you can use for developing your own customizations in the SDK_home/samples/OAuthTokenCustomization directory, where SDK_home is the Billing Care SDK installation directory.

To use a different OAuth token management tool with the Billing Care REST API:

Create a custom OAuth token module that defines the logic for generating and validating OAuth access tokens. See "Creating a Custom Token Module".
Create wrapper Java classes. These classes reflect the JSON or XML response specification for your OAuth token management tool, which are required to convert the response into a Java Object for further actions. The variables in the wrapper classes will vary according to the different fields that the response contains.

You can use the sample wrapper files in the SDK_home/samples/OAuthTokenCustomization/src/java/com/oracle/communications/brm/sdk/model directory for guidance.
Configure the Billing Care REST API to use your custom OAuth token module. See "Adding a Custom OAuth Token Module to the customModule.properties File".
Deploy your customizations as a shared library to the Billing Care REST API. See "Packaging and Deploying Customizations".

Note:

Ensure that any third-party libraries or JARs required by the OAuth token management tool are packaged in the SDK .war file.

Creating a Custom Token Module

Create a new CustomTokenModule.java class that extends the default PCMOAuthTokenModule.java class. The new class should override the token management logic used in the default class's queryAccessToken() and validateToken() methods.

To create a custom token module:

Create a CustomTokenModule.java file in your myproject/src/com/oracle/communications/brm/sdk/modules/ directory, where myproject is your IDE project folder containing your Billing Care REST API customizations.
Open the CustomTokenModule.java file in an editor.

Override the queryAccessToken() method to implement the logic for sending a request to create an OAuth 2.0 token with your OAuth token management tool. This method needs to return a response with the token.

For example:

@Override
public Response queryAccessToken(HttpServletRequest servletRequest) throws ApplicationException, JsonProcessingException {
    logger.entering("queryAccessToken");
    loadOAUTHAttributes();
    String BASE_64_CREDENTIALS = servletRequest.getHeader(HttpHeaders.AUTHORIZATION);

    Feature feature = new LoggingFeature(logger.getLogger(), Level.FINE,
        LoggingFeature.Verbosity.PAYLOAD_ANY, null);
    Client client = ClientBuilder.newBuilder().register(feature).build();

    System.setProperty("sun.net.http.allowRestrictedHeaders", "true");
    Response response = client.target(OAM_OAUTH_URL + "/token")
        .queryParam("grant_type", "CLIENT_CREDENTIALS")
        .queryParam("scope", OAM_OAUTH_BC_RESOURCE_SCOPE)
        .request()
        .header(HttpHeaders.AUTHORIZATION, BASE_64_CREDENTIALS)
        .header(HttpHeaders.CONTENT_TYPE, MediaType.APPLICATION_FORM_URLENCODED)
        .header("X-OAUTH-IDENTITY-DOMAIN-NAME", OAM_OAUTH_ID_DOMAIN)
        .post(Entity.entity("", MediaType.APPLICATION_FORM_URLENCODED), Response.class);
    String responseString = response.readEntity(String.class);
    ObjectMapper mapper = new ObjectMapper();
    Response.ResponseBuilder builder;
    if (response.getStatus() == Response.Status.OK.getStatusCode()) {
        OAuthTokenWrapper tokenWrapper = mapper.readValue(responseString, OAuthTokenWrapper.class);
        builder = Response.status(response.getStatus()).entity(tokenWrapper);
    } else {
        OAuthTokenErrorMsgWrapper tokenErrorMsgWrapper = mapper.readValue(responseString, OAuthTokenErrorMsgWrapper.class);
        builder = Response.status(response.getStatus()).entity(tokenErrorMsgWrapper);
    }
    logger.exiting("queryAccessToken");
    return builder.build();

}

Override the validateToken() method to use the OAuth token returned in step 2 for validation. If validation is successful, this method needs to return the CLIENT_ID.

The CLIENT_ID must then be added to the Oracle Unified Directory and assigned to groups according to their expected permissions.

This example shows remote validation using Oracle Access Manager to validate the token, but your implementation can validate the token locally without a REST API call.

@Override
public String validateToken(HttpServletRequest servletRequest) throws InvalidTokenException, JsonProcessingException {
    logger.entering("validateToken");
    loadOAUTHAttributes();
    String clientId = "";
    String token = getTokenFromRequest(servletRequest);

    Feature feature = new LoggingFeature(logger.getLogger(), Level.INFO, LoggingFeature.Verbosity.PAYLOAD_ANY, null);
    Client client = ClientBuilder.newBuilder().register(feature).build();

    System.setProperty("sun.net.http.allowRestrictedHeaders", "true");
    Response response = client.target(OAM_OAUTH_URL + "/token/info")
        .queryParam("access_token", token)
        .request()
        .header("X-OAUTH-IDENTITY-DOMAIN-NAME", OAM_OAUTH_ID_DOMAIN)
        .header(HttpHeaders.CONTENT_TYPE, MediaType.APPLICATION_JSON)
        .get(Response.class);
    ObjectMapper objectMapper = new ObjectMapper();
    if (response.getStatus() == Response.Status.OK.getStatusCode()) {
        String responseString = response.readEntity(String.class);
        objectMapper.configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false);
        objectMapper.configure(JsonParser.Feature.ALLOW_BACKSLASH_ESCAPING_ANY_CHARACTER, true);
        objectMapper.configure(JsonParser.Feature.ALLOW_UNQUOTED_CONTROL_CHARS, true);
        OAuthTokenValidationWrapper validationResponse = objectMapper.readValue(
            responseString, OAuthTokenValidationWrapper.class);
        clientId = validationResponse.client;
    } else {
        logger.exiting("validateToken");
        throw new InvalidTokenException(response.readEntity(String.class));
    }
    logger.exiting("validateToken");
    return clientId;
}

Save the file in your NetBeans IDE project.

Adding a Custom OAuth Token Module to the customModule.properties File

Configure the Billing Care REST API to use your custom OAuth token module by editing the customModule.properties file. See "About the customModule.properties File" for more information.

To add a custom OAuth token module:

Open the myproject/src/java/custom/customModule.properties file in a text editor.

Add the following entry:

billingcare.rest.oauthtoken.module=com.oracle.communications.brm.sdk.modules.CustomTokenModule

Save the file in your NetBeans IDE project.