# Secure Your API With OpenID Connect OAuth 2.0 Standard

## Securing APIs with Red Hat Single Sign-on and OAuth

### Describing OIDC Authentication Workflow in Red Hat 3scale API Management

You can configure 3scale API Management to require OpenID Connect (OIDC) as an authentication mechanism for your APIs. This means that 3scale API Management verifies the following:

* Each request contains a JSON Web Token (JWT).
* The JWT token is cryptographically signed by the configured OIDC provider.
* The JWT token is valid, for example not expired.
* The JWT token contains the necessary claims, such as the authorized party (azp) or audience (aud).

When you configure OIDC integration, APIcast reads the configuration of the OIDC provider by using the `https://OIDC_PROVIDER_HOST/.well-known/openid-configuration` discovery endpoint. APIcast caches information required for validating JWT tokens, such as public keys and signing algorithms.

Requests to the protected API then require a valid JWT token. The following diagram provides an example of an authentication request flow:

![sso config](https://3707709575-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FlMgVlX77EAThg6NrNt4u%2Fuploads%2Fgit-blob-72f669cd2953b116191d586ed52ff50b0e643a52%2Foauth-auth-flow.png?alt=media)

### Integrating 3scale API Management with Red Hat Single Sign On (RHSSO)

When you configure OIDC integration in your product, 3scale API Management requires that the authorized party (azp) claim in the JWT token corresponds to the API credentials that you associate with an application in your product. However, RHSSO issues JWT tokens. Consequently, 3scale API Management must synchronize application credentials with RHSSO.

The Zync component is responsible for the credential synchronization with RHSSO. When you create a new application, the Sidekiq component schedules Zync to synchronize the data with RHSSO. Zync asynchronously communicates with RHSSO and creates the API credentials.

![sso config](https://3707709575-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FlMgVlX77EAThg6NrNt4u%2Fuploads%2Fgit-blob-8a05af74711f99109164cfeb0d1d6de14e8fe418%2Foauth-acc-flow.png?alt=media)

## Steps

* [1. Configure SSO](#1-configure-sso)
* [2. Setting Authentication mode for API Product](#2-setting-authentication-mode-for-api-product)
* [3. Recreate Application](#3-recreate-application)
* [4. Testing](#4-testing)

## 1. Configure SSO

You have to setup Zync client in SSO (Keycloak) so 3scale can integrate with SSO and call SSO APIs.

1. Login to Red Hat SSO web console using the URL and credential from step 4 above.
2. Click **Clients** menu from left panel.

   ![sso config](https://3707709575-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FlMgVlX77EAThg6NrNt4u%2Fuploads%2Fgit-blob-a145e5c170f9ac147f334a7f07a7ade1c0c092c2%2Fsso-config-1.png?alt=media)
3. Click **Create** button.

   ![sso config](https://3707709575-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FlMgVlX77EAThg6NrNt4u%2Fuploads%2Fgit-blob-4d3fa7bb9d970d39fccd7706a17c4c2b9c5fcfd7%2Fsso-config-2.png?alt=media)
4. Click **Select file** button. Browse to [zync-client.json](https://github.com/audomsak/redhat-3scale-api-management/blob/main/manifest/sso/zync-client.json) file.

   ![sso config](https://3707709575-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FlMgVlX77EAThg6NrNt4u%2Fuploads%2Fgit-blob-659b987aaa450d9a979bc6852a5b4222432d0c24%2Fsso-config-3.png?alt=media)
5. Click **Save** button.

   ![sso config](https://3707709575-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FlMgVlX77EAThg6NrNt4u%2Fuploads%2Fgit-blob-0d9619d6c77639f22665da44eb85f62b7f422b74%2Fsso-config-4.png?alt=media)
6. Go to **Service Account Roles** tab. In the **Client Roles** section, select **Realm Management**. Click **manage clients**, then click **Add selected** button.

   ![sso config](https://3707709575-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FlMgVlX77EAThg6NrNt4u%2Fuploads%2Fgit-blob-e344618a66f22a92bd92dfd1e580daa5d205b099%2Fsso-config-5.png?alt=media)
7. Go to **Credentials** tab. Look for **Secret** value, you will need this when setting up OAuth authentication in 3scale so keep this page open in web browser.

   ![sso config](https://3707709575-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FlMgVlX77EAThg6NrNt4u%2Fuploads%2Fgit-blob-4b99d41b98bf1576c62e5df725728529aad783cb%2Fsso-config-6.png?alt=media)

## 2. Setting Authentication mode for API Product

1. From main dashboard, click **Human Resource Services** link to open Product dashboard page.

   ![oauth secure](https://3707709575-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FlMgVlX77EAThg6NrNt4u%2Fuploads%2Fgit-blob-88f0516ce509a4533dfa69f53b5ded86c2655337%2Foauth-1.png?alt=media)
2. Enter following details:

   * **AUTHENTICATION** section
     * Select **OpenID Connect Use OpenID Connect for any OAuth 2.0 flow.** option.
   * **OPENID CONNECT (OIDC) BASICS** section
     * **OpenID Connect Issuer Type:** `Red Hat Single Sign-On`
     * **OpenID Connect Issuer:** Enter a URL in this format: `https://zync-client:<SECRET>@keycloak-sso.apps.<CLUSTER DOMAIN>/auth/realms/example`

       * **SECRET:** **Zync-client** client secret get from **Step 7** in [Configure SSO](#1-configure-sso) step above.
       * **CLUSTER DOMAIN:** OpenShift cluster domain. (You can also run `oc whoami --show-console|awk -F'apps.' '{print $2}'` command in terminal to get cluster domain value)

       For example, `https://zync-client:2IaLsOOTEZzTOBeTp5U8OfIeQiKYmNtI@keycloak-sso.apps.cluster-hrpdc.hrpdc.sandbox140.opentlc.com/auth/realms/example` #gitleaks:allow
   * **OIDC AUTHORIZATION FLOW** section
     * Check **Authorization Code Flow** and **Service Accounts Flow** options.

   ![oauth secure](https://3707709575-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FlMgVlX77EAThg6NrNt4u%2Fuploads%2Fgit-blob-d32a9510d10f7db6443f4d97ac9a2021bc197e5d%2Foauth-2.png?alt=media)
3. Scroll down to bottom of the page then click **Update Product** button.

   ![oauth secure](https://3707709575-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FlMgVlX77EAThg6NrNt4u%2Fuploads%2Fgit-blob-ed1e3c778130bbcb3b38289c1e8a8c331f791b94%2Foauth-3.png?alt=media)

## 3. Recreate Application

Due to the authentication mode for API product has been changed to OpenID Connect OAuth 2.0 flow, so the existing applications (**Test Corp HR Mobile** app, in this case) can't call APIs using API Key or API Key-Pair anymore. So, we need to recreate the application which 3scale will generate a new client ID in SSO for the application to be used for authentication in OAuth flow.

1. Select **Applications -> Listing** menu from left panel. Then click **Test Corp HR Mobile** link to open application page.

   ![oauth secure](https://3707709575-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FlMgVlX77EAThg6NrNt4u%2Fuploads%2Fgit-blob-fa6dfbecd8d7f9240b73a37172a6e023ef40c6a4%2Foauth-4.png?alt=media)
2. Click **Edit** link.

   ![oauth secure](https://3707709575-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FlMgVlX77EAThg6NrNt4u%2Fuploads%2Fgit-blob-ec1af1e0acd42bfd432b88e8d4cc0ffda2713277%2Foauth-5.png?alt=media)
3. Click **Delete** then **OK** button to confirm deletion.

   ![oauth secure](https://3707709575-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FlMgVlX77EAThg6NrNt4u%2Fuploads%2Fgit-blob-5bb5efa6c2e79c7511348601d6c2640fe4a88f39%2Foauth-6.png?alt=media)
4. You'll be directed to the Application dashboard. Click **Create application** button.
5.

```
![oauth secure](https://3707709575-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FlMgVlX77EAThg6NrNt4u%2Fuploads%2Fgit-blob-e16259a7452b9af215724a04901bafed3a91cbe0%2Foauth-7.png?alt=media)
```

6. Enter following details then click **Create application** button.

   * **Account:** `Test Corp`
   * **Product:** `Human Resource Services`
   * **Application plan:** `Free`
   * **Name:** `Test Corp HR Mobile`
   * **Description:** `Test Corp HR Mobile Application`

   ![oauth secure](https://3707709575-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FlMgVlX77EAThg6NrNt4u%2Fuploads%2Fgit-blob-1876d6f02d8d70bda0bc0f22b75fa87173793e54%2Foauth-8.png?alt=media)
7. A new application should be created with assigned Application Plan as well as an auto genereated Client ID and Client Secret. This will be used for authentication when calling APIs.

   ![oauth secure](https://3707709575-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FlMgVlX77EAThg6NrNt4u%2Fuploads%2Fgit-blob-34dbd8cff5fb7919b865d0b489cbae49a4907677%2Foauth-9.png?alt=media)
8. Go to SSO web console, Select **Clients** menu from left panel. You'll see a new client with the same Client ID in 3scale gets created automatically. This is done by Zync client component. Click on the client ID, you'll see the details.

   ![oauth secure](https://3707709575-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FlMgVlX77EAThg6NrNt4u%2Fuploads%2Fgit-blob-3c7ecef49b49f80b2ae6d2284bd89d2c5a071d50%2Foauth-10.png?alt=media)

   ![oauth secure](https://3707709575-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FlMgVlX77EAThg6NrNt4u%2Fuploads%2Fgit-blob-ab4b66e8c05d5107d0cc1bfb071b497cf3d48c54%2Foauth-12.png?alt=media)
9. Promote Configuration changes to Staging and Production.

   ![oauth secure](https://3707709575-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FlMgVlX77EAThg6NrNt4u%2Fuploads%2Fgit-blob-9e5d24d256f0edfe3694347a3fad04d98bf41226%2Foauth-11.png?alt=media)

## 4. Testing

1. Update `client-id` and `client-secret` variable in Postman Environments with **Client ID** and **Client Secret** generated when you recreate the application (see step 7 in [Recreate Application](#3-recreate-application)) and click **Save** button.

   ![oauth secure](https://3707709575-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FlMgVlX77EAThg6NrNt4u%2Fuploads%2Fgit-blob-cc2671cce56be498a6a9a094405b10a7ec73b215%2Foauth-13.png?alt=media)
2. [Test the API secured with OAuth](https://audomsak.gitbook.io/3scale/testing-application#testing-api-secured-with-oauth) using [3Scale API Testing (OAuth)](https://github.com/audomsak/redhat-3scale-api-management/blob/main/postman/3scale-api-testing-oauth.postman_collection.json) collection.

***