Set up Access to REST API

The Oracle Cloud Service applications are used for API authentication and authorization. The applications add controls that enable you to issue tokens with READ (GET as an example) and ADMIN (POST as an example).

In OCI IAM, the controls are referred to as scopes. These scopes are available for each Student Financial Aid (SFA) environment:

• /audit.admin
• /audit.readonly
• /mpg.admin
• /mpg.readonly
• /ui.admin
• /ui.readonly
• /vug.admin
• /vug.readonly

Here are examples of when to use the different scopes:

• When you need to make a READ (GET) call to the Vocado US Department of Education Gateway (VUG) API, you would request a token with only the /vug.readonly scope for the corresponding SFA environment.
• When you need to make an ADMIN (POST) call to the Message Processing Gateway (MPG) API, you would request a token with only the /mpg.admin scope for the corresponding SFA environment.

Environment URLs and Endpoints

Here's the list of production and test environments as well as the endpoints.

Production and Test Environment Formats

Production Environment	Test Environment
Format: https://sfp.ocs.oraclecloud.com/<environment>/<endpoint> Example: https://sfp.ocs.oraclecloud.com/oracleprod/<endpoint>	Format: https://sfp.ocs.oc-test.com/<environment>/<endpoint> Example: https://sfp.ocs.oc-test.com/oracletest/<endpoint>

These are the endpoints in the production and test environments:

• API
  • /audit/v2
  • /mpg/v2
  • /portal/info
  • /vm-ui/rest
  • /vug/v2
• Financial Aid System and Self-Service Portal
  • /vm-ui/ui-auth
  • /portal/ui-auth

Add a Confidential Application

To access the APIs for all your SFA environments, you need to create a Confidential Application for which you can regenerate the credentials on an ongoing basis, and control who has access to it.

For the complete instructions, see Adding a Confidential Application. The steps outlined below provide some recommendations as you add a new application.

1. From OCI's navigation menu, go to Identity & Security > Domains > <your OCI identity domain> > Integrated applications.
2. Add a new application.
3. Select Confidential Application.
   1. Enter the required information.
   2. Select Enforce grants as authorization.
4. On the Configure OAuth pane, select Configure this application as a client now.
5. Select Client Credentials.
6. Select Add resources.
   1. Expand the . . ._ADMIN app that corresponds to the SFA environment you want to interact with via REST API.
   2. Select the corresponding scope for the activity.

      You can select the checkbox next to all . . ._ADMIN apps that correspond to your SFA environments to add all scopes for those environments. But it's good practice to include only the SFA environments and specific scopes in the "Resources" of the Integrated application that are needed at the time, and to keep the "Resources" empty when not in use.

      By default, any scopes for newly provisioned SFA environments will not be included in "Resources."

   3. Select Add.
7. Select Add app roles.
   1. Select Signin.
   2. Select Add.
8. Finish creating the app. You don't need the other options.
9. Activate the application.

Request a Token

To access the REST APIs, you also need to request a token. This token can't be shared, but you can configure when the token expires. This period depends on your organization's requirements and whether you're comfortable allowing a token to be used for a certain period.

1. From OCI's navigation menu, go to Identity & Security > Domains > <your OCI identity domain> > Integrated applications.
2. Browse to the confidential application you created, then select it.
3. Select OAuth Configuration
   1. Locate Client ID and Client secret.

      We recommend routinely regenerating the Client Secret for the confidential application you created because this allows for READ and ADMIN access to the APIs for your SFA environments.

      We also recommend restricting who has access to the Client ID and Client Secret within OCI IAM.

   2. Encode the values to Base64.
      Here's an example in Windows Powershell:

      $stringToEncode = "id:secret"
       $bytes = [System.Text.Encoding]::UTF8.GetBytes($stringToEncode)
       $encodedString = [System.Convert]::ToBase64String($bytes)
       $encodedString

      Make sure to note the value for use in token requests.
   3. In your preferred software client, make an API call to request and retrieve a token.

      When you need to make a READ (GET) call to the MPG API, you would request a token with only the /mpg.readonly scope for the SFA environment you need to interact with.

      Example scope:

      curl -H "Authorization: Basic <base64 string created from client id and client secret" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" --request POST https://<identity domain url>/oauth2/v1/token-d "grant_type=client_credentials&scope=https://sfp.ocs.oc-test.com/oracletest/mpg.readonly"

      When you need to make an ADMIN (POST) call to the VUG API you would request a token with only the /vug.admin scope for the SFA environment you need to interact with.

      Example scope:

      curl -H "Authorization: Basic <base64 string created from client id and client secret" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" --request POST https://<identity domain url>/oauth2/v1/token -d "grant_type=client_credentials&scope=https://sfp.ocs.oc-test.com/oracletest/vug.admin"

   4. To make an API call to interact with an SFA environment, use the token retrieved in the previous step.

      curl -kv -X POST -H "Authorization: Bearer <token value>" -F "file=@demotest.dat"
      https://sfp.ocs.oc-test.com/oracletest/vug/v2/in/publish