OAuth JWT User Assertion

Overview

An application may require users to authenticate using JWT user assertions, before it returns access tokens that allows access to its data/APIs. The OAuth JWT User Assertion security policy obtains an authorization to an application's API through a trusted relationship between the client (Oracle Integration) and authentication server, which involves an exchange of certificates.

When you add this security policy to your adapter, your adapter's user must create a client application on the corresponding authentication server and obtain a set of client credentials enabled with the correct grant type, that is, JWT assertion. During this process, the user may also need to exchange certificates to establish trust, both in the authentication server and Oracle Integration.

Subsequently, the adapter user can leverage the adapter interface to formulate and send a JWT user assertion from Oracle Integration to the authentication server, specifying the required privileges for a particular user (without the user having to explicitly provide consent, which is typically the case in the OAuth Authorization Code security policy). In exchange, the authentication server provides an access token that models the privileges for the specified user.

To add the OAuth JWT User Assertion policy to your adapter definition document, use the available authentication scheme template. See Implement a New Connection Definition.

Note:

If you choose to use this security policy in your adapter, ensure that you create a client application on the required authentication server, formulate the JWT assertion for the server, and thoroughly test the assertion on tools like jwt.io, Postman, or other browser plugins.

Security Properties

This section lists the security properties available in the OAuth JWT User Assertion authentication scheme template.

The user assertion is formulated using the values that are entered against these properties in the adapter interface by the adapter user. As an adapter developer, you can make the formulation of the assertion payload easier for your adapter's users by entering default values for the authentication server (corresponding to your adapter). This way, the adapter's users do not have to enter values for some properties, such as audience, kid, jti, algorithm, expiration duration, scope, and access token URL.

Typically, users only need to create a client application on the required authentication server and obtain values for client_id, client_secret, and the alias of the certificate uploaded.

If you need to include one or more custom properties to formulate the assertion, you can include them in the connectionProperties section. See Connection Properties and Sample Code.

Note:

To represent a particular user in an assertion, you require a property by the authentication server that represents the user. Typically, this is an Email ID or User ID.

Name	Display Name	Short Description	Description	Data Type	Required
`oauth.access.token.uri`	`Access Token URI`	`for example: https://www.google.com/oauth/token`	The URI to which a request should be sent for obtaining an access token.	String	Yes
`jwt_header`	`JWT Header`	`for example:{\"alg\":\"RSA256\"}`	The JWT header contains metadata about a JWT, including the key identifier, the algorithm used to sign in, and other information.	String (JSON String)	Yes
`jwt_payload`	`JWT Payload`	`for example: {"iss":"as12123", "sub":"nsjsas12"}`	The JWT payload contains statements about the entity (for example, the user) and additional entity attributes, which are called claims.	String (JSON String)	Yes
`jwt_signing_key_alias_name`	`JWT Private Key Alias`	`for example: MSSignkey`	The signing-key identifier received after uploading the private key in the Oracle Integration certificates.	String	Yes
`scope`	`Scope`	`for example: read,write.`	The permissions your application is requesting on behalf of the user.	String	No
`jwtAccessTokenRequest`	`Customized Access Token Request`	`for example: -X POST -H 'Content-Type: application/x-www-form-urlencoded' -d 'grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion=sjkdndaiwd&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer &client_assertion=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIs&scope=read' https://idcs-fb8d65590fb3413.identity.oraclecloud.com/oauth2/v1/token`	The Access Token Request whose value is formed using a URI syntax of the HTTP request used to fetch the access token. The URI syntax resembles cURL.	String	No

Sample Code: OAuth JWT User Assertion (Google PubSub API)

In this example, Google's assertion requires custom properties (Service Account). Note the formulation of the header and the body using the JQ expression in the security policy definition. Some of the properties have been defaulted by the policy in the JQ expression itself.

"connectionProperties": [
  {
    "name": "projectID",
    "type": "STRING",
    "displayName": "Project ID",
    "description": "Google Cloud Project ID",
    "shortDescription": "Example: xxx-xxx-657890",
    "required": true,
    "hidden": false,
    "tokenized": true,
    "scope": [
      "ACTION",
      "TRIGGER"
    ]
  },
  {
    "name": "serviceAccount",
    "type": "STRING",
    "displayName": "Service Account",
    "description": "Google Cloud Service Account",
    "shortDescription": "Example: name@<projectId>.iam.gserviceaccount.com",
    "required": true,
    "hidden": false,
    "tokenized": true,
    "scope": [
      "TRIGGER",
      "ACTION"
    ]
  },
  {
    "name": "hostName",
    "type": "STRING",
    "displayName": "HostName",
    "description": "Environment hostname with which user needs to connect",
    "shortDescription": "Example: pubsub.googleapis.com",
    "required": true,
    "hidden": true,
    "scope": [
      "ACTION",
      "TRIGGER"
    ],
    "default": "pubsub.googleapis.com"
  }
],
"securityPolicies": [
  {
    "type": "managed",
    "policy": "JWT_USER_ASSERTION_FOR_OAUTH",
    "description": "JWT User Assertion for OAuth Policy",
    "displayName": "JWT User Assertion for OAuth",
    "scope": "ACTION",
    "securityProperties": [
      {
        "name": "oauth.access.token.uri",
        "displayName": "Access token uri",
        "description": "Access token uri",
        "shortDescription": "https://oauth2.googleapis.com/token",
        "hidden": true,
        "required": true,
        "default": "https://oauth2.googleapis.com/token"
      },
      {
        "name": "jwt_header",
        "displayName": "JWT header",
        "description": "JWT header",
        "shortDescription": "{\"alg\":\"RSA256\"}",
        "hidden": true,
        "required": true,
        "default": "${{\"alg\" : \"RS256\",\"typ\": \"JWT\"}}"
      },
      {
        "name": "jwt_payload",
        "displayName": "JWT Payload",
        "description": "JWT Payload",
        "shortDescription": "{\"iss\":\"123as12\", \"sub\":\"as12123\"}",
        "hidden": true,
        "required": true,
        "default": "${{\"iss\": .connectionProperties.serviceAccount,\"sub\": .connectionProperties.serviceAccount,\"aud\": \"https://oauth2.googleapis.com/token\",\"exp\": \"\",\"iat\": \"\",\"scope\": \"https://www.googleapis.com/auth/pubsub\"}}"
      },
      {
        "name": "jwt_signing_key_alias_name",
        "displayName": "JWT Private Key Alias",
        "description": "Jwt Signing key. This is the key name of certificate uploaded in the OIC certificates page.",
        "shortDescription": "Example: MSSignkey",
        "hidden": false,
        "required": true,
        "default": ""
      },
      {
        "name": "scope",
        "displayName": "Scope",
        "description": "Scope",
        "shortDescription": "Scope",
        "hidden": true,
        "required": false,
        "default": ""
      },
      {
        "name": "jwtAccessTokenRequest",
        "displayName": "Access Token Request",
        "description": "Access Token Request",
        "shortDescription": "Example: AC1234",
        "hidden": true,
        "required": false,
        "default": ""
      }
    ]
  }
]