• Prerequisites for All Grants
• Prerequisites for Resource Owner Password Credentials
• Prerequisites for OAuth Client Credentials
• Prerequisites for JWT Assertions

Prerequisites for All Grants

Perform the following tasks for each grant type you use.

• Obtain the Oracle Identity Cloud Service URL.
  1. Go to the URL for your Oracle Utilities application. You are redirected to a URL such as:

     https://idcs-c2881.identity.myhost.example.com/ui/v1/signin

  2. Replace /signin with /adminconsole to access Oracle Identity Cloud Service.
     For example:

     https://idcs-c2881.identity.myhost.example.com/ui/v1/adminconsole

     You'll be prompted to sign in again to the Oracle Identity Cloud Service Console.

  3. Log in to the Oracle Identity Cloud Service Console with your identity domain administrator credentials.
• Check the Oracle Utilities application in Oracle Identity Cloud Service.
  When an Oracle Utilities application instance is provisioned, an Oracle Identity Cloud Service application is created for that application instance. The application name is composed as follows:

  product-domaintenantsuffixsequential_number

  For example:

  CCS-PRODC12345CMETERDATA0

  CCS-PRODC12345FIELDSERVICE1

  1. To request creation of a new OAuth client application, create a cloud operations service request and provide the following information:
     • Environment(s) where the OAuth client application is needed (for example, PROD, TEST01, or DEV).
     • Client name suffix: Use a distinct name that may suggest the functional purpose of the integration.
     • Provide a meaningful description of the integration point.
     • Client type (trusted or confidential) and client certificate: The integration requirements may call for a trusted client and the external application may also supply its own certificate. Otherwise, Oracle Identity Cloud Service creates a trusted client with its internal native certificate.
     • OAuth flow for your intended integration: Client credentials is currently supported.
     • Scope: You can define the OAuth client application with access to either REST or SOAP APIs or both REST and SOAP APIs.
  The Oracle Utilities Cloud Operations team creates the OAuth client using the input provided in the service request.

  1. Log in to Oracle Identity Cloud Service to get your application.
  2. Go to Oracle Cloud Services and find the application with the above name to access the application.

Prerequisites for Resource Owner Password Credentials

Perform the following tasks.

• Validate the Oracle Integration application and user roles:
  1. Go to Configuration, and then Client Configuration of the Oracle Identity Cloud Service application.
  2. Verify that Resource Owner and Refresh Token for Allowed Grant Types are enabled.
  3. Go to Configuration, and then Resources of the Oracle Identity Cloud Service application.
  4. Verify that the Is Refresh Token Allowed option is enabled.

     
     
     

     The scope with access to either REST or SOAP APIs or both REST and SOAP APIs is provided.

     
     
     

  5. Add the appropriate user(s) to the various Oracle Application roles. For standard/production configurations, use the ServiceUser role. (See Oracle Integration Service Roles in Provisioning and Administering Oracle Integration 3.)
  6. To assign the user, go to the Application Roles section of the application and assign the user for AppWebServices.

     
     
     

• Configure the client application:
  1. In the Oracle Identity Cloud Service Console, go to the Applications section to create a new application that allows you to invoke an Oracle Utilities application with an OAuth Utilities Connection. Add this application as a confidential application.
  2. Click Add.
  3. Select Confidential Application.

     
     
     Description of the illustration oauth_grant6.png
     

  4. Complete the Details page, and go to the Client page.

     
     
     Description of the illustration oauth_grant7.png
     

  5. On the Client page, select Configure this application as a client now and add the following.
     1. Select Resource Owner and Refresh Token for Allowed Grant Types.
     2. Select Specific in the Authorized Resources section.

        
        
        Description of the illustration ropc2.png
        

     3. Click Add Scope under the Resources section.

        
        
        

     4. Find the Oracle Utilities application.

        
        
        

     5. Add the scope containing access to either REST (/rest/*) or SOAP(/soap/*) APIs or both REST and SOAP APIs (/*), and click >.

        
        
        

     6. Save your changes.
  6. Click through the remaining wizard pages without making changes and save the application.
  7. Activate the application for use.
• Validate the client application:
  1. To fetch the access client, make a request to Oracle Identity Cloud Service with the user name and password in the payload.

     Note:

     Add offline_access in the scope to fetch the request refresh token as part of the response.

     ##Syntax
     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>.identity.oraclecloud.com/oauth2/v1/token -d 'grant_type=password&username=<user-name>&password=<password>&scope=<App_Scope>%20offline_access'
      
     ###where
     #### <base64-clientid-secret> - Base 64 encode clientId:ClientSecret
     #### <username> - user for token needs to be issued (must be in serviceuser role).
     #### <password> - password for above user
     #### <app_scope> - Scope added while creating application in client configuration section
     ##Example
     curl -i -H 'Authorization: Basic OGQyM...ZDA0Mjcz' -H 'Content-Type: application/x-www-form-urlencoded;charset=UTF-8' --request POST https://<idcs_host>/oauth2/v1/token -d 'grant_type=password&username=sampleUser&password=SamplePassword&scope=https://<Resource_APP_Audience>/rest/*%20offline_access'
     

  2. Capture the access_token and refresh_token from the response.

     {
         "access_token": "eyJ4NXQjG...dfsdfsFgets2ed",
         "token_type": "Bearer",
         "expires_in": 3600,
         "refresh_token": "AQAgY2MzNjVlOTVhOTRh...vM5S0MkrFSpzc="
     }
     

  3. Use the access_token in the authorization header to invoke the Oracle Utilities application endpoint.

     curl --location --request GET 'https://<Utilities_Application_API_ENDPOINT>' \
     --header 'Authorization: Bearer eyJ4NXQjG...dfsdfsFgets2ed'

  4. To update the access token, use the refresh token and make a request to Oracle Identity Cloud Service.
  5. Capture the access_token and refresh_token from the response for further use.

     curl -i -H 'Authorization: Basic <base64-clientid-secret>' -H 'Content-Type: application/x-www-form-urlencoded;charset=UTF-8' --request POST https://<IDCS-Service-Instance>.identity.oraclecloud.com/oauth2/v1/token  -d 'grant_type=refresh_token&refresh_token=<refresh_token>'
      
     ##Example
     curl -i -H 'Authorization: Basic OGQyM...ZDA0Mjcz' -H 'Content-Type: application/x-www-form-urlencoded;charset=UTF-8' --request POST https://<IDCS-Service-Instance>.identity.oraclecloud.com/oauth2/v1/token  -d 'grant_type=refresh_token&refresh_token=AQAgY2MzNjVlOTVhOTRh...vM5S0MkrFSpzc='
     

Prerequisites for OAuth Client Credentials

Oracle Identity Cloud Service (IDCS) configuration requirements for OAuth Client Credential inbound and outbound requests in integrations using the Oracle Utilities Adapter are described below.

• Inbound to Oracle Integration:

  For IDCS configurations to enable OAuth Client Credentials in the inbound direction to Oracle Integration, see Prerequisites for Client Credentials in Using the REST Adapter with Oracle Integration 3.

• Outbound from Oracle Integration to Oracle Utilities Applications:

  Perform the following tasks.

  • Validate the Oracle Utilities application and user roles:
    1. Go to Configuration, and then Client Configuration of the Oracle Identity Cloud Service application.
    2. Verify that Client Credentials for Allowed Grant Types is enabled.
    3. Go to Configuration, and then Resources of the Oracle Identity Cloud Service application. The scope with access to either REST or SOAP APIs or both REST and SOAP APIs is provided.

       
       
       

    4. Add the appropriate user(s) to the various Oracle Utilities application roles. For standard/production configurations, use the ServiceUser role. (See Oracle Integration Service Roles in Provisioning and Administering Oracle Integration 3.)
    5. To assign the user, go to the Application Roles section of the application under AppWebServices.

       
       
       

  • Configure the client application:
    1. In the Oracle Identity Cloud Service Console, go to the Applications section to create a new application that allows you to invoke an Oracle Utilities application API with an OAuth Utilities Connection. The application is added as a confidential application.
    2. Complete the Details section, and go to the Client section.
    3. On the Client page, select Configure this application as a client now, and complete the following:
       1. Select Client Credentials from the Allowed Grant Types list.
       2. Select Specific in the Authorized Resources area of the Token Issuance Policy section.
       3. Click Add Scope under the Resources section.
       4. Find the Oracle Utilities application.

          
          
          

       5. Add the scope containing access to either REST or SOAP APIs or both REST and SOAP APIs, and click >.

          
          
          

       6. Save your changes.
    4. Click through the remaining wizard pages without making changes and save the application.
    5. Activate the application for use.
    The next step is to create an application user in the appropriate Oracle Utilities Cloud Service (such as Oracle Utilities Meter Solution Cloud Service). Access the appropriate Oracle Utilities Cloud Service application, and navigate to the User portal.

    1. Create a new user corresponding to the OAuth client created above:
       1. Search for Add User.
       2. Enter the OAuth client ID as the user’s login ID.
       3. Provide values of your choice for the mandatory fields, such as USER, LAST NAME, and FIRST NAME.
       4. Select USER ENBLE as Enable.
       5. Assign User Groups that provide the integration with access to the appropriate functionality (for example, the ALL_SERVICES user group providing a future expiration date).
       6. Assign To Do Roles (for example, the F1_DFLT system default role) and appropriate Access Security (for example, System Default) with an expiration date to the created user.
       7. Save the user.

       The OAuth client credentials are now ready to use.

  • Validate the client application.
    1. Fetch the access client to make a request to Oracle Identity Cloud Service with the client ID and client secret of the client in the payload.

       ##Syntax
       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>.identity.oraclecloud.com/oauth2/v1/token -d 'grant_type=client_credentials&scope=<App_Scope>'
       
       ###where
       #### <base64-clientid-secret> - Base 64 encode clientId:ClientSecret
       #### <app_scope> - Scope added while creating application in client configuration section
       ##Example
       curl -i -H 'Authorization: Basic OGQyM...ZDA0Mjcz' -H 'Content-Type: application/x-www-form-urlencoded;charset=UTF-8' --request POST https://<idcs_host>/oauth2/v1/token -d 'grant_type=client_credentials&scope=https://<Resource_APP_Audience>/rest/*'

    2. Capture the access_token from the response.

       {
           "access_token": "eyJ4NXQjG...dfsdfsFgets2ed",
           "token_type": "Bearer",
           "expires_in": 3600
       }

    3. Use the access_token in the authorization header to invoke the Oracle Utilities Application APIs.

       curl --location --request GET 'https://<Utilities_Application_API_ENDPOINT>' \
       --header 'Authorization: Bearer eyJ4NXQjG...dfsdfsFgets2ed'

    4. To update the access token when it is expired, make the same request to Oracle Identity Cloud Service.

Prerequisites for JWT Assertions

• Generate the key

  You must first generate the key to import when you configure the client application for the JWT user assertion.

  1. Generate the self-signed key pair.

     keytool -genkey -keyalg RSA -alias <your_alias> -keystore <keystore_file> -storepass <password> -validity 365 -keysize 2048
      
     ##example
     keytool -genkey -keyalg RSA -alias assert -keystore sampleKeystore.jks -storepass samplePasswd -validity 365 -keysize 2048

  2. Export the public key for signing the JWT assertion.

     keytool -exportcert -alias <your_alias> -file <filename> -keystore <keystore_file> -storepass <password>
       
     ##example
     keytool -exportcert -alias assert -file assert.cer -keystore sampleKeystore.jks -storepass samplePasswd
      
     ## This should show a success message e.g. Certificate stored in file <assert.cer>

  3. Convert the keystore to P12 format.

     keytool -importkeystore -srckeystore <filename> -srcstorepass <password> -srckeypass <password> -srcalias <your_alias> -destalias <your_alias> -destkeystore <destFileName> -deststoretype PKCS12 -deststorepass <password> -destkeypass <password>
      
     ##example
     keytool -importkeystore -srckeystore sampleKeystore.jks -srcstorepass samplePasswd -srckeypass samplePasswd -srcalias assert -destalias assert -destkeystore assert.p12 -deststoretype PKCS12 -deststorepass samplePasswd -destkeypass samplePasswd
      
     ## This should show a success message e.g. Importing keystore sampleKeystore.jks to assert.p12...

  4. Export the private key from the P12 keystore.

     openssl pkcs12 -in <destFileName> -nodes -nocerts -out <pem_file>
       
     ##example
     openssl pkcs12 -in assert.p12 -nodes -nocerts -out private_key.pem
       
     ## This should show a success message: MAC verified OK

• Configure the client application
  In the Oracle Cloud Infrastructure Console, go to the Integrated applications section to create a new application that allows you to invoke an Oracle Utilities application API with an JWT Utilities connection.

  1. Click Add application.
  2. Select Confidential Application, and click Launch workflow.
  3. Enter a name in the Application details section. The remaining fields on this page are optional and can be ignored.
  4. Click Next.
  5. In the Client configuration section, select Configure this application as a client now, and complete the following:
     1. For JWT assertions, select JWT assertion and Refresh token in the Allowed grant types section.
     2. Leave the Redirect URL, Post-logout redirect URL, and Logout URL fields blank.
     3. In the Client type section, select Trusted.
     4. Upload the public certificate created in the Generate the key section.
     5. Provide the alias name. Remember this alias name because it is used when creating assertions. This action adds the certificate as a trusted partner.
     6. Bypass several fields and scroll down to the Token issuance policy section.
     7. Select Specific in the Authorized resources section.
     8. Click the Add Resources check box.
     9. Click Add scope.
     10. Use the search facility to find the Oracle Utilities application.

         
         
         

     11. Add the scope containing access to either REST or SOAP APIs or both REST and SOAP APIs. The scopes are displayed in the Resources section.
     12. Click through the remaining wizard pages without making changes and save the application.
  6. Activate the application for use.
  7. In the General Information section, note the client ID and client secret values. These values are required for the third-party application that is communicating with the identity domain.
• Add a certificate as a trusted partner
  In addition to importing the signing certificate into the client application, you are also required to include the certificate as a trusted partner certificate.

  1. In the navigation pane, click Settings.

     
     
     

  2. Click Trusted partner certificates.
  3. Click Import certificate to upload the public certificate created in the Generate the key section.
• Generate the JWT user assertion

  Generate the JWT user assertion using the generated private key and simple Java code.

  Note:

  You can use the https://github.com/jwtk/jjwt library to generate the user assertion. There are many libraries listed at https://jwt.io/ for multiple technologies.

  Sample:
  header:
  {
  "alg": "RS256",
  "typ": "JWT",
  "kid": "assert"
  }
   
  payload:
  {
  "sub": "utilitiesApplicationUser",
  "jti": "8c7df446-bfae-40be-be09-0ab55c655436",
  "iat": 1589889699,
  "exp": 1589909699,
  "iss": "d702f5b31ee645ecbc49d05983aaee54",
  "aud": "https://identity.oraclecloud.com/"
  }

  Where:

  • sub specifies the user name for whom user assertion is generated.
  • jti is a unique identifier.
  • iat is issued (epoch seconds).
  • exp is the token expiry (epoch seconds).
  • iss is the client ID aud must include the identity domain audience https://identity.oracle.com/. The signing algorithm must be RS256.
  • kid specifies the key to use to verify the signature. Therefore, it must match with the uploaded certificate alias.
• Generate the JWT client assertion

  Similar to JWT user assertion, you can generate the client assertion using the generated private key and simple Java code.

  Note:

  You can use the https://github.com/jwtk/jjwt library to generate the user assertion. There are many libraries listed at https://jwt.io/ for multiple technologies.

  Sample:
  header:
  {
  "alg": "RS256",
  "typ": "JWT",
  "kid": "assert"
  }
   
  payload:
  {
  "sub": "d702f5b31ee645ecbc49d05983aaee54",
  "jti": "8c7df446-bfae-40be-be09-0ab55c655436",
  "iat": 1589889699,
  "exp": 1589909699,
  "iss": "d702f5b31ee645ecbc49d05983aaee54",
  "aud": "https://identity.oraclecloud.com/"
  }

  Where:

  • sub specifies the client ID of the client application.
  • jti is a unique identifier.
  • iat is issued (epoch seconds).
  • exp is the token expiry (epoch seconds).
  • iss is the client ID aud must include the identity domain audience https://identity.oracle.com/. The signing algorithm must be RS256.
  • kid specifies the key to use to verify the signature. Therefore, it must match with the uploaded certificate alias.

  Note:

  In user assertions, you add sub as the user name. In client assertions, you add the client ID as sub.
• Validate the client application
  1. Once you generate the JWT user assertion, generate the access token as follows.

     ##Syntax
     curl -i -H 'Authorization: Basic <base64Encoded clientid:secret>' -H 'Content-Type: application/x-www-form-urlencoded;charset=UTF-8' --request POST https://<Identity_Domain_Service_Instance>.identity.oraclecloud.com/oauth2/v1/token -d 'grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer&assertion=<user assertion>&scope=<app_scope>'
       
     ###where
     #### grant type - urn:ietf:params:oauth:grant-type:jwt-bearer
     #### <base64-clientid-secret> - Base 64 encode clientId:ClientSecret
     #### <user assertion> - User assertion generated
     #### <app scope> - Scope added while creating application in client configuration section

  2. Capture the access_token from the response.

     { "access_token": "eyJ4NXQjG...dfsdfsFgets2ed", "token_type": "Bearer", "expires_in": 3600 }
     

  3. Use the access_token in the authorization header to invoke the Oracle Utilities Application APIs.

     curl --location --request GET 'https://<Utilities_Application_API_ENDPOINT>' \ --header 'Authorization: Bearer eyJ4NXQjG...dfsdfsFgets2ed'

  4. To update the access token when it expires, make the same request to Oracle Identity Cloud Service.
• Add new security policies
  • OAuth Client Credentials using JWT Client Assertion
  • OAuth using JWT User Assertion