Use Oracle Advanced Authentication REST APIs with Postman

Introduction

This tutorial shows you how make REST API calls to Oracle Advanced Authentication using Postman, software typically used for REST API tests.

Objectives

The Oracle Advanced Authentication REST APIs provide a way to integrate Oracle Advanced Authentication with REST clients so that they can configure and administer Oracle Advanced Authentication. For a full list of the REST API endpoints refer to OAA Admin API.

In this tutorial you will learn how to download and import the Oracle Advanced Authentication Postman collection and test some of the most common Postman requests.

Prerequisites

In order to complete this tutorial, you will require the following:

Install the Oracle Advanced Authentication Postman Collection

Set the Environment Parameters in Postman

  1. Open Postman, and select File > Import.

  2. In the Import dialog box, in the File tab, select Upload Files. Choose the Oracle_Advanced_Authentication_Example_Environment.postman_environment.json , and then click Open.

  3. In the left hand menu click .

  4. In the environment list displayed, to the right of Oracle Advanced Authentication Example Environment, click the elipsis and then Duplicate.

    Description of the illustration duplicate_env.jpg

  5. On Oracle Advanced Authentication Example Environment Copy, which appears above the original environment, click the elipsis and rename to Oracle Advanced Authentication Environment for REST APIs.

  6. Update the environment variables for the new environment by entering the following values for Initial Value and Current Value. Once complete click Save and then X on the tab to close it:

    • oaa-admin: Oracle Advanced Authentication hostname and admin port, for example https://oaa.example.com
    • oaa-policy: Oracle Advanced Authentication hostname and policy port, for example https://oaa.example.com
    • oaa-runtime: Oracle Advanced Authentication hostname and runtime port, for example https://oaa.example.com
    • RELEASENAME: The RELEASENAME assigned to the Oracle Advanced Authentication setup, for example oaainstall. This is the value passed for common.deployment.name when installing OAA.
    • oaapolicyapikey: The oaapolicyapikey for the Oracle Advanced Authentication setup, for example a5764d4ef6b71129f38a2d8ddc88b6060653d3c8. This is the value passed for install.global.policyapikey when installing OAA.
    • oaaapikey: The oaaapikey for the Oracle Advanced Authentication setup, for example a5764d4ef6b71129f38a2d8ddc88b6060653d3c8. This is the value passed for install.global.uasapikey when installing OAA.
    • KBA: The KBA username for the Oracle Advanced Authentication setup, for example OAAINSTALL_OAA_KBA. This takes the value <RELEASENAME>_OAA_KBA and is case sensitive.
    • oaafactorapikey: The oaafactorapikey for the Oracle Advanced Authentication setup, for example a5764d4ef6b71129f38a2d8ddc88b6060653d3c8. This is the value passed for install.global.factorsapikey when installing OAA.

    Note: If you do not know the URL’s for oaa-admin, oaa-policy, and oaa-runtime (spui), see Printing Deployment Details.

    The environment will look similar to the following:

    Description of the illustration environment.jpg

    Note: The URL values in the example above assume an OAA install using NodePort and hence port numbers for each of the pods are defined in the URL’s. If the OAA install uses an ingress then use the ingress URL in all cases.

  7. Click the Environment drop-down list, and then select the updated environment from the list:

    Description of the illustration environment_selection.jpg

Import the Postman Collection

  1. To import the Oracle Advanced Authentication REST API Postman collection, on the Postman main page, select File > Import.

  2. In the Import dialog box, in the File tab, select Upload Files. Choose the file Oracle_Advanced_Authentication_REST_API.postman_collection.json, and then click Open and then Import.

    Click on Collections in the left hand menu. The collection should display as follows:

    Description of the illustration collections.jpg

Test the REST API’s

In this section you will run some of the requests in the Postman collection for Oracle Advanced Authentication.

Note : To prevent SSL certificate verifcation errors, navigate to File > Settings, and in the General tab set SSL certificate verification to OFF.

Create an API Integration Agent

In this section you will create an API integration agent.

  1. On the Collections tab, navigate to Oracle Advanced Authentication REST API > REST API for Defining System Entities -> agent/v1.

  2. Select Create a new API integration agent. This request makes a POST request to the /oaa-policy/agent/v1 endpoint, and creates an API integration agent called APIAgent based on the information in the Body:

    Description of the illustration createapiagent.jpg

  3. Click Send.

  4. In the response, confirm that the Status: 200 OK appears and that the response body displays details about the integration agent created. Make note of the agentgid returned as this will be used in the following sections.

    Description of the illustration createapiagentsuccess.jpg

Create an Assurance Level

In this section you will create an Assurance Level for the integration agent created.

  1. On the Collections tab, navigate to Oracle Advanced Authentication REST API > REST API for Defining System Entities -> AssuranceLevel/v1.

  2. Select Define Assurance Level. This request makes a POST request to the /oaa-policy/assuranceLevel/v1 endpoint and creates an Assurance Level for the integration agent called AssuranceLevel1. In the body, edit the value for agentid to match the value returned earlier:

    Description of the illustration createassurancelvl.jpg

  3. Click Send.

  4. In the response, confirm that the Status: 200 OK appears and that the response body displays details about the Assurance Level created.

    Description of the illustration createassurancelvlsuccess.jpg

Create Groups

In this section you will create an action group for Factors and a group for IP addresses. These groups will later be assigned to a policy and rule for the integration agent and Assurance Level previously created.

  1. On the Collections tab, navigate to Oracle Advanced Authentication REST API > REST API for Defining System Entities -> group/v1.

  2. Select Create new factor group. This request makes a POST request to the /oaa-policy/group/v1 endpoint, and creates a group for the agent called FactorRuleGrp1. In the body, edit the value for agentid to match the value returned earlier. In this example the group sets two factors - ChallengeEmail and ChallengeOMATOTP:

    Description of the illustration createfactorgrp.jpg

  3. Click Send.

  4. In the response, confirm that the Status: 200 OK appears and that the response body displays details about the group created. Make note of the groupid as this will be used later to assign this group to a policy.

    Description of the illustration createfactorgrpsuccess.jpg

  5. In the current collection under group/v1 select Create new group of type IP’s. This request makes a POST request to the /oaa-policy/group/v1 endpoint, and creates a group for the integration agent called SecureIP. In the body, edit the value for agentgid to match the value returned earlier. In this example the values section sets the IP’s from 198.51.100.1 to 198.51.100.3:

    Description of the illustration createipgrp.jpg

  6. Click Send.

  7. In the response, confirm that the Status: 200 OK appears and that the response body displays details about the group created. Make note of the groupid as this will be used later to assign this group to a policy.

    Description of the illustration createipgrpsuccess.jpg

Create Policy

In this section you will create a Policy for the Assurance Level and integration agent previously created.

  1. On the Collections tab, navigate to Oracle Advanced Authentication REST API > REST API for Defining System Entities -> policy/v1.

  2. Select Create new policy. This request makes a POST request to the /oaa-policy/policy/v1 endpoint, and creates a policy for the previously created integration agent and assurance level called Policy1. In the body, edit the value for agentgid to match the value returned earlier:

    Description of the illustration createpolicy.jpg

  3. Click Send.

  4. In the response, confirm that the Status: 200 OK appears and that the response body displays details about the policy created. Make note of the policygid as this will be used later assign a rule to this policy.

    Description of the illustration createpolicysuccess.jpg

Create Policy Rule

In this section you will create a Policy Rule for the Policy.

  1. On the Collections tab, navigate to Oracle Advanced Authentication REST API > REST API for Defining System Entities -> policy/v1 -> {policygid} -> rule > {ruleid}.

  2. Select Define new rule for the policy. This request makes a POST request to the /oaa-policy/policy/v1/:policygid/rule endpoint. In the Params tab edit the value for policygid to match the value for the policy returned earlier. In the Body, under conditionMap edit the values under expression and values and set to the groupId of the SecureIP group created earlier. Under results set the value for action to match the groupId of the FactorGroup1 group created earlier:

    Description of the illustration createrule.jpg

    In the above, the rule states that if the IP address of the end user making the authentication request is one of those defined in the SecureIP group, then set the factors for authentication to those defined in FactorGroup1.

  3. Click Send.

  4. In the response, confirm that the Status: 200 OK appears and that the response body displays details about the rule created. Make note of the rulegid for later reference..

    Description of the illustration createrulesuccess.jpg

Create User Preferences

In this section you create a user user1 and register their factor preferences.

  1. On the Collections tab, navigate to Oracle Advanced Authentication REST API > REST API for User Preferences -> preferences/v1.

  2. Select User Preferences are created/registered. This request makes a POST request to the /oaa/runtime/preferences/v1 endpoint. In the Body, enter the userId to be created and their corresponding groupId. In the example below user1 is created in the Default group and registers the user for Email and OMATOTP factors. Change the email address value to a valid email address. Change the secret_key for OMATOTP to a value of your choice to use in the Oracle Mobile Authenticator application.

    Description of the illustration createuserprefs.jpg

  3. Click Send.

  4. In the response, confirm that the Status: 200 OK appears and that the user and their preferences are created and registered successfully.

    Description of the illustration createuserprefssuccess.jpg

Challenge the User, Initialize the Challenge, and Validate

In this section you test a user challenge for user1 against the rule created earlier in Create Policy Rule. If the rule is validated, the factors registered for that user are returned. After choosing a factor to authenticate with, an Initialize request is sent to prompt for the OTP for that factor. A valid factor OTP is then entered and validated.

Before starting this section make sure your Oracle Mobile Authenticator has an Oracle account added with the Key set to the secret_key value entered in Create User Preferences. See Configuring an Account in Oracle Mobile Authenticator

  1. On the Collections tab, navigate to Oracle Advanced Authentication REST API > REST API for User Challenge -> Challenge User, Initalize Challenge, Validate Challenge.

  2. Select Challenge User. This request makes a POST request to the /oaa/runtime/authn/v1 endpoint. In the Body enter the userId for user1 and their corresponding groupId. In the example below the challenge will be made for user1 against the API Integration Agent you created earlier in Create Integration Agent API. Enter the values for clientSecret and clientId for this API agent. In the ipAddr enter an IP that was defined in SecureIP group created earlier:

    Description of the illustration challengeuser.jpg

  3. Click Send.

  4. In the response, confirm that the Status: 200 OK appears. An OAA-40001 message is returned stating Authentication Required. The factors registered to user1 (Email and OMATOTP) are returned along with a correlationId. Make note of the correlationId to use in subsequent requests:

    Description of the illustration challengeusersuccess.jpg

  5. Under Challenge User, Initalize Challenge, Validate Challenge select Initialze Challenge. This makes a PUT request to the /oaa/runtime/authn/v1 endpoint. In the Body enter the correlationId returned in the previous response. In this example we are selecting to use the OMATOTP factor:

    Description of the illustration initchallenge.jpg

  6. Click Send.

  7. In the response, confirm that the Status: 200 OK appears. An OAA-40001 message is returned stating Authentication Required for the OMATOTP. A nonce value is returned for the associated correlationId. Make note of the nonce value for use the next request:

    Description of the illustration initchallengesuccess.jpg

  8. Under Challenge User, Initalize Challenge, Validate Challenge select Validate Challenge. This makes a PUT request to the /oaa/runtime/authn/v1 endpoint. In the Body enter the correlationId, and nonce returned in the previous response. Enter a valid OTP from Oracle Mobile Authenticator in the ChallengeAnswer:

    Description of the illustration validate.jpg

  9. Click Send.

  10. In the response, confirm that the Status: 200 OK appears. If the validation of the OTP is successful an OAA-40004 message is returned stating the user is Authenticated:

    Description of the illustration validatesuccess.jpg

Learn More

Feedback

To provide feedback on this tutorial, please contact idm_user_assistance_ww_grp@oracle.com

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.