1. REST API for Oracle Insurance Policy AdministrationREST API for Oracle Insurance Policy Administration - OIPA
  2. Authentication and Authorization

Authentication and Authorization

All client users accessing the OIPA APIs must be authenticated in addition to being authorized for data access and functional behavior. The users must be:

  • Authenticated: To identify the user validity
  • Authorized for data access: Have access to Calendars, Cases, Clients, Codes, Companies, Domains, Group Customers, Outbound Applications, Plans, Policies, Products, Queries, Schemas, Segments, and Users and Security Groups resources
  • Authorized for functional behavior: To perform Create, Read, and Update functions

OIPA supports the OAuth 2.0 protocol and provides a token service for authentication and authorization of Service Layer REST requests. The OAuth protocol allows delegated authorization from a trusted external source, such as Identity Cloud Service (IDCS) or Active Directory. OAuth Client Credential Grant Flow is used in OIPA 11.3 to protect access to the Service API. However, the client application accesses the OIPA API through a Service Layer application (Resource Server) authenticating and authorizing against an Identity Provider (Authorization Server).

To access the OIPA REST resources over HTTPS, provide the following information for authentication:
  • An SSL certificate authority (CA) certificate file or bundle to authenticate against the Verisign CA certificate. Oracle Cloud uses a CA certificate issued by Verisign to enable clients to connect securely to the server. For more information, use cURL
  • The Authorization standard header to specify the OIPA account user with authorization to perform the operation in the specified identity domain. The value in the Authorization header depends on the type of authentication that you use to validate the user.

Obtaining and Using an OAuth Token

The Service Layer application should be registered with the Identity Provider (IDP). The registration process provides a CLIENT ID (client_id) and CLIENT SECRET (client_secret) for the Service Layer application. Both CLIENT ID and CLIENT SECRET must be configured in the SERVLET FILTER (Relying Party) configuration. The Relying Party (RP) configuration is stored in a secured file.

The user needs to provide the following:

  • Specify Trusted Application as the application type.
  • Select Resource Owner as the grant type.
  • Specify the Redirect URI, which is where responses to authentication requests are sent.

General Sequence Flow

The following illustrates the architecture of the oAuth Flow with the relying party:


oAuth Process Flow
  • When a user accesses the Service Layer custom oAuth2 URL ../PASService/rest/oauth2/token, they need to set the following parameters in the browser or Postman:
    • Header Parameters

      • Content-Type: application/x-www-form-urlencoded

      • Authorization: Basic base64Encoded client_id:cliend_secret

    • Form Parameters

    • username: username

    • password: password

    • grant_type: password

    • scope: urn:opc:idm:__myscopes__

    • redirect_uri= API URI, where IDP will redirect after authentication

    • Token URL: https URL for IDCS ../oauth2/v1/token or Service Layer custom oAuth2 token URL ../oauth2/token

  • The request is intercepted by a Servlet Filter (a relying party). The relying party ensures that the request is not signed (no access_token) and redirects the request to a configured IDP (IDCS) by passing all the parameters to the IDP oAuth2 URL ../oauth2/vi/token.
  • The Relying Party (Servlet Filter) must extract and prepare the following information before executing the IDP token service:
    • IDCS Token URL: https:// IDCS-Service-Instance.identity.oraclecloud.com/oauth2/v1/token
    • grant_type=password
    • scope=urn:opc:idm:__myscopes__
    • username= username provided by the USER via http request attributes
    • password= password provided by the USER via http request attributes
    • content-type=application/x-www-form-urlencoded
    • Authorization=Basic base64Encoded client_id:client_secret

  • IDP returns an access_token when a password credential is exchanged with the Servlet Filter. The Servlet Filter (RP) sends the access_token back to the client.

  • The user requests the resource API /PASService/rest/service/{resource}?access_token= token

  • The Servlet Filter extracts the access_token from the request parameter and validates against the IDP using validation URL of an IDP ../oauth2/v1/introspect.

  • The IDP returns a response to the validation.

  • If the token is valid, the Servlet Filter requests the API (redirect_url) that is requested from the Service Layer application.

  • The Service Layer application returns the response JSON back to the client.

The service should be a common set of source code (Java) that can accept a USER_ID and can load appropriate roles based on the security group it belongs to. Each Service API request must check the row security when a request is being made. The Service Layer processes the request as per the security privileges available for the security group to which the user belongs.

  • Service Layer checks with the database for the required security as per system date for performing the specified operation, that is PUT, POST, and GET.

  • If the security is available for the user, the requested operation will be performed or it results in a data access error ("Not Authorized").

    There are two layers of validation operating at the Service Layer:

    1. Role-based Security: to access a particular API
    2. Access Security: to access a particular resource

    Scope: The OAuth flow support the all the resources and their sub-resources present in the REST API.

Format: curl -i -H 'Authorization: Basic base64Encoded clientid:secret' -H 'Content-Type: application/x-www-form-urlencoded;charset=UTF-8' --request POST https://IDCS-Service-Instance/PASService/rest/oauth2/token -d 'grant_type=client_credentials&scope=scope value'

Sample: curl -i -H 'Authorization: Basic base64Encoded clientid:secret' -H 'Content-Type: application/x-www-form-urlencoded;charset=UTF-8' --request POST https://slc10hah.us.oracle.com:7010 /PASService/rest/oauth2/token -d'grant_type=client_credentials&scope=clients'

Error message descriptions are:

  • Invalid Access Token, or token denied, the resource should return an HTTP Error Code 401.

    "error": "invalid_token"

    "error_description": "The provided token is invalid"

  • Access not approved, the resource should return an HTTP Error Code 400

    "error": "access_denied"

    "error_description": "The access to the resource is refused by the server"