Setting up native OAuth 2.0 authentication

When you configure native OAuth 2.0 authentication, you only need OAuth 2.0 clients for authentication with the REST APIs and CLI tools. Basic authentication is not allowed when OAuth 2.0 is configured.

In this configuration, OpenPages® performs the role of OAuth 2.0 Authorization Server. If you want, you can also use another OAuth 2.0 Authorization Server or OpenID Connect (OIDC) provider as the Identity Provider (IdP).

Before you begin

Your environment must meet the following criteria:

OpenPages is installed and the OpenPages servers are running.
You can log in to the OpenPages application from your browser.

About this task

In this task, you configure an IBM® WebSphere® Liberty server to act as the Authorization Server and an OpenID Connect Client. For more information, see OpenID Connect Client (openidConnectClient).

You can use any external OpenID provider or Authorization Server that supports OAuth 2.0 or OpenID Connect protocols.

Procedure

Log on to the OpenPages application server.
Install the oauth-2.0 and IBM WebSphere Liberty openidConnectClient-1.0 features by running the following commands:
```
<WLP_HOME>/bin/installUtility install oauth-2.0
<WLP_HOME>/bin/installUtility install openidConnectClient-1.0
```
The IBM WebSphere Liberty server provides transportSecurity-1.0, so you don't need to install it separately.
Configure an OAuth 2.0 client.
For more information, see Configuring an OAuth 2.0 client.
To ensure that the client secret you generated in the previous step is stored securely, run the following command to encrypt it:
```
<WLP_HOME>/bin/securityUtility encode --encoding=aes
```
When prompted to enter text, enter the client secret.

Use the aes-encrypted value that the command returns to replace <CLIENT_SECRET> in step 6.
Go to the directory <WLP_USER_DIR>/servers/<server_name>Server<#>/configDropins/overrides.
If the directory does not exist, create it.

Create an .xml file with a name similar to OP_OAUTH2_config.xml. In the file, insert the following lines:

<server>
	<featureManager>
		<feature>oauth-2.0</feature>
		<feature>openidConnectClient-1.0</feature>
		<feature>transportSecurity-1.0</feature>
	</featureManager>

    <application-bnd>
        <security-role name="OpenPagesApplicationUsers">
            <special-subject type="ALL_AUTHENTICATED_USERS"></special-subject>
        </security-role>
        <security-role name="AllAuthenticated">
            <special-subject type="ALL_AUTHENTICATED_USERS"/>
        </security-role>
	</application-bnd>

    <oauthProvider id="OPOauthProvider" accessTokenLifetime="2m" clientSecretEncoding="PBKDF2WithHmacSHA512" accessTokenEncoding="PBKDF2WithHmacSHA512" >
        <databaseStore dataSourceRef="CWTxDataSourceXA" schema="OPENPAGE" />
    </oauthProvider>

    <openidConnectClient id="<ID>"
        clientId="<CLIENT_ID>"
        clientSecret="<CLIENT_SECRET>"
        authorizationEndpointUrl="https://<HOST_NAME>:<PORT>/oauth2/endpoint/OPOauthProvider/authorize"
        tokenEndpointUrl="https://<HOST_NAME>:<PORT>/oauth2/endpoint/OPOauthProvider/token"
        validationEndpointUrl="https://<HOST_NAME>:<PORT>/oauth2/endpoint/OPOauthProvider/introspect"
        userIdentityToCreateSubject="functional_user_id"
        inboundPropagation="required">
		<authFilter id="oidcApiAuthFilter">
			<requestUrl id="apiCUrl" matchType="contains" urlPattern="/grc/api|/opgrc/api"/>
		</authFilter>
	</openidConnectClient>
	<webAppSecurity allowFailOverToBasicAuth="false" />
</server>

Use the values in the following table to replace the placeholders in the .xml file:

Table 1. Placeholders and values
Placeholder	Value
`<ID>`	Any unique ID
`<HOST_NAME>`	The application hostname
`<PORT>`	The application port
`<CLIENT_ID>`	The client ID created in step 3.
`<CLIENT_SECRET>`	The aes-encrypted value client secret created in step 4.

One default client ID and secret are enough to validate a connection with openidConnectClient.

Make sure that the <authFilter> element does not contain <requestUrl> filters that conflict.

Tip: To add more filters, create more <requestUrl> elements. Give each of them a unique id.

Restart the OpenPages application server.
Repeat steps 4 to 7 on all application servers in a load-balanced environment.

What to do next

To authenticate with the OAuth 2.0 client ID and client secret, see Calling the OpenPages REST API by using OAuth 2.0 authentication.