TABLE OF CONTENTS

• Introduction
• Overview  
• Creating a Key
• Key Types
  • Standard Methods
    • Basic Auth
  • Custom Methods
    • ONE DATA Auth
    • Personio Auth
    • Microsoft ROPC (Resource Owner Password Credentials)
    • Azure Blob Storage Auth
    • Google Cloud Platform Auth
    • Amazon Web Services Auth
• Referencing a Key in a Processor
• Invalid Keys After Import 
• Exposing Keys via API
  • Necessary Rights
  • Security Implications
  • How To Expose a Key
  • How To Use an Exposed Key
  • Example

Introduction

The scope of the Credentials functionality is to allow the user to get access to secure data on an external data resource without explicit authentication at the time the data is requested. 

The keys created can be referenced while configuring REST API or ETL connections and can also be used in processors like Multi URL API Load or Flexible REST API processors.

Overview  

In the credentials tab, all the existing keys will be listed in a descending order of modification time. Within the credentials overview, the user will see details like key name, the type of the key, connection name (if a key is referenced in a connection), the permissions he has, etc.

A user with full rights will be able to create, delete, edit and share the keys to different projects.

Please be mindful that user with respective rights may be able to access these credentials as well! So always make sure, especially if personal credentials are used, that user rights are set properly and accordingly.

Creating a Key

• First of all, navigate to the "Credentials" tab in ONE DATA. 
• Within the tab click on 'Create' from the left sidebar.
• A new window pops up and the 'Basic Auth' key type is selected by default.
  
• Fill in the mandatory information for the respective key type.
• Click on "Create". A new key is created and is now populated on top of the list in the credentials tab.

Important things to note when creating credentials:
- There are no restrictions for the password.
- Once a key is saved, the key type cannot be edited.
- A key cannot be deleted, unless the connections currently using the key are deleted.

Key Types

This section will explain the different key types for credentials.

Standard Methods

ONE DATA offers 

Basic Auth

This is the type for any basic authentication with a username and a password.

Custom Methods

These are the key types for the authentication for certain platforms. 

ONE DATA Auth

The ONE DATA authentication type is very useful when working with the ONE DATA API inside of your workflows.

With this credential type and the respective connection, you can authenticate requests by using the account information of a ONE DATA user.

Without these credentials you would need to save your JWT within a REST API Processor. This is problematic because authentication tokens can expire, which means you would need to update the workflow every time the token becomes invalid.

Personio Auth

This key type is for authentication in Personio. If you want to know how to enable authentication in Personio, take a look at this article.

It has the following required fields:

Microsoft ROPC (Resource Owner Password Credentials)

This is the key type for the authentication for Microsoft Services, for example the MS Graph API.

To be able to use this key type, you need to register ONE DATA / your Workflow via Microsoft Azure. If you already have an app registered, you can skip this part.

Register an application in MS Azure:

1. First, you need to click "New Registration" on the upper left of the part. In the appearing dialog, select a name and then an account type that fits your needs.
2. After that, you will be redirected to the configuration menu of the app. There you can see your "ClientId" (Application Id) and "TenantId" (Directory Id) in the center of the page.

• Under the "Authentication" tab in the side bar, you need to set the application to public, to be able to use ROPC.
• Under "Certificates & Secrets" you can generate your Client Secret.
• The last important point to mention is, that under "API Permissions" you can configure which information should be accessible via the registered application.

These are the required fields in ONE DATA to create credentials for MS ROPC:

Azure Blob Storage Auth

Google Cloud Platform Auth

The GCP Service Account used needs the role of Storage Object Viewer. 
While creating a Service Account in GCP (opens new window)a JSON file that provides all the necessary data will be provided.

Amazon Web Services Auth

The IAM user requires privileges s3:ListBucket and s3:GetObject.

Referencing a Key in a Processor

Similarly, within the Flexible REST API processor, under the 'AUTHENTICATION' section, the user can override the key provided by the Connection by selecting another key.

Invalid Keys After Import 

Confidential information (passwords, secrets, etc.) in Keys is replaced with dummy values during Project export. This means that resources that depend on the Keys will not work after the import of or update based on an exported Project.

Exposing Keys via API

Since ONE DATA version 74 (Server 48.0.0, Client 1.200.0) Credential Keys are now exposable. This means that their information (username, password, etc) can now be retrieved via API and used in Functions and Python Processors without having to write them in plaintext. Formerly, Keys were only used in OD's internal data processing, e.g. Workflows and Connections. The user was actually given no direct possibility to retrieve the plaintext Credentials after creating or editing one.

If the owner of a Credential decides to un-expose a Key, please be aware that any Function or Processor that requests and uses these Credentials will most likely fail during future executions.

Necessary Rights

To expose or unnexpose a Credentials, you have to be the owner of the Credential. Any user with WRITE access can still change the underlying information (e.g. username and password), but is not able to expose or un-expose the Key. 

Security Implications

Please also note that this has some security implications that should be considered. Any user with READ access to your exposed Credential will be able to see its plaintext.

How To Expose a Key

By default, all Credentials are un-exposed. When creating or editing a Credential, set it as exposed by ticking the checkbox "Expose Key".

An exposed Key is indicated in the Credentials list by a checkmark in the "Exposed" column.

How To Use an Exposed Key

The button beside the checkbox in the creation/edit dialog reveals an information box. It shows code snippets for using the exposed Key in Python Processors, Functions or locally (curl). 

If the Key has not yet been created, there is a placeholder for its ID inside the code. When editing an existing Key, its ID has been entered. The code snippets can just be copied and used as is or adapted to your specific use case.

Another way to get the Key ID for the snippets is to go to the Credentials list and perform the action "Copy Key ID to clipboard".

Example

The provided code snippets get and then print the Credentials. As an example, the Python code was run using a Function and shows the Key's properties as follows. The result will be the same for the other two options, just shown in a Processor or locally.

When using an unexposed Key, a message that the ID is not exposed is returned. The example snippets print this message. If the code had used the returned Credentials in some way, the Function would have failed since there is no returned "keyInformation".