Skip to end of metadata
Go to start of metadata

You are viewing an old version of this content. View the current version.

Compare with Current View Version History

« Previous Version 19 Current »

Why Use Authentication?

Authentication is a way to verify that only permitted calls to an API are allowed.

How To Enable Authentication on an API Endpoint

  1. Open a  API Endpoint in PhixFlow from the  Actionflow homepage
  2. On the toolbar, click  Properties
  3. Disable  Allow Anonymous Connection 
    1. This will then only allow authenticated calls to the API
  4.  Apply the changes

How To Create Authentication Users

Create New User (Optional)

Create a dedicated API user with limited privileges if you want the API to show as being run by this user in the System Console. 

  1. In the  Full Repository, expand the  Users section 
  2. Click  to create a new user who will be able to run the API
    1. Enabled: 
    2.  Apply the user

Create New Role

  1. In the  Repository, expand the application with the Incoming API
  2. Expand  Roles and create an New Role by clicking 
    1. Pin the tab as we will need it to remain open
    2. Provide a useful Name, e.g. GenerateToken

Add Privileges to New Role 

  1. In the Privileges section, click  Privileges
  2. Search for and drag across the following privileges in the Full Repository:
    • Use API Key
    • Run Actions
  3. Drag each privilege across from the Full Repository into the Privileges section of the Role  Properties
  4.  Apply the changes

Create and Assign API User Group to Role

  1. In the  User Groups section, click  User Groups
    1. Add a new Group for your Role
      1. Give it a useful Name e.g. API Users
      2. Add any users you require to be able to run the API
        1. This could be a dedicated API user with limited privileges, such as the one created in the section, Create New User, above
          1. For more on creating users, see Managing User Accounts
      3. Click  Apply and close the tab
    2. Now drag the new user group into the  User Groups section of the new role
    3.  Apply the changes
  2. The setup should look similar to:

Assign Application Access User Group to New User (Optional)

  1. If you created a new user, in the  Full Repository, expand the  Users section
  2. Double click on the new user
  3. In the User Groups section, click the  icon to display the available User Groups in the Full Repository
  4. Search for the name of your application in the search box
    1. Two User Groups will display - drag across the one that doesn't contain _Admin into the User Group section of your user

How To Generate Authentication Tokens

  1. The Incoming API will run as a specified user, this means that when it is called the audit trail will show the specified user as having performed the Incoming API Actionflow
  2. You do not need to login as this user, however, if you were already logged in as this user, you will need to logout and login again to pick up the user group change 
  3. In the  Repository, scroll down to the Full Repository section and expand it
  4. Expand the  Users section
  5. Double click on the user who will run the Incoming API
  6. Click the 3-dot more menu in the top right of the user properties
  7. Click Generate API Key
  8. Copy the value displayed and store it somewhere safe

How To Send Authorisation

When calling the API, the authorisation token must be passed in as a header called: Authorization.

  1. On the  HTTP action, open the  Properties
  2. In the Secret Key Details section, click 
    1. Give the secret key a name, e.g. MyAPIKey
    2. Toggle on Enabled
    3.  Apply the secret key
    4. Next to Secret, click 
    5. Paste in the API Key you copied above - see above section, How To Generate Authentication Tokens
    6.  Apply and Close the Local Secret and Secret Key
  3. In the Headers section on the  HTTP action, click 
    1. Name: Authorization
    2. Expression: ${_datasource.MyAPIKey}
      1. Where MyAPIKey is the name of the Secret Key you set above

Worked Example

Here's a worked example using the Company Data (available from the Learning Centre).

In this example, we are using:  

  • A Company Call API screen containing a fixed drop down list of industries, a string fields for the API Status and a multi-line string field for the Results - this screen was created using the Tile with Buttons template

If you are completing this chapter as part of the Actionflow course and using a training instance, the data and screens have already been pre-loaded into the Actionflow Advanced Application. For this example, we'll be working on the Company Call API screen.

Add Authentication to API Calling Actionflow

In this example, we'll add authentication to the Actionflow that calls an API. 

Prerequisites

For this example, we'll modify an API End Point Actionflow containing company data to only allow authenticated calls and we'll add secret key details to an Actionflow that calls the API.

The two Actionflows that will be modified were created in Setting up an API Endpoint If you have not completed this chapter, expand the section below and follow the steps to create the Actionflows.

 Create API End Point Actionflow and Call API Actionflow

Example 1: Passing Out Data

In this example, we'll configure an API Endpoint that passes out Company ID, Company Name and Industry data from our Companies data.

Create API Endpoint

In this example, we'll set up an API Endpoint to pass out company data.

  1. Create a new  API Endpoint on the  Actionflow homepage using the  option
    1. Name: API Company Data
    2. Click Create
  2. The API Endpoint canvas will display, with the  Properties open on the right
    1. In the Basic Settings section, enable Allow Anonymous Connections
    2. Copy the URL and save it locally, to be used later
    3.  Apply your changes
 Checkpoint

Construct JSON

  1. Create a  Calculate action
    1. Name: GetDataAndConstructJSON
  2. Connect the input to the Calculate action

  3. From the  Calculate action, create a lookup to the Companies data

     How?
    1. Hover over the Calculate action and select Add lookup
      1. Name: getCo
    2. On the Create View window:
      1. Name: CompanyData
      2. Table: Companies
      3. Output Attributes Selection: drag CompanyID, CompanyName and Industry into the Output Attributes section of the View Action properties
      4. Return (Outgoing) Mappings: map across CompanyID, CompanyName and Industry


  4. On the Calculate action, create an attribute where the JSON will be constructed
    1. Name: JSON
    2. Type: Structured Data

    3. Expression: 

      1. toJson(getCo)

    4.  Apply and Close

 Checkpoint

Configure the Output

  1. Drag the  output connection node onto the Calculate node

  2. Map the JSON attribute from the Calculate action to the body attribute 

Example 2: Passing in Parameters

In this example, we'll retrieve data from our Companies API and pass in an industry parameter (e.g. "Telecoms") to filter the results to just companies in that industry.

API End Point Setup

  1. On the API End Point, create a  JSON action to receive the parameter
    1. Name: GetIndustry
      1. Input Expression: in.body
      2. Path: $
      3. Create an Output Attribute on the JSON action
        1. Name: IndustryReceived
        2. Type: String
        3. Expression: _result.Industry
    2. Insert the   JSON action between the  input and  Calculate nodes
    3. On the Mappings between the  input and  JSON nodes, map across body, contentType, headers and url
    4. On the lookup connector, getCo, map the IndustryReceived attribute as an Incoming Mapping
    5. On the   View action, add a filter:
      1. Name: ByIndustry
      2. Filter Details:  

Call API Actionflow Setup

  1. On the screen, Company Call API, add an Actionflow to the Call API button
    1. If you have completed /wiki/spaces/HELP12/pages/9615606000 and /wiki/spaces/HELP12/pages/9615626047 you will recognise the similar Actionflow setup
    2. On the input connection point, map in the Industry drop down field
    3. Create a  HTTP action:
      1. Name: Call API
    4. Connect the input to the HTTP action and map across the attribute, Industry
      1. HTTP Method: POST
      2. URL: the URL from the API End Point you copied earlier

      3. Body: 

        [{
    "Industry": "${in.Industry}"
}]

      4. Log Traffic: 

         Checkpoint

    5. Create a  JSON action 

      1. Name: ReturnedCompanies

      2. Input Expression: in.body

      3. Path: $.getCo

      4. Create 2 Output Attributes on the JSON action

        1. Name: CoName
          1. Type: String 
          2. Expression: _result.1.CompanyName
        2. Name: CompanyID
          1. Type: Integer 
          2. Expression: _result.1.CompanyID
    6. Hover over the HTTP action and choose out, then connect it to the JSON action
    7. On the Mappings between the HTTP action and JSON action, map the attributes:
      1. body
      2. status
    8. Create an  output connection point back to the screen
    9. Connect the JSON action to the output, and configure the following mappings:
      1.  
    10. Then map the following attributes back to the screen on the output connection point:
 Checkpoint

Testing

  1. On the screen, Company Call API, click the Call API button to see the results of the Actionflow


System Console Response

On the HTTP action, Call API, the option to Log Traffic was enabled allowing the API response to be seen in the  System Console.

  1. The results of the API call can also be seen in the  System Console via the  Administration option
    1. Navigate to the Completed Tasks tab
    2. Find the Actionflow calling the API and click on it
    3. In the Messages tab in the bottom half of the screen, double-click the message, Response from URL
    4. Click on the Message Detail tab in the Log Message window to see the API output

Enable Authentication on API End Point Actionflow

  1. Open the  API Company Data 
  2. On the toolbar click  Properties
  3. In the API section, disable  Allow Anonymous Connection 
    1. This will then only allow authenticated calls to the API
  4.  Apply the changes

Create Authentication User

  1. In the  Full Repository, expand the  Users section 
  2. Click  to create a new user who will be able to run the API
    1. Login: apiagent
    2. First Name: API
    3. Surname: Agent
    4. Password: Phixflow123!
    5. Enabled: 
    6.  Apply the user

Create Role

We need to create a role then assign the privilege and user group(s) to it.

  1. In the  Repository for the application (not the full repository), expand the application you're working in
  2. Expand  Roles and create an New Role by clicking 
    1. Pin the tab as we will need it to remain open
    2. Name: GenerateAPIToken

Add Privileges to Role

  1. On the Role, in the Privileges section, click  Privileges
    1. Search for and drag across the following privileges from the Full Repository into the Privileges section of the Role  Properties:
      • Run Actions
      • Use API Key
    3.  Apply the changes

Create and Assign User Group to Role

  1. On the Role, in the  User Groups section, click  User Groups
    1. Create a new User Group by clicking the 
      1. Name: APIUsers
      2.  Apply the new user group
      3. On the User Group, in the Users section, click  icon and drag across your API Agent user into the Users section
      4. Click  Apply the changes
  2. Click back onto the GenerateAPIToken Role tab
  3. Drag the APIUsers user group into the  User Groups section of the GenerateAPIToken Role
    1.  Apply the changes

Assign Application Access User Group to User

  1. In the  Full Repository, expand the  Users section
  2. Double click on the API Agent user
  3. In the User Groups section, click the  icon to display the available User Groups in the Full Repository
  4. Search for the name of your application in the search box
    1. Two User Groups will display - drag across the one that doesn't contain _Admin into the User Group section of your API Agent user

Generate Authentication Token

  1. On the API Agent user, hover over the 3-dot menu in the top right corner
  2. Click Generate API Key
  3. Copy the value displayed and store it somewhere safe

Send Authorization

  1. On the screen, Company Call API, open the Actionflow on the Call API button
  2. Click on the HTTP Action, Call API, to open its  Properties
  3. In the Secret Key Details section, click 
    1. Name: APIKey
    2. Enabled: 
    3.  Apply the changes
    4. Secret: click 
      1. In the Secret field, paste the API Key you copied above
      2.  Apply the changes
  4. In the Headers section, click 
    1. Name: Authorization
    2. Expression: ${_datasource.APIKey}
  5.  Apply the changes

Testing

  1. On the Actionflow calling the API, click Run Action and run the Actionflow
  2. Access the System Console to check if the API displays as being run by your specific API User


  • No labels