Manage OAuth Client Secret Retrieval

Introduction

Using Oracle Access Management (OAM), you can create OAuth clients that are used to interact with OAuth providers and applications. By default, the OAuth client secret once created is stored hashed and is not usable that is, can not be retrieved. Starting with the October 2022 Bundle Patch, you can retrieve the secret of an OAuth client in usable form. Administrators must enable the OAuth client recovery feature to retrieve the client secret. Older OAuth clients that were created before the patch must be updated/reset before the secret can be retrieved. If the OAuth Client secret recovery feature is disabled, the OAuth Client GET API will return secret in hashed form (unusable) even after applying Oct 2022 BP.

Objectives

Setup OAuth Service in Oracle Access Management.

Prerequisites

Task 1: Enable OAM OAuth client secret recovery

  1. Depending on your configuration, you can turn on or off this feature. If the configuration is not present, OAM assumes the feature is off. Configuration Setting Path: /DeployedComponent/Server/NGAMServer/Profile/ssoengine/OAuthConfig Configuration Setting Name: ClientSecretRecoveryEnabled The following command allows you to determine if Client Secret Recovery is enabled or disabled.

    curl --location --request GET 'https://<admin-host>:<admin-port>/iam/admin/config/api/v1/config?path=/DeployedComponent/Server/NGAMServer/Profile/ssoengine/OAuthConfig' --header 'Authorization: <Basic Authz Header>'

    Description of the illustration config_does_not_exist.jpg

  2. If the configuration is not present or is disabled (false) then execute the following command to add/update the value to true. Note: Skip this step if the value already exists and is set to true.

    curl --location --request PUT 'https://<admin-host>:<admin-port>/iam/admin/config/api/v1/config?path=/DeployedComponent/Server/NGAMServer/Profile/ssoengine/OAuthConfig' --header 'Authorization: <Basic Authz Header>' /--header 'Content-Type: application/xml' --data-raw '<Setting Name="OAuthConfig" Type="htf:map" Path="/DeployedComponent/Server/NGAMServer/Profile/ssoengine/OAuthConfig"> <Setting Name="ClientSecretRecoveryEnabled" Type="xsd:boolean">true</Setting></Setting>'

    Description of the illustration updating_config_to_true.jpg

    Verify that the value is successfully updated using the GET API in Step 1.

Task 2: Retrieve OAuth client details - For newly created client

When the Secret Recovery feature is enabled on a client, the GET client API will return the secret in the format Basic <base64 encoded id:secret>.

  1. Create the client with the following attributes.

    • client name: SampleClientNew1
    • client id: SampleClientNew1_id
    • secret: client_secret

  2. Retrieve the client details using the OAuth Client API.

    curl --location --request GET 'https://<admin-host>:<admin-port>/oam/services/rest/ssa/api/v1/oauthpolicyadmin/client?identityDomainName=SampleDomain&name=SampleClientNew1' --header 'Authorization: <Basic Authz Header>' --header 'Accept: application/json'

    The secret returned is: Basic U2FtcGxlQ2xpZW50TmV3MV9JZDpjbGllbnRfc2VjcmV0 Base 64 Decoded value is: SampleClientNew1_Id:client_secret

    Description of the illustration get_new_client.jpg

Task 3: Retrieve OAuth client details - For an existing client

For a client that was created before secret recovery feature was enabled, the secret is not recoverable unless the feature is reset/updated. The GET Client API returns a message to reset the feature to retrieve the value.

  1. Create the client with the following attributes.

    • client name: SampleClientOld1
    • client id: SampleClientOld1_id
    • secret: client_secret

  2. Retrieve the client details using the OAuth Client API.

    curl --location --request GET 'https://<admin-host>:<admin-port>/oam/services/rest/ssa/api/v1/oauthpolicyadmin/client?identityDomainName=SampleDomain&name=SampleClientOld1' --header 'Authorization: <Basic Authz Header>' --header 'Accept: application/json'

    Description of the illustration get_old_client.jpg

    The message reads: OAMSSA-06399: Current secret is not recoverable. Please reset secret to make it recoverable.

  3. Update the client secret using the OAuth Client API.

    curl --location --request PUT 'https://<admin-host>:<admin-port>/oam/services/rest/ssa/api/v1/oauthpolicyadmin/client?identityDomainName=SampleDomain&name=SampleClientOld1' --header 'Content-Type: application/json' --header 'Accept: application/json'  --header 'Authorization: <Basic Authz Header>' --data-raw  '{ "secret": "client_secret_new"  }'

    Description of the illustration client_secret_modify.jpg

    New secret: client_secret_new

  4. Retrieve the updated client details using the OAuth Client API. The GET Client API will return the secret in the format Basic <base64 encoded id:secret>.

    curl --location --request GET 'https://<admin-host>:<admin-port>/oam/services/rest/ssa/api/v1/oauthpolicyadmin/client?identityDomainName=SampleDomain&name=SampleClientOld1' --header 'Authorization: <Basic Authz Header>' --header 'Accept: application/json'

    Description of the illustration get_old_client_post_modify.jpg

    The secret returned is: Basic U2FtcGxlQ2xpZW50T2xkMV9JZDpjbGllbnRfc2VjcmV0X25ldw== Base 64 Decoded value is: SampleClientOld1_Id:client_secret_new

  5. If the configuration ClientSecretRecoveryEnabled is updated to false , the GET OAuth Client API will return a hashed secret instead of base64 encoded result, which is the pre Oct 2022 Bundle Patch behavior.

Acknowledgements

More Learning Resources

Explore other labs on docs.oracle.com/learn or access more free learning content on the Oracle Learning YouTube channel. Additionally, visit education.oracle.com/learning-explorer to become an Oracle Learning Explorer.

For product documentation, visit Oracle Help Center.