Prerequisites for Creating a Connection
You must satisfy the following prerequisites to create a connection with the REST Adapter:
OAuth Security Policies Use
If you are using one of the OAuth security policies, you must already have registered your client application to complete the necessary fields on the Connections page. The Basic Authentication and No Security Policy security policies are exempted.
Before a client application can request access to resources on a resource server, the client application must first register with the authorization server associated with the resource server.
The registration is typically a one-time task. Once registered, the registration remains valid, unless the client application registration is revoked.
At registration time, the client application is assigned a client ID and a client secret (password) by the authorization server. The client ID and secret are unique to the client application on that authorization server. If a client application registers with multiple authorization servers (for example, Facebook, Twitter, and Google), each authorization server issues its own unique client ID to the client application.
@ref: http://tutorials.jenkov.com/oauth2/authorization.html
For OAuth configuration, read the provider documentation carefully and provide the relevant values.
SSL Endpoints Use
For SSL endpoints, obtain and upload a server certificate. See Upload a Certificate to Connect with External Services.
Amazon Web Services (AWS) REST API Consumption
Before you can create a connection that consumes an Amazon Web Services (AWS) REST API, you must obtain the necessary access and secret keys. See Understanding and Getting Your Security Credentials.
OCI Signature Version 1 Security Policy Use
-
Create an API signing key. You then specify the signing key in Oracle Cloud Infrastructure.
- Create the signing key in
Oracle Cloud
Infrastructure using
openssl
. The key must be in RSA (PKCS1) format. During creation, you also create a pass phase to protect the key. Both the key and pass phrase are required when configuring the OCI Signature Version 1 security policy on the Connections page. See Creating a Key Pair.If the key downloaded from the Oracle Cloud Infrastructure Console is in PKCS8 format, it must be converted to RSA (PKCS1) format. See Convert a Private Key from PKCS8 to RSA (PKCS1) Format for the OCI Signature Version 1 Security Policy.
Existing connections already using the OCI Signature Version 1 security policy do not need to be upgraded because they continue to work.
- Sign in to the Oracle Cloud Infrastructure Console.
- Open the navigation menu and click
Identity & Security. Under
Identity, click Users.
A list of users in your tenancy is displayed.
- On the Users page, click the link of the user name to use.
- Scroll down to the API Keys section, and click Add API Key.
- In the Add API Key dialog, enter the contents of the public key you created, and click Add.
- Copy the finger print value
generated by Oracle Cloud
Infrastructure. You need this value when configuring
the OCI Signature Version 1 security policy on the Connections page.
- Create the signing key in
Oracle Cloud
Infrastructure using
- Obtain the tenancy OCID and user
OCID details in the Oracle Cloud
Infrastructure Console. When you sign up for Oracle Cloud
Infrastructure, Oracle creates a tenancy for your company,
which is a secure and isolated partition within
Oracle Cloud
Infrastructure where you can create, organize, and administer
your cloud resources.
- Sign in to the Oracle Cloud Infrastructure Console.
- Open the navigation menu and click Governance & Administration. Under Account Management, click Tenancy Details.
- In the Tenancy information section, click Show to display the OCID tenancy value.
- Copy the value. You need this value when configuring the OCI Signature Version 1 security policy on the Connections page.
- In the header, click the
Profile icon and select User
Settings.
Note:
You can also open the navigation menu and click Identity & Security, then under Identity, click Users to access the user profile. - Click Show to display the OCID user value.
- Copy the value. You need this value when configuring the OCI Signature Version 1 security policy on the Connections page.
RPST and OCI Service Invocation Security Policy Use
To use RPST and the OCI Service Invocation security policy, you must satisfy the following prerequisites.
- Ensure that your cloud tenancy uses identity domains. The OCI Service
Invocation security policy that you select on the Connections page does not work in
cloud tenancies that are not enabled for identity domains. If you are unsure, ask your
administrator for details. Your cloud tenancy does not use identity domains if you
observe either of the following:
- In the upper right corner, you select your
Profiles icon and don't see an entry for identity domain.
- From the menu, you select Identity & Security and don't see
Domains under the Identity section.
- In the upper right corner, you select your
Profiles icon and don't see an entry for identity domain.
- Create the required dynamic group and assign a policy to that group to allow
your Oracle Integration instance to access Oracle Cloud
Infrastructure services, such as Oracle Cloud
Infrastructure Functions, Oracle Cloud
Infrastructure Object Storage, Oracle Cloud
Infrastructure Vision, and more. The policy defines the permissions for the dynamic
group and determines which operations the dynamic group can perform on Oracle Cloud
Infrastructure services.
- Log in to the Oracle Cloud Infrastructure Console.
- Obtain the client ID of the OAuth application for the Oracle Integration instance.
- In the upper right corner, select Profile,
then click the identity domain.
- In the left navigation pane, click Oracle Cloud
Services.
The Oracle Cloud Services page for your domain appears.
- In the Name column, click your service instance.
- Scroll down to the General Information section and copy the client ID value to use to create your dynamic group.
- In the upper right corner, select Profile,
then click the identity domain.
- Scroll to the breadcrumbs at the top and click Default
domain.
- In the left navigation pane, click Dynamic groups.
- Click Create Dynamic Group.
- Enter the following details:
- In the Name and Description fields, enter values. These fields are required.
- In the Matching Rules section, enter the
required rule. The resource ID you specify must match the client ID of the OAuth
application of your Oracle Integration instance. Ensure that you enclose the
value in single quotes. For
example:
resource.id = 'client_ID'
- Scroll to the breadcrumbs at the top and click
Identity.
- In the left navigation pane, click Policies.
- Click Create Policy.
- Select the compartment in which to create the policy.
- Enter the following details:
- In the Name and Description fields, enter values. These fields are required.
- In the Policy Builder section, build the
required policy for the dynamic group. For this example, the policy is specified
to manage all Oracle Cloud
Infrastructure
service resources in the compartment in which your Oracle Integration instance
is
located.
allow dynamic-group dynamic_group to manage all-resources in compartment compartment_name
Where:dynamic_group
: Is the dynamic group name you specified in Step 5.compartment_name
: Is the compartment in which your Oracle Integration instance is located.
This enables the Oracle Integration instance associated with the dynamic group to call any Oracle Cloud Infrastructure services in this particular compartment. The RPST token is only valid for resources to which the dynamic group has been granted access using this policy.
JWT Assertions Outbound Use
- Manually create a signing key for upload on the Certificates page. See
Upload a Certificate to Connect with External Services.
The service provider typically provides instructions on how to generate the signing keys and the format. For an example, see Required Keys and OCIDs.
- Create the JWT header and JWT payload JSON files. You upload both files on
the Connections page when configuring the REST Adapter to support JWT assertions. For example:
JWT Header JSON File Example JWT Payload JSON File Example { "alg": "RS256", "kid": "cecsassertion" }
Where:
alg
: The algorithm to use.kid
: A key identifier that is uniquely-generated and associated with the uploaded signing key.
{ "iss": "3485233d3fed4fbcb38338e536d399fc", "sub": "3485233d3fed4fbcb38338e536d399fc", "aud": "https://identity.oraclecloud.com/", "exp": 1672564057" }
Where:
- JWT issuer (
iss
): A unique identifier for the entity that issued the assertion. This is typically the entity that holds the key material used to sign or integrity-protect the assertion. Examples of issuers are OAuth clients (when assertions are self-issued) and third-party security token services. If the assertion is self-issued, the issuer value is the client identifier (client_id
). If the assertion was issued by a security token service (STS), the issuer must identify the STS in a manner recognized by the authorization server. The assertion must contain an issuer. - JWT subject (
sub
): The subject typically identifies an authorized accessor for which the access token is being requested (that is, the resource owner or an authorized delegate). In some cases, this may be a pseudo anonymous identifier or other value denoting an anonymous user. When the client is acting on behalf of itself, the subject must be the value of the client'sclient_id
. The assertion must contain a subject. - JWT audience (
aud
): A value that identifies the party or parties to process the assertion. The assertion must contain an audience that identifies the authorization server as the intended audience. The authorization server must reject any assertion that does not contain its own identity as the intended audience (in this case, for Oracle Identity Cloud Service,https://identity.oraclecloud.com/
). - Expires at (
exp
): The time at which the assertion expires. While the serialization may differ by assertion format, the time must be expressed in UTC format with no time zone component. The assertion must contain an expires-at entity that limits the window during which the assertion can be used. The authorization server must reject expired assertions (subject to allowable clock skew between systems). The authorization server may reject assertions with an expires-at attribute value that is unreasonably far in the future.
Note:
Carefully review the JWT documentation of your service provider and ensure that you follow all guidelines required by the service provider to correctly create the header and payload files. The content of each file varies from one service provider to another. The REST Adapter supports the different implementations of JWT provided by the following service providers:- NHS (See Application-restricted RESTful APIs - signed JWT authentication and Step 4: Register your public key)
- FHIR (See Using OAuth 2.0 and Standalone Launch)
- DocuSign (See How to get an access token with JWT Grant)
- Adobe eSign (See JWT (Service Account) Authentication)
- Microsoft (See Microsoft identity platform and OAuth 2.0 On-Behalf-Of flow)
- Okta (See Implement OAuth for Okta with a service app and JWT with private key)