OAuth2 Authentication Support

OAuth2 is an authorization protocol that provides a secure way to access protected data from an application. The PIP Service can be configured to use OAuth 2.0 to securely access API based data sources, such as SCIM, Azure AD, OData, and REST.

To support OAuth authentication, pre-configuration is required. Individual websites typically provide developer-facing REST-based APIs for accessing their content and ways to register custom applications on users' behalf. The first step is to register the custom application on the website and collect consumer/API keys and secrets.

OAuth Configuration For PAA

After you get your service client credentials, you need to set them up in the PIP Auth configuration. Currently, the Auth configuration for external services is done in an auth XML file containing general setup that you don’t need to change and security policy sections that need to be added for each service using OAuth.

Environment Variables

Before configuring the sample code below, note that any module-option name can be set using an environment variable by enclosing it in ${env:<module-option>}. The variable name can be any valid string.

For example: <module-option name=“client-secret”> ${env: CLIENT_SECRET} </module-option>

Sample auth-config.xml file:

<?xml version='1.0'?>
<policy xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="urn:jboss:security-config:5.0" xmlns="urn:jboss:security-config:5.0" xmlns:jbxb="urn:jboss:security-config:5.0">
  <application-policy name="teiid-security-file">
    <authentication>
      <login-module code="org.jboss.security.auth.spi.UsersRolesLoginModule" flag="required">
        <!-- https://access.redhat.com/documentation/en-us/jboss_enterprise_application_platform/5/html/security_guide/ch12#Using_JBoss_Login_Modules-Password_Hashing -->
        <module-option name="usersProperties">users.properties</module-option>
        <module-option name="rolesProperties">roles.properties</module-option>
        <module-option name="unauthenticatedIdentity">nobody</module-option>
        <module-option name="hashAlgorithm">MD5</module-option>
        <module-option name="hashEncoding">base64</module-option>
      </login-module>
    </authentication>
  </application-policy>

  <application-policy name="oauth2-azure-ad-staging">
    <authentication>
      <login-module code="com.plainid.pip.auth.oauth.clientcredential.OAuth20ClientCredentialLoginModule" flag="required">
        <module-option name="scope">https://graph.microsoft.com/.default</module-option>
        <module-option name="access-token-uri">https://login.microsoftonline.com/********-****-****-****-************/oauth2/v2.0/token</module-option>
        <module-option name="client-id">client-id</module-option>
        <module-option name=“client-secret”>client-secret</module-option>
      </login-module>
    </authentication>
  </application-policy>

  <!-- Add application credentials. Details below -->
</policy>

For each service using OAuth, you need to add an <application policy> section with the relevant service credentials.

Sample <application-policy> Settings for Azure AD OAuth Configuration

<application-policy name="oauth2-azure-ad-staging">
  <authentication>
    <login-module code="com.plainid.pip.auth.oauth.clientcredential.OAuth20ClientCredentialLoginModule" flag="required">
      <module-option name="scope">https://graph.microsoft.com/.default</module-option>
      <module-option name="access-token-uri">https://login.microsoftonline.com/********-****-****-****-************/oauth2/v2.0/token</module-option>
        <module-option name="client-id">${env:AAD_CLIENT_ID}</module-option>
        <module-option name=“client-secret”>${env:AAD_CLIENT_SECRET}</module-option>
    </login-module>
  </authentication>
</application-policy>

The application-policy name (in the above example is oauth2-azure-ad-staging) is used to set the Security Domain field in the PIP Settings screen when configuring the Data Source.

Module Options Properties Table

The OAuth jar (pip-auth-extensions-#.jar) and auth-config.xml configuration file should be set in all PAAs.

Containerized PAA

In Containerized PAA, the auth-config.xml file is located at app/conf/auth-config.xml.

PlainID PAA Helm Chart includes two configuration files:

• values.yaml - Stores all potential setting parameters, and the default values for the PAA.
• custom-values.yaml - Used to set only the parameters/settings that are modified. As a best practice, we recommend using this file for setting the relevant parameter values by adding configuration values from the values.yaml to the values-custom.yaml file.

You can use the above custom-values.yaml mechanism to inject your auth-config.xml file. You need to add all the XML content, not just your application policies sections, to your custom-values.yaml under this key:

pipOperator:
  plainIDConfig:
    auth-config.xml: |
      <?xml version='1.0'?>
      <policy xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="urn:jboss:security-config:5.0"
        xmlns="urn:jboss:security-config:5.0">
        <!-- Add your XML content here -->
      </policy>

Following is an example:

tenantId: "ENTER_TENANT_ID" # Tenant Id (can be found in the Hybrid Agent Keys tab)
agentSecretKey: "ENTER_AGENT_SECRET_KEY" # Agent Secret key (can be found in the Hybrid Agent Keys tab)
paaId: "ENTER_PAA_ID" # Policy Authorization Agent Id (can be found in the Policy Authorization Agents tab)

pipOperator:
  plainIDConfig:
    auth-config.xml: |
      <?xml version='1.0'?>
      <policy xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="urn:jboss:security-config:5.0"
        xmlns="urn:jboss:security-config:5.0">
        <!-- Add your XML content here -->
      </policy>

Standalone/VM PAA

In a Standalone/VM PAA, the auth-config.xml file is located at $PLAINID_HOME/pip-operator/conf/auth-config.xml. Add OAuth services as application policies, as described above.

OAuth Logging

Additional logging for OAuth can be configured by adding the following section to the auth-config.xml via the custom-values.yaml mechanism:

<logger name="org.teiid.jboss.oauth" level="detail" additivity="false">
    <appender-ref ref="RollingFile" />
</logger>

OAuth Setting For PIP Data Sources

After completing the OAuth configuration, you will be able to configure PIP data sources accessible by OAuth authentication.

In the PIP settings UI, when creating a data source with adapters that allow/require the usage of OAuth (e.g., Azure Active Directory, SCIM, REST, or OData v4.0), you will need to reference the auth-config.xml file and the specific application-policy name as the Security Domain:

1. In the Policy Authorization Agent section(s), under the Security Type field, choose None.

2. In the Translator Properties section, add two new properties with these key-value pairs:

   • Key = authConf, Value = "<path of the auth-config.xml file as described above.>"
   • Key = securityDomain, Value = "<name of the application-policy you added in the XML for your service>"